Skip to main content
Glama

🎯 为什么需要它?

❌ 痛点:上午用 Claude Code,好不容易让 Agent 摸清了代码库的逻辑、知道了哪个内部 API 会报错;结果晚换了台电脑,或者换了个模型,你的Coding Agent 瞬间失忆。然后又要在新的对话框里init,结果发现模型还是记不起来之前的agent到底踩过什么坑,跟你渡过过怎样的美好开发时间 :disguised_face:,然后就开始继续告诉他之前做到哪了,哪是坑之后别踩,只能说是身心俱疲。

✅ 解法:Context Sync 为 Agent 提供了一个独立于对话、独立于具体模型的长期记忆库。基于 Git 和 MCP,换台电脑、换个 Agent,敲一句 /sync-load,进度与上下文都能继续接上。

工作流极简: 新项目先 sync_init 建立第一份上下文 → 踩坑了/新决策用 write_context 自动记录 → sync_push 推送 → 换电脑 sync_load 拉取。就是这么简单。

它同步的不是“某个 Agent 的私有聊天记录”,而是项目里的结构化上下文文件;所以同一份上下文可以在 Claude ↔ Codex ↔ Gemini 之间复用。

💡 实际演示:由 Antigravity-Claude Code Opus 4.6 到 GPT-5.4

Related MCP server: openhandoff-mcp

🚀 推荐工作流

  • 新项目第一次接入:执行 /sync-init

  • 日常开发中有新增上下文:让 Agent 调用 write_context 记录到 .context/

  • 离开当前设备前保存:执行 /sync-save

  • 在另一台设备恢复:执行 /sync-load

简单记忆:先 init,一直 write,切换前 save,新设备 load。

✨ 核心特性

特性

说明

🧠 结构化长期记忆

将零散的对话沉淀为 5 类标准文档(避雷点、架构决策等),拒绝遗忘。

🔗 关联与自动编号

踩坑记录自动递增编号,支持 related_to 双向跳转,构建项目的知识图谱。

⚡️ 跨设备 + 跨 Agent 同步

sync_push / sync_load 一键指令,背靠 Git 实现可靠的版本控制与多端漫游;同一份上下文可被不同 Agent 继续使用。

🛡️ 同步文件规范化

会为 .context/ 写入轻量的 Git attributes,保持 Markdown / JSON 文件的文本格式一致;复杂并发编辑仍可能需要人工处理。

Token 消耗估算

操作

消耗 (Tokens)

说明

write_context

💡 极低 (~200)

取决于单次写入内容的长度

sync_push

💡 极低 (~20)

固定调用指令开销

sync_load

📊 中等 (~2000)

取决于 .context/ 积累的文件总量

一句话总结:日常开发一整天(5-10次写入 + 1次同步),额外消耗仅约 2k-5k tokens,对账单几乎无影响。


📦 极速安装与配置

与时俱进,直接让 Agent 帮你搞定一切。

提示词中默认将补充提示词写道项目提示词中,如果需要写入全局,可以修改全局提示词

前置要求

  • Node.js ≥ 18.0.0

  • Git 已安装并配置好 SSH/HTTPS 认证

  • 当前目录在一个 Git 仓库内

让你的 coding agent 帮你配置

复制下面这段话,直接发给你的 Codex / Claude Code / Gemini / Antigravity,剩下的交给它:

帮我安装并配置 `context-sync-mcp`,并确保它适用于跨设备、跨 Agent 的上下文同步。  
1. 运行 `npm install -g context-sync-mcp`  
2. 找到 context-sync-mcp 的安装路径(运行 `which context-sync-mcp` 或 `npm root -g`),确认 `dist/index.js` 的绝对路径  
3. 帮我注册这个 MCP server(使用你的标准 MCP 配置命令或修改相应的 mcp.json)。command 是 `node`,args 是 `["/绝对路径/context-sync-mcp/dist/index.js"]`  
4. 优先把下面的规则内容写入**当前项目**的规则文件(如 `.cursorrules`、`CLAUDE.md`、`.cursor/rules/`);

