Contextforge

ContextForge MCP — Claude、Cursor 和 Copilot 的持久记忆

通过 Model Context Protocol（MCP），让 Claude Code、Cursor 和 GitHub Copilot 在不同会话间保留持久记忆。不必每次都重新解释你的项目。

ContextForge MCP 是一款开源 MCP 服务，可将你的 AI 编码助手连接到长期、可搜索的记忆。决策、架构说明、调试上下文和项目知识，在每个会话中都能使用——并适用于所有支持 MCP 的工具。

• 🧠 持久记忆 — AI 会在数天乃至数周的不同会话中记住所有内容
• 🔍 语义搜索 — 根据含义而非关键词查找知识
• 🔗 一份记忆，适用于所有工具 — Claude Code、Cursor、Copilot、Claude Desktop、Windsurf
• 🐙 Git 集成 — 自动同步提交和 PR
• ✅ 任务跟踪 — 问题、分配和项目状态
• 👥 团队协作 — 与团队共享项目和记忆
• 🆓 免费套餐 — 无需信用卡即可开始使用

说明

自动生效，无需配置（v0.5.1+）。 连接后，服务会向 AI 客户端发送启动说明。支持这些说明的客户端（Claude Desktop、Claude Code）会在每次会话开始时加载项目记忆，并主动保存新的决策——无需编辑任何设置。现在，运行 init（步骤 4）是增强措施，而非必需步骤；对于尚不支持服务端说明的客户端（例如 Cursor），运行它仍然有帮助。

---

快速开始

1. 安装

无需安装步骤——以下设置会通过 npx -y contextforge-mcp 运行服务，并在需要时获取最新版本。

想要更快的冷启动速度，并倾向于全局安装？可以选择运行 npm install -g contextforge-mcp；如果安装了，就可以从下面的命令中省略 npx -y 前缀。

2. 获取 API 密钥

1. 前往 contextforge.dev
2. 注册（提供免费套餐）
3. Settings → API Keys → Generate API Key
4. 复制你的密钥（以 cf_ 开头）

3. 连接到你的 AI 工具

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

重启 Claude Desktop。

Claude Code（CLI）

claude mcp add contextforge -s user \
  -e CONTEXTFORGE_API_KEY=your-api-key-here \
  -- npx -y contextforge-mcp

重启 Claude Code，然后运行 /mcp 验证是否已连接。

Cursor

添加到 Cursor MCP 设置中：

