在压缩后恢复上下文

当 Claude Code 压缩一段长对话时，摘要只保留大意，细节会被丢弃。压缩后恢复功能把这些细节找回来：每次压缩之后，一个 hook 会把你项目在 ContextForge 中最近的记忆和待办任务重新注入模型的上下文。自 contextforge-mcp 0.12.0 起提供。仅支持 Claude Code。

问题所在

长会话会填满上下文窗口。Claude Code 会压缩对话，无论是你手动运行 /compact 还是空间不足时自动触发。它保留的摘要擅长把握全局，却不擅长记住细节。通常丢失的恰恰是你接下来最需要的内容：

你一小时前做出的决定以及背后的原因。
哪些任务已完成、哪些仍在待办，以及约定好的下一步是什么。
你给智能体的纠正，现在它已悄悄忘记。

智能体并不知道自己丢了什么。 压缩之后它会像什么都没发生一样，继续基于摘要工作，所以偏差只会在它重新提出已解决的问题或推翻某个决定时才暴露出来。

工作原理

由两部分组成：一个 Claude Code hook 和一个 CLI 子命令。

1. 由 `init` 安装的 hook

npx contextforge-mcp init 现在会在项目的 .claude/settings.json 中添加一个带有 compact matcher 的 SessionStart hook。Claude Code 会在每次压缩之后立即运行它，并把命令的标准输出追加到模型的上下文中。

# .claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "npx -y contextforge-mcp recall" }
        ]
      }
    ]
  }
}

init 会合并到已有的 settings.json 中，不会改动其他键或其他 hook，并且是幂等的：重复运行会打印 "already present"。Cursor 没有 hook 机制，因此不会安装任何内容。

2. `recall` 子命令

contextforge-mcp recall 会解析你的 API 密钥（优先读取 CONTEXTFORGE_API_KEY，其次是 ~/.claude.json 中的 contextforge 服务器条目，最后是项目的 .mcp.json），从仓库根目录的 .contextforge 文件读取已关联的项目，获取该项目在所有空间中最近的 10 条记忆和最多 5 条待办任务，然后打印一段如下的纯文本块：

# npx contextforge-mcp recall 的输出

## ContextForge: context restored after compaction

Recent memories:
- [Decisions] Keep Supabase magic links, drop password login — Decided after the support thread on 2026-09-22. Password reset emails were the top ticket…
- [API] Rate limit is 60 requests per minute per key — Enforced in the edge function. Return 429 with a Retry-After header, never a 500…

Pending tasks:
- [f8drg2] Ship the billing webhook retry (high, due 2026-09-30)
- [k2m9xa] Write the 0.12.0 release notes (medium, due 2026-10-02)

For anything older or more specific, call memory_query before answering.

它绝不会阻塞会话。没有密钥、项目未关联、网络错误或超过 8 秒超时，都只会导致不输出任何内容并以退出码 0 结束。正常运行约需 4 秒。

新用户

无需额外操作。按照快速开始中的"初始化项目"步骤在项目中运行 init，hook 会随其他内容一起安装：

cd ~/your-project
npx contextforge-mcp init

现有用户

两步：升级到 0.12.0，然后在每个项目中重新运行一次 init。

1. 更新软件包

如果是全局安装，请更新它。如果一直只用 npx，下次启动就会得到 0.12.0。无论哪种情况都请检查版本，因为旧的全局安装会覆盖 npx：

npm update -g contextforge-mcp
npx contextforge-mcp --version   # expect 0.12.0 or newer

2. 在每个项目中重新运行 init

它只会添加缺失的 hook。你的 CLAUDE.md、其他 hook 和其他 settings 键都保持原样。

cd ~/your-project
npx contextforge-mcp init

想手动操作？ 把上面代码片段中的 hooks.SessionStart 组粘贴到项目的 .claude/settings.json 中。如果已经有 SessionStart 数组，请把该组追加进去，而不是替换它。

验证是否生效

在项目文件夹中直接运行该子命令。你应该会看到上面那样的文本块，内容是你自己的记忆和任务。输出为空表示没有密钥或项目未关联。
然后在 Claude Code 中运行 /compact，并提问 "what context did you just receive?"。智能体应能复述文本块中的记忆和任务。

cd ~/your-project
npx contextforge-mcp recall

要求与限制

仅支持 Claude Code。 hook 位于 .claude/settings.json。Cursor 没有 hook 机制，因此不会安装任何内容。
项目必须已关联。 仓库根目录需要有 .contextforge 文件。参见项目关联。
只会重新注入你保存过的内容。 文本块包含 ContextForge 中最近的 10 条记忆和最多 5 条待办任务。它无法告诉你压缩摘要丢弃了什么，因为它从不读取对话本身。
所以请随时保存决定。 在开始一段长时间的工作之前，让智能体"保存当前进度和下一步"。存进 ContextForge 的内容会回来；只存在于聊天中的内容不会。

故障排除

hook 运行了，但什么也没注入

shell rc 文件中残留的 export CONTEXTFORGE_API_KEY=... 优先级高于 ~/.claude.json。如果那个密钥已过期，hook 会静默地不输出任何内容。删除该 export 或替换密钥，然后重新运行 npx contextforge-mcp recall 确认。

钩子运行的是旧版本

旧的全局安装会让 npx -y contextforge-mcp 运行旧版本，而旧版本没有 recall 子命令。检查并更新：

which contextforge-mcp
npm update -g contextforge-mcp
npx contextforge-mcp --version

输出为空，但密钥没问题

项目未关联。仓库根目录必须有 .contextforge 文件。让智能体"关联项目"（它会使用 cf_tools），然后再次运行 recall。