你有 context-sync MCP 工具。开发过程中:
- 踩坑了 → write_context 写到 gotchas
- 做了架构决策 → 写到 architecture
- 发现 API 特殊行为 → 写到 api_notes
- 完成阶段任务 → 更新 progress
- 仅更新 progress 不等于保存详情;具体踩坑/决策/API 行为必须写入 gotchas / architecture / api_notes,否则 `/sync-load` 只能恢复进度标记
- 用户说 /sync-init、初始化上下文同步、初始化这个仓库的 context sync → 调 sync_init
- 用户说 /sync-save、sync push、保存上下文、上传上下文 → 调 sync_push
- 用户说 /sync-load、sync pull、拉取上下文、恢复上下文、新设备恢复上下文 → 调 sync_load
- `sync_push` / `sync_load` 是内部工具名;对用户统一使用 `/sync-save` 和 `/sync-load`,不要说 `/sync-push`
- 这个 MCP 同步的是项目内 `.context/` 里的结构化上下文,不依赖某一个特定 Agent;因此同一份上下文可以在 Claude、Codex、Gemini 等不同 Agent 之间继续使用

🪄 配置完成后,你不需要记忆任何额外命令。像平常一样自然地写代码、提问,Agent 知道什么时候该记录。下班前对它说一句 /sync-save 即可;第二天哪怕换到另一个 Agent,也能用 /sync-load 接着干。


步骤 1:安装 CLI

npm install -g context-sync-mcp

步骤 2:注册 MCP

Cursor — 编辑 ~/.cursor/mcp.json(全局)或项目的 .cursor/mcp.json:

{
  "mcpServers": {
    "context-sync": {
      "command": "node",
      "args": ["/绝对路径/context-sync-mcp/dist/index.js"]
    }
  }
}

Claude Code — 运行:

claude mcp add context-sync node /绝对路径/context-sync-mcp/dist/index.js

OpenAI Codex — 运行:

codex mcp add context-sync -- node /绝对路径/context-sync-mcp/dist/index.js

Google Antigravity — 编辑项目根目录的 mcp_config.json 或 .mcp.json:

{
  "mcpServers": {
    "context-sync": {
      "type": "local",
      "command": "node",
      "args": ["/绝对路径/context-sync-mcp/dist/index.js"]
    }
  }
}

步骤 3:注入提示词

将本项目 rules/ 目录下的模板复制到你的工作区:

  • Cursor: 复制 rules/context-sync.mdc 到 .cursor/rules/

  • Claude Code: 复制 rules/CLAUDE.md 内容到根目录的 CLAUDE.md

建议优先使用项目级规则。只有在你明确希望所有项目默认启用 Context Sync 时,再考虑加到全局规则里。


🏗️ 它是如何运转的?

我们优化了架构图,让你一眼看懂它的极简逻辑。

一句话理解: Context Sync 传递的不是某个模型的“脑内状态”,而是项目内 .context/ 里的结构化记忆;因此它天然支持跨设备,也天然支持跨 Agent。

flowchart LR
    A["🤖 Coding Agent<br>(Cursor/Claude)"]
    M(("⚙️ Context Sync<br>MCP Server"))
    F["📁 本地记忆库<br>(.context/)"]
    G[("☁️ Git 远端")]

    A <-->|stdio 通信| M
    M <-->|读/写 Markdown| F
    M <-->|Push / Pull| G

    style A fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,color:#0f172a
    style M fill:#fffbeb,stroke:#fcd34d,stroke-width:2px,color:#92400e
    style F fill:#f0fdf4,stroke:#86efac,stroke-width:2px,color:#166534
    style G fill:#f3f4f6,stroke:#d1d5db,stroke-width:2px,color:#1f2937

📖 极简数据流

sequenceDiagram
    participant Dev as 👨‍💻 开发者
    participant Agent as 🤖 AI
    participant MCP as ⚙️ 组件
    participant Git as ☁️ 远端

    Note over Dev, Agent: 🌤 白天:遇到坑
    Dev->>Agent: "SQLite 跨进程锁死了..."
    Agent->>MCP: write_context(gotchas)
    MCP-->>Agent: ✅ 已记录至 gotchas.md

    Note over Dev, Agent: 🌙 下班:保存记忆
    Dev->>Agent: "/sync-save"
    Agent->>MCP: sync_push()
    MCP->>Git: ✅ git commit & push (含设备信息)

    Note over Dev, Agent: ☕ 重启:换电脑恢复
    Dev->>Agent: "/sync-load"
    Agent->>MCP: sync_load()
    MCP->>Git: git pull
    MCP-->>Agent: 📋 返回所有历史上下文与踩坑记录

🔧 工具详情

write_context

往 .context/ 目录写入记录。

  • gotchas (append): 踩坑记录、Bug 发现。

  • architecture (append): 架构决策记录。

  • api_notes (append): 接口行为说明。

  • progress (overwrite): 当前任务进度。

  • summary (overwrite): 项目整体索引。

