Context Sync

🚀 上下文同步：🧠 AI 开发的记忆层

Context Sync 是一个开源基础设施，它为所有开发工具、会话和项目中的 AI 系统提供持久的内存，解决了 AI 系统在对话间丢失上下文的问题，极大提升了开发效率。

🚀 快速开始

安装

# 全局安装
npm install -g @context-sync/server

测试使用

重启你的 AI 工具（如 Claude Desktop、Cursor、VS Code），然后询问："help me get started with context-sync"，Context Sync 会自动配置并通过自然语言指令引导你完成首次设置。

不同平台的快速设置

VS Code + GitHub Copilot

1. 完全重启 VS Code。
2. 打开 Copilot 聊天（Ctrl+Shift+I / Cmd+Shift+I）。
3. 切换到代理模式（如果可用）。
4. 在工具列表中查找 context-sync。
5. 测试：询问 Copilot "help me get started with context-sync"。

Cursor

在安装 Context Sync 后，在 Claude Desktop 中输入：

setup cursor

Claude 会给出特定于操作系统的指令。

Claude Desktop

1. 完全重启 Claude Desktop。
2. 开始新对话。
3. 测试：询问 Claude "help me get started with context-sync"，Claude 会自动完成配置。

不同平台的手动设置

VS Code + GitHub Copilot

无额外手动设置说明。

Cursor

1. 打开 Cursor：Settings → MCP。
2. 添加以下配置：

{
  "mcpServers": {
    "context-sync": {
      "command": "npx",
      "args": ["-y", "@context-sync/server"]
    }
  }
}

3. 刷新 MCP 服务器。
4. 测试："Help me get started with context-sync"。

Claude Desktop

Windows：

# 编辑配置文件
notepad "%APPDATA%\Claude\claude_desktop_config.json"

macOS：

# 编辑配置文件
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Linux：

# 编辑配置文件
nano ~/.config/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "context-sync": {
      "command": "npx",
      "args": ["-y", "@context-sync/server"]
    }
  }
}

重启 Claude Desktop 并测试："Help me get started with context-sync"。

✨ 主要特性

解决 AI 上下文丢失问题

AI 系统在对话间会丢失上下文，开发者需要反复解释代码库、架构决策和项目上下文。Context Sync 为 AI 系统创建了持久、可查询的内存，解决了这一问题。

类似 AI 记忆的版本控制

它就像 AI 上下文的分布式版本控制，让每个 AI 工具都能共享相同的内存，例如：

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude.ai     │    │   Cursor IDE    │    │   VS Code       │
│   (Web & App)   │    │                 │    │   + Copilot     │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          │           MCP Protocol (standardized)       │
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                     ┌───────────▼────────────┐
                     │    Context Sync        │
                     │   Memory Layer         │
                     │                        │
                     │  • Project Context     │
                     │  • Code Understanding  │
                     │  • Decision History    │
                     │  • Architecture Maps   │
                     │  • File Operations     │
                     │  • Git Integration     │
                     └────────────────────────┘

支持 Notion 集成

v1.0.3 版本新增了与 Notion 的集成，通过交互式设置向导可轻松完成配置：

# 安装 Context Sync
npm install -g @context-sync/server

# 运行设置向导
context-sync-setup

向导会引导你完成以下步骤：

1. 打开浏览器到 Notion 的集成页面。
2. 逐步引导（只需复制/粘贴 2 个值）。
3. 自动测试连接。
4. 为你保存所有设置。

集成特性包括：

• 🔍 搜索你的 Notion 工作区。
• 📖 以正确格式读取和更新页面。
• 📝 自动创建新文档。
• 🎯 导出决策为架构决策记录（ADRs）。
• 📊 生成包含技术栈和架构的项目仪表盘。
• ✨ 支持 Markdown - 在 Notion 中创建漂亮、格式化的页面。

分布式 AI 记忆

Context Sync 使用模型上下文协议（MCP）在你和 AI 系统之间创建一个持久的知识层，其架构如下：

Your Development Environment
┌─────────────────────────────────────────────────────────┐
│  IDE/Editor        AI Tool           Browser/Web        │
│  ┌───────────┐    ┌───────────┐     ┌─────────────┐    │
│  │  Cursor   │    │  Claude   │     │ Claude.ai   │    │
│  │  VS Code  │    │  Desktop  │     │  Web app    │    │
│  │  Vim/etc  │    │  Copilot  │     │  Other AIs  │    │
│  └─────┬─────┘    └─────┬─────┘     └──────┬──────┘    │
└────────┼──────────────────┼─────────────────┼───────────┘
         │                  │                 │
         └──────────────────┼─────────────────┘
                            │ MCP Protocol
                            │
┌───────────────────────────▼─────────────────────────────┐
│              Context Sync (Open Source)                 │
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │   Memory    │  │   Files     │  │    Git & Code   │ │
│  │  • Projects │  │  • Read     │  │  • Status       │ │
│  │  • Context  │  │  • Write    │  │  • Diffs        │ │
│  │  • History  │  │  • Search   │  │  • Analysis     │ │
│  └─────────────┘  └─────────────┘  └─────────────────┘ │
│                                                         │
│            Local SQLite Database (~/.context-sync/)    │
└─────────────────────────────────────────────────────────┘

