快速开始

5 分钟内完成 ContextForge 的配置。支持 Claude Code、Claude Desktop、GitHub Copilot 和 Cursor。

claude -c

继续单次对话，记忆仅保留在该会话中。适合在单个项目上进行短期工作。

claude + ContextForge

跨所有对话和所有项目的持久记忆，永久可搜索。

前提条件

Node.js 18 或更高版本
Claude Code、Claude Desktop、带 Copilot 的 VS Code 或 Cursor
ContextForge 账户（提供免费套餐）

第一步：创建账户

注册免费的 ContextForge 账户以获取 API 密钥。

创建免费账户

第二步：获取 API 密钥

注册后，前往设置 → API 密钥，创建一个新密钥。

您的 API 密钥格式如下： cf_live_xxxxxxxxxxxxxxxx

第三步：安装 ContextForge MCP

使用 npm 全局安装 ContextForge MCP 服务器。

npm install -g contextforge-mcp

还有两个必要步骤——两者缺一不可，记忆功能才能正常运行：

将 ContextForge 连接到您的编辑器 使用您刚刚创建的 API 密钥——这是唯一需要用到密钥的步骤。在下方选择您的编辑器（Claude Code、Claude Desktop、Cursor 或 Copilot）。
初始化每个项目 使用 npx contextforge-mcp init （下一步），让 AI 真正使用 ContextForge 而非其内置记忆。

顺序不限——但仅创建 API 密钥并不会完成连接。

第四步：初始化项目（必须）

在每个需要持久记忆的项目目录中运行此命令：

cd ~/your-project
npx contextforge-mcp init

此命令会写入特定于编辑器的规则，告知 Claude Code 和 Cursor 使用 ContextForge MCP 而非其内置的基于文件的自动记忆。

若跳过此步骤，即使 MCP 已连接，AI 也会默默忽略 ContextForge 的记忆查询 ——因为内置自动记忆默认优先。

写入内容

默认情况下， init 会自动检测项目使用的编辑器：

写入文件	适用编辑器	检测条件
`CLAUDE.md`	Claude Code	存在 `CLAUDE.md` 或 `.claude/`
`.cursorrules`	Cursor	存在 `.cursorrules` 或 `.cursor/`
两者均写入	—	未检测到编辑器（零摩擦默认）

强制指定编辑器

使用 --editor 标志跳过自动检测：

npx contextforge-mcp init --editor=claude   # only CLAUDE.md
npx contextforge-mcp init --editor=cursor   # only .cursorrules
npx contextforge-mcp init --editor=all      # both, skip detection

幂等操作：重复运行是安全的。 CLAUDE.md 或 .cursorrules 中的现有内容会被保留；我们的区块仅追加一次，后续运行时跳过。

提示：可以在连接 MCP 到 AI 工具之前或之后运行此命令——顺序不限，但两者都是必须的。

方案 A：Claude Code（CLI）配置

为所有项目全局配置 ContextForge。

快速配置向导

备选方案：手动命令

如果向导无法正常工作，可直接运行以下命令：

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

提示：将 your-api-key-here 替换为您的 API 密钥。 -s user 标志可使配置在所有项目中生效。

验证是否正常工作：

在任意项目中打开 Claude Code，运行 /mcp ——您应该能看到 ContextForge 已连接。

npx contextforge-setup --verify

方案 B：Claude Desktop 配置

如果您使用 Claude Desktop，请按以下步骤操作：

1. 找到配置文件

# macOS

~/Library/Application Support/Claude/claude_desktop_config.json

# Windows

%APPDATA%\Claude\claude_desktop_config.json

# Linux

~/.config/Claude/claude_desktop_config.json

2. 添加 ContextForge 配置

编辑该文件并添加以下 JSON 配置：

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

注意：将 your-api-key-here 替换为第二步中的实际 API 密钥。

3. 重启 Claude Desktop

关闭并重新打开 Claude Desktop，以加载新配置。

方案 C：GitHub Copilot（VS Code）

GitHub Copilot 在智能体模式下支持 MCP 服务器。将 ContextForge 添加到您的 VS Code 设置中。

方式 1：项目级配置

在项目根目录创建 .mcp.json 文件：

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

方式 2：用户级配置

添加到 VS Code 的 settings.json 以在所有项目中启用：

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

3. 在智能体模式中使用

在 VS Code 中打开 Copilot 聊天，切换到 智能体模式，ContextForge 工具将自动可用。