提示:progress 更适合写“现在做到哪一步了”;如果你想让另一台设备恢复到具体的测试记录、踩坑细节或接口限制,请把正文写进 gotchas / architecture / api_notes,不要只写一句进度提示。

sync_init

为一个还没有 .context/ 的项目建立第一份上下文基线。适用于 /sync-init、初始化上下文同步、初始化当前仓库的 context sync。默认会自动探测项目名、当前分支和 README 标题,并生成保底的 progress / summary;如果 Agent 额外传入自定义内容,则以注入内容为准。若项目已有上下文,应改用 /sync-load。

sync_push

将 .context/ 推送到 Git 远端。自动生成 SUMMARY.md、写入用于保持文本格式一致的 .gitattributes,并更新同步元信息 sync_meta.json。适用于 /sync-save、sync push、保存/上传上下文。

sync_load

从远端拉取最新上下文,按优先级展示给 Agent 供推理使用。适用于 /sync-load、sync pull、拉取/恢复上下文、新设备恢复上下文。

如果 /sync-load 之后只看到了 SUMMARY.md 和 task_progress.md,通常不是同步坏了,而是此前详细内容还没有写入对应的结构化文件;这时应检查是否已经把内容写入 gotchas.md、architecture.md 或 api_notes.md。


📁 文件结构与隔离

工具会在你的项目根目录生成一个干净的 .context/ 文件夹,与业务代码完全隔离:

your-project/
└── .context/                   
    ├── SUMMARY.md              # 总览索引
    ├── gotchas.md              # 踩坑本
    ├── architecture.md         # 架构决策
    ├── api_notes.md            # 接口行为说明
    ├── task_progress.md        # 当前任务进度
    ├── .gitattributes          # Git attributes(保持文本格式一致)
    └── sync_meta.json          # 同步元数据 (设备识别)

最佳实践:直接将 .context/ 一并 commit 进业务代码仓库。如果你不希望污染业务代码,也可以在独立的文件夹(专用的 context 仓库)中运行 Agent。


Available Tools

4 tools
sync_initA

Bootstrap Context Sync for a project that has not been initialized yet. Use for first-time setup requests such as /sync-init, 'init context', 'initialize sync', or 'set up context sync for this repo'. If context already exists, do not overwrite it; guide the user to /sync-load instead.

Inputs: summary, progress, auto_push, project_path.

sync_loadA

Pull latest .context/ files from remote git and return their contents. Use for load/pull/restore/recover requests such as /sync-load, 'sync pull', 'pull context', 'load context', or 'restore context on a new device'. Do NOT use sync_push for these requests.

Inputs: topic, project_path.

sync_pushA

Push local .context/ files to remote git. Auto-generates SUMMARY.md. Use only for save/upload/push requests such as /sync-save, 'sync push', 'save context', or 'upload context'. Do NOT use this tool for pull/load/restore/new-device recovery requests.

Inputs: summary, project_path.

write_contextA

Batch write memory entries to .context/ files. Supports append (for gotchas, architecture, api_notes) and overwrite (for progress, summary). Use this to record discoveries, decisions, and progress during development.

Inputs: entries (required), project_path.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    The four tools split cleanly by lifecycle stage: local writing, initialization, git push, and git pull. Each description includes clear usage triggers and negative constraints, so an agent should not confuse them.

    Naming Consistency4/5

    Three tools follow a sync_<verb> pattern, while write_context uses verb_<object>. The snake_case convention is consistent and the actions are clear, so this is only a minor structural deviation.

    Tool Count5/5

    Four tools is well-scoped for a context sync server. Each tool earns its place by covering a necessary step: initialize, write, push, and load.

    Completeness4/5

    The core lifecycle from initialization to local writes to remote sync is covered, including first-time setup and new-device recovery. Minor gaps like delete operations or sync status checks are missing but are not blocking for the main workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding assistants to store and retrieve project-aware context as plain Markdown files locally, with no cloud or vector database required.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to save and read persistent, project-local markdown context files in a .opencontext/ directory, so durable project decisions and conventions survive across sessions.
      2
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives AI coding agents persistent, branch-aware memory and a dependency-tracked task graph by storing decisions, lessons, and tasks as plain JSON and Markdown committed directly into the repository. Agents can record and fuzzy-search past decisions, dump instant project context, and create, claim, complete, and query tasks whose completion automatically unblocks downstream work.
      MIT