其主要优势包括：

• 通用兼容性：与任何支持 MCP 的 AI 工具兼容。
• 本地所有权：所有数据存储在本地机器上。
• 无供应商锁定：开源且可扩展。
• 智能缓存：仅在 AI 需要时加载详细信息。

独特的优势

通用 AI 记忆层

Context Sync 不仅仅是一个工具，更是一种基础设施，类似于代码的 Git 版本控制，它是 AI 知识的版本控制：

• 分布式：每个 AI 工具都能共享相同的内存。
• 本地优先：数据由你控制，保障隐私。
• 平台无关：与任何支持 MCP 的 AI 工具兼容。
• 可扩展：开源架构支持无限定制。

目前支持的平台包括：

• ✅ Claude Desktop (Mac/Windows/Linux)
• ✅ Cursor IDE
• ✅ VS Code + GitHub Copilot
• ✅ Continue.dev
• ✅ Windsurf
• ✅ Zed Editor
• ✅ TabNine
• ✅ 任何支持 MCP 的 AI 工具
• 🔄 更多平台通过社区贡献定期添加。

智能上下文管理

项目感知上下文：

• 自动检测和初始化项目。
• 识别技术栈（如 TypeScript、React、Python 等）。
• 跟踪架构决策并记录推理过程。
• 理解和分析代码结构。

高效内存使用：

• 每个项目使用 1 - 3K 个令牌（而非完整的对话转储）。
• 按需查询（AI 根据需要请求详细信息）。
• 使用结构化摘要而非原始聊天记录。
• 不会使上下文窗口饱和。

开发者关注的特性：

• 文件操作（读取、写入、搜索）并带有审批工作流。
• Git 集成（状态、差异、分支）。
• 依赖分析和调用图跟踪。
• 跨项目跟踪的 TODO 管理。
• 代码符号搜索和类型分析。

隐私优先架构

• 100% 本地存储：数据存储在本地的 SQLite 数据库中。
• 无云依赖：（可选基于 Git 的同步）。
• 无跟踪或分析：不使用服务器。
• 开源透明：可审计每一行代码。
• 无供应商锁定：可随时导出数据。

📦 安装指南

全局安装

npm install -g @context-sync/server

Notion 集成安装

# 安装 Context Sync
npm install -g @context-sync/server

# 运行设置向导
context-sync-setup

💻 使用示例

自由开发者工作流示例

周一上午（Cursor）

You: "Initialize project 'EcommerceClient' - Next.js 14, Stripe, PostgreSQL"
AI: "Project created! ✓"
*Build product catalog for 3 hours*

周二下午（Claude Desktop）

You: "Continue EcommerceClient - add shopping cart"
AI: "Adding cart to your Next.js app with Stripe integration.
     Using the product schema we defined yesterday..."

周三（Cursor）

You: "Switch back to Cursor. Review cart implementation"
AI: "Analyzing cart code... found 2 potential improvements..."

📚 详细文档

常见问题解答

为什么 Claude 本身没有内置这个功能？

主要是商业激励的原因。如果 Claude 能完美记住所有内容，开发者的对话会更短，使用的消息更少，达到速率限制的速度也会更慢，这可能会降低 AI 公司的利润。而 Context Sync 是开源的，以本地优先，由社区驱动开发。

这会填满我的上下文窗口吗？

不会。Context Sync 每个项目仅使用 1 - 3K 个令牌，它存储结构化摘要，AI 按需查询详细信息，不会将所有内容一次性加载到新对话中。

我的数据安全和隐私有保障吗？

数据 100% 存储在本地（SQLite 数据库），无需依赖云服务（可选基于 Git 的同步），无跟踪或分析，开源透明，可随时删除数据（只需删除 ~/.context-sync/）。

它能与 VS Code 一起使用吗？

可以，自 v0.6.0 版本起支持。安装步骤如下：

1. 安装 Context Sync：npm install -g @context-sync/server。
2. 重启 VS Code。
3. 打开 Copilot 聊天。
4. 切换到代理模式。
5. 在工具列表中查找 context-sync。

它能与 Claude Code CLI 一起使用吗？

自 v0.6.0 版本起也支持。Claude Code 支持 MCP，集成应该很简单。目前的优先级是：

1. VS Code 扩展。
2. Claude Code CLI。
3. 更好的入门引导。

我可以在移动设备上使用吗？

目前还不支持。移动设备使用需要 Claude 移动应用支持 MCP（目前不可用）或开发自定义移动应用（计划未来实现）。当前的解决方法是在移动设备上使用 Claude.ai 网页版（只读），仅桌面端支持完整功能。

这需要花费多少钱？

Context Sync 是 100% 免费且开源的（MIT 许可证）。可能需要支付的费用包括：

• Claude Pro 订阅（推荐但非必需）。
• 安装设置所需的时间（约 2 分钟）。

如果我有多个项目怎么办？

Context Sync 可以很好地处理多个项目，例如：

You: "Switch to my blog project"
AI: [loads blog context instantly]