测试您的配置

尝试以下命令验证一切是否正常工作：

# Store something in memory
"Remember that our API uses JWT tokens with 1-hour expiration"

# Query your memory
"What do we use for authentication?"

# List your spaces
"Show me my memory spaces"

# Get statistics
"Show me my memory usage stats"

推荐：关联您的项目

新功能

将本地目录关联到 ContextForge 项目，查询将自动筛选到该项目的 Spaces。

为何要关联？

查询仅搜索已关联项目的 Spaces
不同代码库之间的上下文保持独立
无需在每条命令中指定项目

如何关联：

# See available projects
"Link this project to ContextForge"

# Link to a specific project
"Link this directory to project MyProject"

# Create and link a new project
"Create and link a project called Backend-API"

# Check what's linked
"What project is linked here?"

注意：这会在您的目录中创建 .contextforge 文件。将其添加到 .gitignore 可避免团队共享，或者提交它以让所有人使用同一个项目。

了解更多关于项目关联的信息 →

可用 MCP 工具

ContextForge 为 Claude 提供以下工具，用于管理您的上下文记忆：

核心记忆操作

memory_ingest

将新知识存入记忆，自动生成向量嵌入

memory_query

使用语义相似度搜索记忆（由 Voyage AI 提供支持）

memory_list_items

分页列出所有已存储的知识条目

memory_delete

按 ID 或标题从记忆中删除条目

项目管理

memory_list_projects

列出账户中的所有项目

memory_create_project

创建新项目以整理 Spaces

memory_link_project新功能

将当前目录关联到云端项目

memory_current_project新功能

显示已关联的项目及其 Spaces

memory_unlink_project新功能

从目录中移除项目关联

memory_delete_project

删除项目及其所有 Spaces

Space 管理

memory_list_spaces

列出所有可用的记忆 Spaces

memory_create_space

创建新的隔离记忆工作区

memory_move_space

将 Space 移动到不同的项目

memory_stats

获取用量统计和限额信息

Git 集成

memory_git_connect

连接 GitHub 仓库以自动同步

memory_git_sync

手动同步已连接仓库的提交和 PR

memory_git_commits

列出存储在记忆中的提交记录

memory_git_prs

列出存储在记忆中的 Pull Request

Snapshots 与备份

memory_snapshot_create

创建记忆的 Snapshot 备份

memory_snapshot_restore

从之前的 Snapshot 还原记忆

memory_snapshot_list

列出所有可用的 Snapshots

导入与导出

memory_export

将记忆导出为 JSON、Markdown 或 CSV 格式

memory_import

从 JSON、Markdown、Notion 或 Obsidian 导入数据

批量操作

memory_ingest_batch

批量存储多条条目（最多 100 条）

memory_delete_batch

使用过滤条件批量删除条目

示例工作流

记录架构设计

"Remember: Our backend uses a microservices architecture with these services: auth-service (handles JWT), api-gateway (rate limiting), user-service (CRUD), and notification-service (email/push)."

之后，Claude 可回答："What services do we have?"

保存代码模式

"Store this as our standard error handling pattern:"

try {
  await operation();
} catch (error) {
  logger.error('Operation failed', { error });
  throw new AppError('OPERATION_FAILED', error);
}

记录决策

"Remember: We decided to use PostgreSQL instead of MongoDB because of our need for complex joins and ACID compliance. Decision made on 2024-01-15."

后续步骤

项目关联

新功能

将目录关联到项目以自动过滤

语义搜索

学习如何高效查询您的记忆

Git 集成

连接您的代码仓库

Snapshots

记忆的版本控制

安全性

管理 API 密钥和权限

故障排查

"Tool not found" 错误

请确保在添加配置后重启了 Claude。对于 Claude Code，使用 claude mcp list 进行验证。

"Invalid API key" 错误

请仔细检查配置中的 API 密钥，确保没有多余的空格或引号。在仪表盘设置中验证密钥是否有效。

"Command not found: contextforge-mcp" 错误

请确保使用 npm install -g contextforge-mcp 全局安装了该包。使用 which contextforge-mcp 进行验证。

ContextForge 在 Claude Code 中显示为 "disabled"

在 /mcp 对话框中使用方向键导航到 contextforge 并按 Enter 键启用。或再次运行 claude mcp add contextforge -s user -e CONTEXTFORGE_API_KEY=your-api-key-here -- npx -y contextforge-mcp。