Capn-hook 发布：让编码代理不再重复 grep

背景

在编程代理（coding agent）的使用中，一个常见的痛点在于：每个会话（session）之间，代理会“遗忘”之前探索过的信息。例如，当开发者询问“支付 webhook 在哪里处理？”时，代理可能需要花费数分钟遍历代码库才能找到答案（如 src/api/webhooks.ts 以及 src/billing/handlers/ 中的处理函数）。然而，一旦会话结束，这些昂贵探索的成果就消失了，下一次会话又要从头开始，浪费 token 和时间。

传统的解决方式是通过 grep 或手动搜索，但每次重复探索的成本高昂，且无法在代码变更时自动过期。针对这一问题，开发者推出了一款名为 Capn-hook 的开源工具，旨在为编码代理提供持久记忆，避免重复“grep 同一个谜题”。

核心内容

Capn-hook 是一个轻量级的 CLI 工具，它赋予编码代理（如 Claude Code、Codex）在会话间保留探索成果的能力。其核心机制围绕三个简单命令展开：

1. capn ask – 在搜索代码库之前，先向 capn 询问。如果之前有保存的答案，它直接返回包含精确文件路径的 JSONL 结果，跳过整个搜索过程；如果未命中，则快速退出（仅耗几秒），并提示代理去探索并记录发现。

2. capn chart – 当代理通过艰难探索得到答案后，使用该命令记录一个简短、可回答的问题以及作为答案的文件列表。支持附加行号、陷阱说明等细节。例如：

   capn chart "where are payment webhooks handled?" \
     --files src/api/webhooks.ts,src/billing/handlers/stripe.ts \
     --details "Router starts near line 40; Stripe handler owns signature checks."
   

   每个被记录的文件在保存时会计算 SHA256 指纹。最佳实践是保持图表（chart）原子化，将可分离的事实拆分为不同的图表，但多个文件可以共同回答一个聚焦的问题。

3. 自动失效 – 如果任何支持文件发生变更或消失，对应的条目会被自动删除，从而确保答案永远不会返回过时信息。仅支持 chart 和 unchart，不支持 update：一旦代码库（如同海岸线）变化，旧图表被丢弃，下一次遇到时重新绘制。

整个系统无需守护进程或服务器，完全本地优先。通过 capn init 可安装一个会话启动钩子（hook），代理在每次新建会话时会看到一条简短提示：在搜索代码库前先询问 capn，在艰难发现后保存结果。该提示（capn context）就是完整的集成点——没有包装器、无中间件、无强制行为，模型读取后自行决定。

技术实现：

• 索引使用 QMD（语义混合搜索，默认）或纯关键词 BM25（通过 capn init --no-embedding 启用）。默认路径首次使用会下载约 300MB 的嵌入模型（全混合管线约 2GB），冷启动的 capn ask 可能需要几秒；BM25 路径不下载任何东西，完全确定性。
• 存储在 .capn/ 目录下，每个条目是一个 Markdown 文件（entries/<id>.md），人类可读；此外有基于 SQLite 的索引（.capn/qmd/index.sqlite），通过 QMD SDK 在进程内隔离运行，与宿主机的 QMD 实例互不干扰。
• 所有 .capn/ 被 gitignore，记忆仅保存在本地工作副本中。
• 核心 CLI 用 JavaScript 编写，优先运行于 Bun，回退到 Node.js。

性能验证：在 5 个生产代码库（Dub、Polar、PostHog、Twenty、Documenso）上，针对 60 个真实开发者问题进行了实验。使用 capn 回忆的代理比从头探索的代理少用 77% 的 token，且两组答案均完全正确。在所有 60 个问题上，右侧图表都能正确回忆，大约在 1.6 次回忆后就能收回图表会话的成本。

关键要点

• 持久记忆：编码代理在会话间保留探索成果，避免重复探索，显著节省 token 和时间。
• 自动过期：基于文件内容哈希（SHA256）判断答案是否陈旧，文件一变化条目自动删除，答案永不返回过时信息。
• 原子化记录：鼓励将不同事实拆分为独立的图表（chart），而不是大块上下文转储；多个文件可联合回答一个聚焦问题。
• 轻量集成：通过一个启动钩子（capn init）即可与 Claude Code、Codex 等代理集成；代理读取一段简短提示后自主决定何时询问或保存。
• 本地优先，无服务器：全部数据存储在本地 .capn/ 目录，通过 SQLite 索引和 QMD SDK 实现进程内语义搜索，无守护进程。
• 代理无关：CLI 和图表格式不依赖特定代理；钩子仅为薄适配层，其他代理可通过调用同一 CLI 集成。
• 两种搜索模式：默认使用 QMD 语义混合搜索（需下载嵌入模型，首次稍慢），可选纯 BM25 关键词搜索（零下载，速度快且确定性高）。
• 实验数据支撑：在 5 个生产代码库上，回忆模式比冷探索 token 减少 77%，且准确率相同；约 1.6 次回忆即可覆盖图表成本。
• MIT 开源许可。

意义与影响

Capn-hook 直击编码代理在实际开发中面临的核心效率瓶颈——会话间记忆丢失。通过提供一种轻量、自愈、基于文件内容哈希的持久记忆层，它让代理能够像人类开发者一样，从过去的探索中受益，而无需为重复发现支付相同的时间与 token 成本。

其设计哲学值得关注：

• 不试图完美管理状态，而是采用“图表即海岸线”的隐喻：变化发生时直接废弃旧图表，代理重新绘制。这种容错机制避免了复杂的版本控制和编辑逻辑。
• 答案永远不会过时，因为内容哈希保证了任何文件修改都会自动触发条目失效。这比靠人工判断或时间戳过期更可靠。
• 本地优先和代理无关的架构使它能无缝融入现有工作流，无需外部服务或复杂配置。

对于使用编码代理进行日常开发的团队而言，Capn-hook 提供了一种实用、可落地的方法来提升代理的效率。随着 AI 辅助编码的普及，类似“记忆层”的工具可能会成为标准组件，帮助代理从一次性查询工具进化为能积累知识的长期伙伴。