Scan to join WeChat groupREADME
🚀 上下文同步：🧠 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
- 完全重启 VS Code。
- 打开 Copilot 聊天（Ctrl+Shift+I / Cmd+Shift+I）。
- 切换到代理模式（如果可用）。
- 在工具列表中查找 context-sync。
- 测试：询问 Copilot
"help me get started with context-sync"。
Cursor
在安装 Context Sync 后，在 Claude Desktop 中输入：
setup cursor
Claude 会给出特定于操作系统的指令。
Claude Desktop
- 完全重启 Claude Desktop。
- 开始新对话。
- 测试：询问 Claude
"help me get started with context-sync"，Claude 会自动完成配置。
不同平台的手动设置
VS Code + GitHub Copilot
无额外手动设置说明。
Cursor
- 打开 Cursor：
Settings → MCP。 - 添加以下配置：
{
"mcpServers": {
"context-sync": {
"command": "npx",
"args": ["-y", "@context-sync/server"]
}
}
}
- 刷新 MCP 服务器。
- 测试：
"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
向导会引导你完成以下步骤：
- 打开浏览器到 Notion 的集成页面。
- 逐步引导（只需复制/粘贴 2 个值）。
- 自动测试连接。
- 为你保存所有设置。
集成特性包括：
- 🔍 搜索你的 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 版本起支持。安装步骤如下：
- 安装 Context Sync：
npm install -g @context-sync/server。 - 重启 VS Code。
- 打开 Copilot 聊天。
- 切换到代理模式。
- 在工具列表中查找 context-sync。
它能与 Claude Code CLI 一起使用吗？
自 v0.6.0 版本起也支持。Claude Code 支持 MCP，集成应该很简单。目前的优先级是：
- VS Code 扩展。
- Claude Code CLI。
- 更好的入门引导。
我可以在移动设备上使用吗？
目前还不支持。移动设备使用需要 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 列表、代码上下文和对话历史。
路线图
| 版本 | 发布时间 | 内容 |
| ---- | ---- | ---- |
| ✅ v0.6.1 - prev | 2025 年 10 月 | ✓ VS Code & GitHub Copilot 支持
✓ 性能优化
✓ 异步文件操作
✓ 文件大小限制与安全
✓ 实时缓存失效 |
| 🔄 v1.0.0 - Current | 2025 年 11 月 | • Windsurf、Tabnine、Zed、Continue 集成
• 增强的 VS Code 集成
• 增强的 Cursor 集成
• 更好的入门流程
• 改进的文档
• 额外的性能优化 |
| 🔮 Future | 未来 | • 移动支持
• 团队协作
• 分析仪表盘
• 更多 AI 平台
• 高级功能 |
高级特性
项目管理
- 初始化和切换项目。
- 跟踪架构和技术栈。
- 存储带有推理的设计决策。
- 管理 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/仪表盘开发 - 用于内存管理的网页界面。
开始贡献
- 给仓库加星以表示支持。
- 加入讨论分享想法并获取帮助。
- 阅读 CONTRIBUTING.md 了解技术指南。
- 选择一个标记为
good-first-issue或help-wanted的问题。 - 提交 PR - 我们会快速审核并提供反馈。
故障排除
Claude Desktop 找不到 Context Sync
- 验证安装：
context-sync --version
- 检查配置文件：
# Mac/Linux
cat ~/.config/Claude/claude_desktop_config.json
# Windows
type %APPDATA%\Claude\claude_desktop_config.json
- 完全重启 Claude：
- Mac:
⌘ + Q（强制退出） - Windows: 右键单击任务栏图标 → 退出
- 在 Claude 设置中检查 MCP 服务器，查找 Context Sync。
如果仍然遇到问题，创建一个 issue。
Cursor 找不到 Context Sync
- 打开 Cursor 设置：
Settings → MCP。 - 验证配置是否存在：
{
"mcpServers": {
"context-sync": {
"command": "npx",
"args": ["-y", "@context-sync/server"]
}
}
}
- 刷新 Cursor 中的 MCP 服务器。
- 测试：询问 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]"
平台间上下文不同步
- 检查平台状态：
You: "Check platform status"
- 验证两个平台都已配置。
- 尝试手动同步：
You: "Sync context to Cursor"
更多帮助请参考 TROUBLESHOOTING.md。
🔧 技术细节
Context Sync 使用模型上下文协议（MCP）在开发者和 AI 系统之间创建一个持久的知识层。它通过本地的 SQLite 数据库存储数据，实现了数据的本地存储和管理。在架构上，它连接了各种开发环境（如 IDE、AI 工具、浏览器等），使得不同的 AI 工具能够共享相同的上下文信息。同时，它还具备智能缓存和按需查询的功能，提高了系统的性能和效率。
📄 许可证
Context Sync 采用 MIT 许可证，允许商业使用、自由修改和公开再分发。它是真正的开源项目，没有双重许可方案，没有 “企业版” 与 “社区版” 之分，没有功能付费墙或订阅层级，也没有专有扩展或锁定的生态系统。选择 MIT 许可证是因为 AI 工具基础设施应该属于开发者社区，而不是企业。