You: "List my projects"
AI: 
  1. TaskFlow (Next.js + Supabase)
  2. Personal Blog (Astro)
  3. Client Website (WordPress)

You: "Switch to TaskFlow"
AI: [back to TaskFlow context]

每个项目都有自己独立的架构决策、技术栈、TODO 列表、代码上下文和对话历史。

路线图

高级特性

项目管理

• 初始化和切换项目。
• 跟踪架构和技术栈。
• 存储带有推理的设计决策。
• 管理 TODO 和优先级。

代码分析

• 依赖图分析。
• 函数调用跟踪。
• 类型定义查找。
• 查找所有引用。
• 影响分析。

文件操作

• 读取项目结构。
• 搜索文件和内容。
• 修改文件（需审批）。
• 应用更改前预览。

Git 集成

• 查看状态和差异。
• 分支信息。
• 提交消息建议。
• 更改跟踪。

跨平台

• 无缝的 Cursor ↔ Claude 同步。
• 特定平台优化。
• 上下文切换自动化。

开发者工具

• 50 + MCP 工具。
• 可扩展架构。
• TypeScript + SQLite。
• 开源。

参与贡献

为什么要贡献？

• 塑造 AI 工具标准：帮助定义 AI 系统应如何处理持久内存。
• 解决自身问题：构建满足自己工作流程的功能。
• 学习前沿技术：使用 MCP、TypeScript、SQLite 和 AI 集成技术。
• 加入变革运动：推动 AI 开发工具真正开放和可扩展。

贡献方式

代码贡献：

• 为新的 AI 平台（如 Gemini、Ollama 等）添加支持。
• 实现新的分析工具（如 Python 依赖跟踪等）。
• 为更多编辑器（如 Vim、Emacs 等）构建集成。
• 优化性能和内存使用。

非代码贡献：

• 编写文档和教程。
• 测试 beta 功能并报告 bug。
• 分享用例和工作流程。
• 在讨论中帮助其他开发者。
• 创建示例项目和模板。

社区建设：

• 向其他开发者分享 Context Sync。
• 撰写关于使用体验的博客文章。
• 在会议或聚会上发言。
• 参与路线图规划。

当前优先事项

• [ ] Python 生态系统支持 - pip、poetry、需求分析。
• [ ] 移动/网页集成 - React Native、Expo、网页开发工作流程。
• [ ] Docker/容器化 - 容器化应用的工作区检测。
• [ ] 更多 Git 集成 - PR 分析、提交消息生成。
• [ ] 性能优化 - 更快的工作区扫描、更好的缓存。
• [ ] UI/仪表盘开发 - 用于内存管理的网页界面。

开始贡献

1. 给仓库加星以表示支持。
2. 加入讨论分享想法并获取帮助。
3. 阅读 CONTRIBUTING.md 了解技术指南。
4. 选择一个标记为 good-first-issue 或 help-wanted 的问题。
5. 提交 PR - 我们会快速审核并提供反馈。

故障排除

Claude Desktop 找不到 Context Sync

1. 验证安装：

context-sync --version

2. 检查配置文件：

# Mac/Linux
cat ~/.config/Claude/claude_desktop_config.json

# Windows
type %APPDATA%\Claude\claude_desktop_config.json

3. 完全重启 Claude：

• Mac: ⌘ + Q（强制退出）
• Windows: 右键单击任务栏图标 → 退出

4. 在 Claude 设置中检查 MCP 服务器，查找 Context Sync。

如果仍然遇到问题，创建一个 issue。

Cursor 找不到 Context Sync

1. 打开 Cursor 设置：Settings → MCP。
2. 验证配置是否存在：

{
  "mcpServers": {
    "context-sync": {
      "command": "npx",
      "args": ["-y", "@context-sync/server"]
    }
  }
}

3. 刷新 Cursor 中的 MCP 服务器。
4. 测试：询问 AI "What's my current project?"。

“No active project” 错误

先设置工作区：

You: "Set workspace to /path/to/your/project"

或者检查现有项目：

You: "What projects do I have?"
You: "Switch to [project-name]"

平台间上下文不同步

1. 检查平台状态：

You: "Check platform status"

2. 验证两个平台都已配置。
3. 尝试手动同步：

You: "Sync context to Cursor"

更多帮助请参考 TROUBLESHOOTING.md。

🔧 技术细节

Context Sync 使用模型上下文协议（MCP）在开发者和 AI 系统之间创建一个持久的知识层。它通过本地的 SQLite 数据库存储数据，实现了数据的本地存储和管理。在架构上，它连接了各种开发环境（如 IDE、AI 工具、浏览器等），使得不同的 AI 工具能够共享相同的上下文信息。同时，它还具备智能缓存和按需查询的功能，提高了系统的性能和效率。

📄 许可证

Context Sync 采用 MIT 许可证，允许商业使用、自由修改和公开再分发。它是真正的开源项目，没有双重许可方案，没有 “企业版” 与 “社区版” 之分，没有功能付费墙或订阅层级，也没有专有扩展或锁定的生态系统。选择 MIT 许可证是因为 AI 工具基础设施应该属于开发者社区，而不是企业。