agent-carnet

Agent Carnet

一个轻量的命令行工具，可在磁盘上的 .carnet/<category>/<slug>.md 路径下提供共享的 Markdown 笔记本。笔记默认保留 30 天，每次被读取或应用时都会重置计时；有用的笔记会被保留，过时的笔记会自动移入 .trash/。

快速参考

# Save (always pass --summary and --agent claude-code)
echo "body content" | agent-carnet save deps/iconv-issue \
  --summary "iconv-esm v0.7 types broken — pin to v0.6" \
  --agent claude-code \
  --tags compat,esm

# Recall
agent-carnet find iconv               # search summaries (does NOT bump lifespan)
agent-carnet list                     # category-grouped overview, sorted by last_used
agent-carnet list --sort use_count    # most-applied notes first
agent-carnet show deps/iconv-issue    # read full content (bumps last_used; weak use signal)

# Mark as actually applied (strong use signal — bumps last_used + use_count)
agent-carnet used deps/iconv-issue

# Maintain
agent-carnet move <from> <to>
agent-carnet rm <path> --yes

如果不确定某个子命令的完整参数，请运行 agent-carnet <command> -h（例如 agent-carnet save -h、agent-carnet used -h）。每个子命令都会打印其专属的帮助信息，包括必填参数、选项和示例，且不会执行任何文件系统操作。

何时保存

当你发现值得跨会话保留的内容时，应主动保存：

• 耗费精力推导出的研究结论
• 代码库中不易察觉的模式或陷阱
• 棘手问题的解决方案
• 架构决策及其背后的理由
• 可能会在之后恢复的进行中工作

何时回忆

在开始相关工作前，或当可能已存在相关上下文时：

• agent-carnet find <topic> —— 快速浏览摘要
• agent-carnet list <category> —— 浏览某个文件夹
• agent-carnet show <path> —— 实际阅读（会重置 last_used；仅在内容确实重要时使用）

何时调用 used

当某条笔记确实影响了你的工作之后，调用 agent-carnet used <path>：

• 你应用了记录的修复方案，并且它解决了问题。
• 你在重试某个假设前查阅了笔记，并避开了一条死胡同。
• 你在新代码中使用了 vocab 笔记中的规范名称，而不是自己发明新名称。

used 会增加 use_count——这是一个持久的重要性信号，可跨会话保留，并让后续读者（以及 agent-carnet list --sort use_count）发现承载关键信息的笔记。

仅阅读笔记不计入。show 会让笔记保持活跃（弱信号）；used 则记录该笔记因真正的原因而值得保留（强信号）。

硬性规则

• --summary 为必填项。请写得明确果断——单独阅读摘要时，下一位读者（或下一个 Agent）应能判断是否需要继续阅读。
• --agent claude-code 为必填项。
• find 不会更新任何字段。show 会更新 last_used。used 会同时更新 last_used 并增加 use_count。
• updated 仅记录内容修改（save、save --update）。它与 last_used 相互独立，也不是生命周期的驱动因素。
• 30 天过期是自动的——请勿手动清理。keep: true 可将笔记永久固定保留。
• 每次运行命令行时都会自动执行清理；被删除的笔记会进入 .carnet/.trash/，保留 7 天后才会被彻底删除。

路径约定

• <category>/<slug> —— 使用 kebab-case（短横线连接的小写），不带前导斜杠，不含 ..。
• 分类即文件夹；可根据需要随意新建。
• 允许使用子分类：例如 deps/esm/iconv-issue 是有效的。

何时阅读 references/

本 SKILL.md 足以应对日常的笔记管理。仅当符合以下特定情况时才打开 references/ 下的文件——它们不是常驻上下文，请勿无故加载。

阅读此文件	适用情况
references/cookbook.md	你即将使用（或被问及）某种基于标签的模式，例如用于项目术语的 tags: [vocab]，或用于调试死胡同的 tags: [hypothesis]。该文件展示了完整模式，包括如何为该模式组织正文和 meta:。
references/frontmatter.md	你需要编写或读取 meta: 扩展命名空间，设置非常规的 lifespan / keep，或想了解为何某个不熟悉的 frontmatter 字段在保存时被保留或未被保留。

如果以上情况均不适用，请勿阅读 references/。本文件的基础内容已涵盖日常的 save/find/show/touch/move/rm 流程。