用途
Agent Carnet 是一个小型 CLI 工具，为智能体提供一个存放在磁盘上的共享 Markdown 笔记本。笔记以 .carnet/<category>/<slug>.md 的形式组织。每条笔记默认拥有 30 天生命周期，每次被读取或应用时都会重置该期限；有用的笔记会存活下来，过期的笔记会自动漂移到 .trash/ 目录。
主要能力
- 保存笔记：通过管道输入正文内容，并附带摘要、智能体标识和标签。
- 查找与浏览：
find搜索摘要（不会延长生命周期）；list按分类分组展示概览，可按last_used或use_count排序；show读取完整内容（会更新last_used，属于弱使用信号）。 - 标记实际应用：
used命令表示笔记真正影响了工作，会同时更新last_used并递增use_count（强使用信号）。 - 维护操作：
move移动笔记，rm --yes删除笔记。 - 自动清理：30 天过期自动执行，无需手动清理；
keep: true可固定永久笔记。每次 CLI 调用都会运行自动修剪，被删除的笔记先进入.carnet/.trash/，7 天后硬删除。
使用方式
保存笔记（必须传入 --summary 和 --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
查找与浏览：
agent-carnet find iconv # 搜索摘要（不会延长生命周期）
agent-carnet list # 按分类分组概览，按 last_used 排序
agent-carnet list --sort use_count # 最常被应用的笔记优先
agent-carnet show deps/iconv-issue # 读取完整内容（更新 last_used；弱使用信号）
标记为实际应用（强使用信号，更新 last_used 并递增 use_count）：
agent-carnet used deps/iconv-issue
维护：
agent-carnet move
agent-carnet rm --yes
当不确定某个子命令的完整参数集时，运行 agent-carnet <command> -h（例如 agent-carnet save -h、agent-carnet used -h）。每个子命令会打印自己的聚焦帮助，包含必需参数、选项和示例，且不会触发文件系统操作。
适用场景
何时保存：当发现值得跨会话保留的内容时应主动保存，包括：需要努力才能得出的研究发现；代码库中不明显的模式或陷阱；棘手问题的解决方案；架构决策及其背后的理由；可能稍后继续的进行中工作。
何时召回：在开始相关工作或可能存在上下文时，使用 find <topic> 快速扫描摘要，list <category> 浏览文件夹，show <path> 实际读取（会重置 last_used，仅在内容重要时使用）。
何时调用 used：当笔记真正影响了工作时调用，例如应用了记录的修复并解决了 bug；在重试假设前查阅笔记从而跳过死胡同；在新代码中使用 vocab 笔记中的规范名称而非自创名称。used 递增 use_count，这是一个跨会话持久的 importance 信号，让未来的读者（以及 agent-carnet list --sort use_count）能浮现出关键笔记。
限制与规则
--summary为必填项，应写得果断明确，让下一个读者（或下一个智能体）仅凭摘要就能判断是否继续阅读。--agent claude-code为必填项。find不会更新任何字段；show更新last_used；used更新last_used并递增use_count。updated仅跟踪内容修改（save、save --update），独立于last_used，不是生命周期的驱动因素。- 30 天过期是自动的，不要手动清理；
keep: true可固定永久笔记。 - 路径约定：
<category>/<slug>使用 kebab-case，无前导斜杠，无..；分类即文件夹，可自由创建；允许子分类，如deps/esm/iconv-issue。 - 关于
references/文件：日常笔记记录只需本 SKILL.md。仅当涉及基于标签的模式（如项目术语的tags: [vocab]或调试死胡同的tags: [hypothesis]）时读取references/cookbook.md；仅当需要写入或读取meta:扩展命名空间、设置非平凡的lifespan/keep，或理解某个陌生 frontmatter 字段在保存时是否被保留时，读取references/frontmatter.md。若两者都不适用，不要读取references/。