写入与召回：ingest、recall、show、chain

你将得到什么

• 用官方 memorable ingest（任意 harness 的 trace JSON）写入一条 procedure
• 用 recall → show 验证召回与 guarded 渲染
• 理解多子目标时的 chain，并用 list / prune / disable 做日常运维

开始前准备

1. 已完成第 1 课：login 成功，enable 为 read-write。
2. 在一个真实项目目录里操作（chain 的依赖只在「动过同一批文件」的 procedure 之间成立）。
3. 本课先用官方最小 ingest 样例跑通；再接到你自己的 agent 轨迹。

步骤 1：用 ingest 写入第一条 procedure

官方 CLI：任意 harness 把 trace 交给 Memorable：

memorable ingest - <<'JSON'
{
  "session_id": "run-183",
  "task_description": "rotate the TLS cert",
  "harness": "my-orchestrator",
  "tool_calls": [
    {
      "name": "shell",
      "input": { "command": "certbot renew" },
      "result": { "ok": true }
    },
    {
      "name": "shell",
      "input": { "command": "nginx -s reload" },
      "result": { "ok": true }
    }
  ]
}
JSON

对照结果：命令成功结束并给出 slug（或「refreshed / new revision」一类说明）。若 consent 不是 read-write，会拒绝并提示先 enable。

要点（官方）：

• result 只在真实已知结果时填写，不要猜。
• 一次 ingest = 一个 prompt 及其后续 tool calls；不要整段 session 糊成一条。
• harness：已知名如 claude-code / codex / opencode 有 curated 工具表；其它字符串仍可用，但非 shell 步骤可能记成更薄的 other。若你手搓的轨迹工具名对齐 Claude Code（Read / Write / Edit / Grep / Glob / Bash），官方建议 "harness": "claude-code"。

也可：

memorable ingest trace.json

步骤 2：list 确认已存

memorable list

对照结果：列出 slug、当前偏好的 revision、被 recall 次数与后续是否顺利等信息。需要全 revision：

memorable list --all

脚本可用：memorable list --json。

步骤 3：recall → show

官方「两分钟到首次召回」示例路径：

memorable recall "rotate the TLS cert"

对照结果（有命中时大致类似官网示例）：

0.86 procedures/…-rotate-the-tls-cert [lexical]

或带 exact / semantic 标注。未命中则提示 no matching procedures，此时按正常推理做任务即可。

对顶部命中执行：

memorable show procedures/REPLACE_WITH_YOUR_SLUG

对照结果：打印 guarded 渲染——改动了哪些文件、哪条命令验证成功等；并明确标成 reference data，不是 instructions（官方防注入设计）。Agent 应核对是否仍匹配当前任务，再决定是否跳过已做过的排查。

强制模式：

memorable recall --single "rotate the TLS cert"
memorable recall --chain "rotate the TLS cert"

步骤 4：多子目标用 chain

官方：长任务很少是「整段重放」，而是若干已会步骤的新组合。recall 会在 single 与 chain 间自动选择；也可直接：

memorable chain "add the POST refunds endpoint and then cover it with tests"

对照结果（官网示例结构，slug/文件名随你库内内容变化）：

4 procedures - 3 artifact edges - 2 segment(s) - coverage 100%
   1. [bridge] Create the refunds database migration
         verified by: bun run migrate
   2. [bridge] Add the refund model
         needs: migrations/003_refunds.sql
         verified by: bun test models
   3. Add the POST refunds endpoint with validation
         needs: src/models/refund.ts
         verified by: bun test routes
   4. Cover the refunds endpoint with tests
         needs: src/routes/refunds.ts
         verified by: bun test refunds

阅读规则（官方）：

• 标成 [not asked for; a later step needs what it produces] / bridge 的步骤：是依赖前置，不要跳过。
• 出现 not covered by memory：该段要现推，不要硬套邻近 procedure。
• 标注可并行的步骤：彼此无文件依赖。

查看将注入的原文块：

memorable chain "add the refunds endpoint and then cover it with tests" --render

步骤 5：召回如何匹配（建立正确预期）

官方三层（Docs / CLI）：

1. exact — 路径 / 命令等标识符
2. lexical — 共享词元
3. semantic — 仅在前两层未中时才跑向量（bge-m3 等；标题嵌入，不嵌文件内容）

多数查询可离线完成 exact + lexical；语义层需要 extraction / embedding 可用。memorable doctor 会断言语义层是否真的配好，而不是只看 API 200。

步骤 6：日常运维与同意开关

memorable status
memorable doctor

清理（官方：任何 consent 模式都可 prune，包括 deny）：

memorable prune --dry-run --stale
memorable prune --dry-run --superseded
memorable prune REPLACE_SLUG

• --stale：写过的文件在本树已不存在
• --superseded：试过并输掉的旧 revision

暂时停止写入、仍要召回：

memorable disable

彻底关掉（含 recall）：

memorable forget

对照结果：status 中 consent 变为 read-only 或 deny；之后 ingest 会被拒绝（设计如此）。

步骤 7（选读）：Extraction API 与 MCP

若你在自建 harness、无 Node，可按 API Reference 对

https://memorable-extraction-api.memorable.workers.dev

发 POST /v1/extract（Bearer mk_…），本机自行保存 draft。字段约束与 CLI ingest 一致：只送允许的 tool 参数字段与 outcome，不送正文/凭证。

本机只读 MCP：CLI 提供 memorable mcp（stdio JSON-RPC）。官网 FAQ 称只读 MCP 暴露一组工具；课程主路径以 CLI recall/show 为准。需要时在支持 stdio MCP 的客户端里把启动命令设为：

memorable mcp

（或 npx memorable-cli@latest mcp。）

本课检查清单

• memorable ingest 成功写入至少 1 条，并出现在 memorable list
• memorable recall "…" 能命中，或明确返回 no matching procedures
• memorable show <slug> 输出 guarded 参考块
• 理解 chain 的 bridge / gap / 并行标注
• 会用 disable / forget / prune --dry-run

延伸阅读（官方）

• Docs overview
• CLI reference
• Extraction API
• memorable.sh
• 站内工具页：https://www.kun.net/tools/memorable/