{
  "mcpServers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

GitHub Copilot（VS Code）

添加到 Copilot MCP 配置中：

{
  "servers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. 初始化项目（推荐）

从 v0.5.1+ 开始，服务会在支持的客户端上自动加载记忆（参见顶部的说明），因此此步骤可选，但建议执行：它可以强化这一行为，覆盖不遵循服务指令的客户端，并完全覆盖内置的基于文件的记忆。

设置项目，让你的 AI 编辑器始终优先使用 ContextForge 记忆：

npx contextforge-mcp init

默认情况下，init 会自动检测项目使用的编辑器，并写入三个规则部分和两个钩子：

• 记忆规则 — 将记忆相关问题交由 ContextForge 处理，而不是使用内置的文件记忆
• 会话在线状态规则 — 要求并行会话在对话开始时以及进行重大更改前相互检查
• 启动上下文规则 — 在每次对话开始时，从 ContextForge 加载简短的项目摘要（概览、待处理任务、活动会话）
• 压缩后回忆钩子（仅限 Claude Code）— 在 .claude/settings.json 中添加一个匹配器为 compact 的 SessionStart 钩子。当 Claude Code 压缩较长的对话时，该钩子会运行 npx -y contextforge-mcp recall，并重新注入会话目标、与你当前工作相关的记忆、项目中最近的 10 条记忆以及待处理任务，确保保存在 ContextForge 中的决策在摘要后仍然保留。
• 会话目标钩子（仅限 Claude Code，0.13.0）— 添加一个 UserPromptSubmit 钩子，通过普通的 node 运行生成的脚本 .claude/hooks/contextforge-objective.cjs（约 50 ms）。它会在你的设备上将提示词记录到 ~/.contextforge-mcp/sessions/<session_id>.jsonl，这样 recall 就能在压缩后恢复会话目标。日志会在 14 天后清理，且绝不会上传；关于 recall 会发送哪些内容，请参见下方的隐私说明。

写入的文件：

• Claude Code 使用 CLAUDE.md（检测标志：已有 CLAUDE.md 或 .claude/ 目录）
• Cursor 使用 .cursorrules（检测标志：已有 .cursorrules 或 .cursor/ 目录）
• Claude Code 使用 .claude/settings.json — 合并写入，绝不覆盖；只添加两个 ContextForge 钩子组
• Claude Code 使用 .claude/hooks/contextforge-objective.cjs — 生成的目标钩子脚本（可安全提交；发布新版本时会由 init 更新；Claude Code 自身的系统轮次——以类 XML 标签开头并包含闭合标签的提示词——不会被记录）

如果未检测到编辑器，则会生成这两个文件。

对于遵循服务指令的客户端（Claude Desktop、Claude Code），即使不执行此步骤也会自动使用 ContextForge。对于其他客户端，或者要确保内置的基于文件的自动记忆不会优先生效，请运行 init：它会写入明确的规则，始终将记忆相关请求交由 ContextForge 处理。

使用 --editor 覆盖设置

标志	行为
--editor=claude	仅生成 CLAUDE.md
--editor=cursor	仅生成 .cursorrules
--editor=all	生成两者，跳过检测

重复运行 init 时，各部分均具幂等性 — 已有的部分保持不变；缺少的部分会追加。要从旧版本升级？只需重新运行 npx contextforge-mcp init：它会添加新的启动上下文部分，而不改动文件的其他内容。

查看版本

npx contextforge-mcp --version   # also: -v, version

打印已安装的版本（例如 contextforge-mcp 0.5.2）。

应对压缩（Claude Code）

长会话会被压缩：Claude Code 会总结对话以释放空间，摘要会保留大意，但会丢失细节——通常是决策，而且经常连任务本身也会丢失。init 会安装两个钩子来解决这两个问题：

1. 目标钩子（UserPromptSubmit）——在本地记录每条提示词，确保会话中的第一个实际请求不会被摘要遗漏。
2. 回忆钩子（SessionStart，匹配器 compact）——每次压缩后立即触发，并按以下顺序输出：会话目标和压缩前的最新请求；最多 5 条与当前工作相关的记忆（基于目标、git 分支、近期提交主题和已更改文件进行语义搜索，不限记忆时间）；项目最近的 10 条记忆；最多 5 个待处理任务；以及提醒你对更早的内容调用 memory_query。整个区块约为 4 KB，只注入一次，且不会固定，因此不会改变压缩触发时机。

相关性搜索在每次压缩时会执行一次计量查询。只有在存在会话目标或当前位于非默认分支时才会运行（仅在 main 上使用 git 上下文会产生噪声）。它会与其他获取操作并行运行，共用 6 秒的阶段时限，因此缓慢的搜索不会导致区块中的其余内容丢失。在环境中设置 CONTEXTFORGE_RECALL_RELEVANCE=0 可彻底关闭此功能。

这些钩子以普通 shell 命令运行，因此 recall 会按以下优先顺序读取 API 密钥：如果已设置，则读取 CONTEXTFORGE_API_KEY；否则读取 ~/.claude.json 中的 contextforge 服务条目（claude mcp add 会将密钥存储在此处）；否则读取项目的 .mcp.json。项目必须已关联（仓库根目录下有 .contextforge）。如果缺少任何内容，它就不会输出任何内容，也不会阻塞会话。请注意，shell 配置文件中导出的 CONTEXTFORGE_API_KEY 优先于 ~/.claude.json：如果其中存的是旧密钥，回忆钩子会静默地不输出任何内容。

在项目目录中手动试用：

npx contextforge-mcp recall           # prints the block for the newest session in this directory
npx contextforge-mcp recall --stats   # local numbers: recalls, objective coverage, follow-up queries

隐私：提示词日志和回忆统计数据存储在你机器上的 ~/.contextforge-mcp/ 下，绝不会上传。离开机器的数据：压缩后，recall 会将会话目标（最多 600 个字符，并附带 git 分支、近期提交主题和已更改文件名）作为搜索查询发送给 ContextForge，方式与 memory_query 发送查询相同；这些数据不会被存储。请注意，.claude/settings.json 通常会提交到仓库，因此拉取该仓库的团队成员也会获得提示词钩子；他们可以移除 UserPromptSubmit 组以选择退出。

已在使用 ContextForge？（现有用户）

无需重新配置。更新到最新版本并重启 AI 客户端：

npm update -g contextforge-mcp   # only if you installed globally; npx users get it on next launch

自动加载功能无需重新运行 init。若要启用压缩后的回忆钩子和会话目标钩子，请在每个项目中运行一次 npx contextforge-mcp init；它只会添加缺少的内容。从 0.13.2 起，如果已安装回忆钩子但目标钩子缺失或已过时，服务会在每个项目中提醒你一次。

---

可用工具

ContextForge 在知识管理、GitHub 集成、问题跟踪和协作领域共定义了 69 个工具。从未移除任何功能——以下所有工具均可完整调用；但从 v0.11.0 起，AI 客户端默认只能看到其中 11 个（CONTEXTFORGE_TOOLS=lean，这是默认值）：

• 10 个核心工具——Agent 在每次会话中都会主动使用的工具：memory_query、memory_ingest、memory_check_freshness、memory_confirm、memory_correct、memory_forget、tasks_list、tasks_what_next、session_list、memory_help。
• cf_tools——一个用于发现和运行其他 59 个工具的网关工具。像平常一样向 AI 提出请求（“同步我的 git 提交”、“从快照恢复”、“olvida ese recuerdo viejo”），它会搜索（支持英语或西班牙语）并调用合适的工具——无需知道确切名称。

设置 CONTEXTFORGE_TOOLS=full，即可改为向客户端直接公开全部 69 个工具，恢复 0.11.0 之前版本的行为。请参阅环境变量。

默认采用精简模式的原因：69 个工具架构在每次会话中会占用约 15,000 个上下文词元，超过 Cursor 的 40 个工具上限，而且当工具数量超过约 50 个时，还会导致多个客户端的准确性下降。精简工具集将占用量降至约 3,500 个词元（减少约 77%），同时仍可通过 cf_tools 一次调用即可使用所有工具。

知识管理

工具	描述
memory_ingest	将知识保存到记忆中
memory_query	通过语义搜索知识
memory_list_items	列出所有已存储的条目
memory_delete	删除指定条目
memory_ingest_batch	一次保存多个条目
memory_delete_batch	按筛选条件删除条目

空间与项目

工具	描述
memory_list_spaces	列出你的空间
memory_create_space	创建新空间
memory_delete_space	删除空间
memory_move_space	将空间移至项目
memory_list_projects	列出你的项目
memory_create_project	创建新项目
memory_delete_project	删除项目
memory_link_project	将目录关联到项目
memory_unlink_project	取消关联目录
memory_current_project	显示已关联的项目

GitHub 集成

工具	描述
memory_git_connect	连接 GitHub 仓库
memory_git_list	列出已连接的仓库
memory_git_activate	启用／停用 Webhook
memory_git_sync	导入现有历史记录
memory_git_commits	列出已同步的提交
memory_git_prs	列出已同步的 PR
memory_git_disconnect	断开仓库连接

问题跟踪

工具	描述
issues_list	列出你的问题
issues_create	创建新问题
issues_start	标记为进行中
issues_resolve	标记为已解决
issues_resolve_by_name	按标题解决问题
issues_assign	分配给协作者
issues_what_next	获取建议

协作

工具	描述
project_share	通过电子邮件共享项目
collaborators_list	列出协作者

快照与导出

工具	描述
memory_snapshot_create	创建备份
memory_snapshot_list	列出所有快照
memory_snapshot_restore	从备份恢复
memory_snapshot_delete	删除快照
memory_export	导出为 JSON/MD/CSV
memory_import	从文件导入

实用工具

工具	描述
memory_stats	查看使用统计信息
memory_relate	关联两个条目
memory_help	显示帮助

---

会话状态（多会话协调）

并行运行多个 Claude Code 会话（工作树、Agent 团队）？ 每个 MCP 进程都会自动注册为一个活动会话，并在运行期间 发送心跳。正常退出时，会话会立即移除 （即使主进程正在被终止，独立辅助进程也会发送告别消息）；如果进程突然崩溃，会话会在最后一次心跳约 10 分钟后过期。Agent 可以通过三个工具进行协调——session_list 是核心工具，始终可见；默认情况下，session_update 和 session_end 通过 cf_tools 网关调用（或者设置 CONTEXTFORGE_TOOLS=full，直接查看全部三个工具）：

工具	功能
session_update	声明此会话正在处理的内容（“正在处理 auth 模块”）
session_list	查看同一项目中的其他活动会话及其关注点，以便在修改共享区域前进行协调（传入 all_projects: true 可查看整个组织）
session_end	明确结束此会话状态（退出时也会自动结束）

默认情况下，session_list 的范围限定为当前项目——这是实际发生工作冲突的地方。在多项目组织中，传入 all_projects: true 可查看所有会话，或者传入 project: "<name-or-id>" 将范围限定到其他项目。

建议在 CLAUDE.md 中采用以下模式：对话开始时调用 session_list；开始或切换任务时调用 session_update。

---

自然语言示例

你无需记住命令——只需自然地向 AI 交流：

# Knowledge
"Save this: we use PostgreSQL for the main database"
"What database do we use?"
"List my spaces"

# GitHub
"Connect my repo github.com/myuser/myproject"
"What commits did I make today?"
"Show PRs merged this week"

# Issues
"Create an issue: Update the login page design"
"What's pending?"
"What should I work on next?"
"Mark the login issue as done"

---

环境变量

变量	必需	说明
CONTEXTFORGE_API_KEY	是	从控制面板获取的 API 密钥
CONTEXTFORGE_API_URL	否	API 端点（默认为生产环境）
CONTEXTFORGE_DEFAULT_SPACE	否	操作的默认空间
CONTEXTFORGE_TOOLS	否	lean（默认）公开 11 个工具——最常用的 10 个，以及用于调用其余 59 个工具的 cf_tools 网关。full 公开全部 69 个工具，与 0.11.0 之前的版本相同。精简模式可使 ContextForge 保持在 Cursor 的 40 个工具上限和 Claude Code 的 50 个工具性能下降阈值以内。

---

工作原理

ContextForge MCP 是一个轻量级客户端，可将 Model Context Protocol 工具调用转换为经身份验证的 HTTP 请求，并发送到 ContextForge API。你的知识会存储、建立索引（语义嵌入），并在服务端检索——MCP 客户端本身是无状态的。

这意味着：

• 无需管理基础设施——无需本地数据库，无需运行嵌入模型，无需维护向量存储
• 适用于 AI 可用的所有环境——Claude Code、Cursor、Copilot 等可共享相同的记忆
• 团队协作——共享项目实时同步

---

控制面板

在 contextforge.dev 直观管理你的记忆：

• 查看并整理你的知识
• 搜索和筛选记忆
• 管理 API 密钥和账单
• 跟踪问题并协作
• 导出和备份数据

---

开发

# Clone and install
git clone https://github.com/alfredoizdev/contextforge-mcp.git
cd contextforge-mcp
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

---

参与贡献

欢迎在 github.com/alfredoizdev/contextforge-mcp 提交问题和拉取请求。

---

支持

• 📖 文档
• 🐛 报告问题
• 💬 问题咨询：[email protected]

---

许可证

MIT © Alfredo Izquierdo