ctxfile

ctxfile

一份上下文，适用于所有 Agent，全部在本地。

网站 · 文档 · 快速开始 · 客户端 · .ctxfile 约定 · 安全

---

你会使用不止一个 AI Agent：在终端中使用 Claude Code，在编辑器中使用 Cursor，也会打开聊天标签页进行思考。每个 Agent 启动时都对项目一无所知，因为你的工作状态（计划、关键文件、git 状态，以及你一小时前做出的决定）都存在你的脑海和滚动记录中。

ctxfile 是一个本地优先的 MCP 服务，可将项目的工作状态快照保存为一个结构化的上下文对象，并通过一次调用将其交给任何 MCP Agent。在一个 Agent 中保存会话，然后在另一个 Agent 中继续。任何内容都不会离开你的设备。

you → ctxfile → the same context, in every agent

30 秒快速开始

一次配置，即可供你设备上的所有客户端使用

npm install -g ctxfile
ctxfile connect          # lists the MCP clients it found
ctxfile connect --all    # adds ctxfile to each (backups kept, other servers untouched)

或者告诉任意编码 Agent：“按照 https://ctxfile.dev/setup.md 为我设置 ctxfile。”

Claude Code（作为插件安装，或运行一条命令）

/plugin install ctxfile --marketplace ctxfile/ctxfile
claude mcp add --scope user ctxfile -- npx -y ctxfile

Cursor（在项目中的 .cursor/mcp.json，或在全局的 ~/.cursor/mcp.json）

{
  "mcpServers": {
    "ctxfile": { "command": "npx", "args": ["-y", "ctxfile", "--root", "${workspaceFolder}"] }
  }
}

Codex CLI

codex mcp add ctxfile -- npx -y ctxfile --root .

Claude Desktop（无需终端）：下载 ctxfile-macos-arm64.mcpb，并将其拖入“设置” → “扩展”。该安装包包含编译好的原生模块，因此目前仅支持 macOS（Apple Silicon）；在 Windows 或 Intel Mac 上，请改为将上面的 stdio JSON 添加到 claude_desktop_config.json 中。

其他所有客户端：ctxfile 是标准的 stdio 服务，因此完整命令就是 npx -y ctxfile。面向 VS Code、Windsurf、Zed、Cline、Gemini CLI、OpenCode、Warp、Goose、LM Studio、Kiro、JetBrains、Visual Studio、Amp、OpenClaw、Hermes 等客户端的一键安装链接和可复制粘贴的配置步骤，请访问 ctxfile.dev/docs/clients 中对应客户端的标签页。

然后，在你的 Agent 中说：“加载我的上下文”（或调用 get_context）。需要 Node ≥ 20（Windows 上需要 ≥ 22）。

自动化

你不再需要输入“保存这个”。只需运行一条命令即可安装一个 技能，让任意 Agent 在执行日常工作时知道何时保存上下文检查点，并在每次保存时通知你（绝不静默保存，随时可暂停，始终可供审查）：

ctxfile init

它会从一份规范源文件生成各类工具链所需的配置：为 Claude Code、OpenCode、OpenClaw 和 Hermes 生成 Agent SKILL.md（一个可在这四种技能系统中通用的文件）、生成 Cursor 规则，以及受管理的 GEMINI.md / AGENTS.md 区块。详情请见 ctxfile.dev/docs/automatic。

它也会随你进入聊天标签页

CLI 和编辑器 Agent 通过 MCP 加载的同一份上下文，也可以用于网页聊天机器人。将 Grok、ChatGPT、Claude web 或 Perplexity 连接到你的加密 Sync 保险库，作为自定义 MCP 连接器使用；或者运行 ctxfile export，再将封装内容粘贴到任何提示框中（Gemini 等）。操作指南：ctxfile.dev/docs/webchat。

默认保护隐私

这是我们最重视的部分，所以放在最前面：

• 默认情况下，不会进行任何网络调用。只访问文件和 git。
• 类似密钥的内容（云密钥、令牌、私钥、JWT、password= 赋值）在进入快照前就会被脱敏。绝不会读取 .env*、密钥文件和凭据文件。
• 核心功能对项目只读。绝不会写入仓库、git 状态或其他任何内容。
• 默认不收集遥测数据。 有一个匿名的每周安装心跳，仅在用户主动选择后才启用。
• 只有在你明确配置后，网络连接器（Notion、本地 Ollama 摘要、Sync）才会启用。

完整模型，包括 Pro 和 Sync 增加的功能，以及它们绝不会访问的内容，详见 ctxfile.dev/security。

功能

快照	get_context 返回一个结构化的 ContextObject：计划文档、按相关性排序且符合 token 预算的关键文件、git 状态，以及可选的 Notion 页面和本地大模型摘要。
保存并继续	save_session 保存 Agent 撰写的当前对话摘要。continue_thread 将合并后的历史记录（附带来源标注）交给下一个 Agent。切换不同的运行框架或服务提供商，甚至从全新会话开始，都能从上次停下的地方继续。
工作线程	为一项工作（例如“Q3 营销活动”）提供持久身份，可跨 Agent 和设备使用。handoff: true 会强制生成完整的交接包：状态、附带理由的决策、按顺序排列的待办事项和注意事项。
导入记忆	ingest_memory 将 ChatGPT、Grok、Claude 或任何助手对你的了解导入 ctxfile：使用一条提示词（ctxfile memory prompt）、严格的架构，并可选择全局或项目级范围。说明和身份信息需经你批准；重复内容会合并；拒绝的内容不会再次出现。之后，每个 Agent 都能在 get_context 中获取这些信息。文档。
任务	post_task、list_tasks、update_task：一个 Agent 可以在线程中为另一个 Agent 留下工作（例如“让 ChatGPT 起草潜在客户邮件”），被指派的 Agent 会在收件箱中找到任务，并在开始前征求你的意见。Agent 发布的任务在你通过仪表板或命令行批准前都只是提议；批准会在你的设备上签署，而任何发送、发布、推送代码或花费资金的操作都需要单独确认。文档。
通用导入	ingest_context 是为任何没有原生解析器的运行框架提供的、受架构约束的入口。提示词就是适配器，因此所有支持 MCP 的 Agent 都能使用，包括尚不存在的 Agent。
云端 Agent	ctxfile export 会生成静态且适合放入仓库的构件，供不会访问你设备的 Agent 使用（托管编码 Agent、CI）。其格式是开放规范：.ctxfile 约定。
仪表板	ctxfile ui：运行于 127.0.0.1 的本地控制台。运行快照、监控连接器、浏览上下文、检查 git 状态。
Sync（可选）	通过可自托管中继实现端到端加密的保险库。使用 Argon2id 派生密钥，并对每个数据块使用 XChaCha20-Poly1305 加密。中继只存储密文。

Monorepo

软件包	内容	许可证
packages/core	npm 上的 ctxfile：MCP 服务、快照引擎、线程、数据导入、导出、Sync 客户端、仪表板宿主	Apache-2.0
packages/relay	npm 上的 @ctxfile/relay：可自托管的 Sync 中继和团队中心（加密保险库、/mcp 端点、联邦、审计日志）。一个 Docker 镜像	Apache-2.0
packages/dashboard + packages/ui-kit	通过 ctxfile ui 提供的本地仪表界面	Apache-2.0
apps/web	ctxfile.dev：网站和文档	Apache-2.0

开源核心，坦诚相待

此仓库中的所有内容均采用 Apache-2.0 许可证，并且永远可以独立运行。付费的 Pro 附加组件（一个独立的闭源软件包）增加了会话连接器，可读取你近期在 Claude Code、Cursor、Codex CLI、OpenCode、Gemini CLI、Aider、OpenClaw 和 Hermes Agent 中的会话；加密的跨会话记忆；多提供商 咨询（Anthropic、通过一个密钥支持数百种模型的 OpenRouter、任何兼容 OpenAI 的端点，或本地 Ollama）；由 AI 提炼的提示词 Playbooks；以及本地语音捕获。许可证使用 Ed25519 签名密钥，并通过离线验证。永远不会向服务器回传数据。Pro 为开源工作提供资金。

参与贡献

欢迎提交问题、PR，以及各种奇特的运行环境报告。请从 CONTRIBUTING.md 开始。你发现的每种数据导入格式、每个 MCP 客户端的特殊情况、每处脱敏缺口，都能让整个项目变得更好。

• 错误和功能请求：问题
• 提问和展示分享：讨论
• 安全报告：SECURITY.md（请勿公开提交漏洞问题）

git clone https://github.com/ctxfile/ctxfile.git && cd ctxfile
npm install
npm run build && npm test    # the whole gate: lint, typecheck, tests

Star 历史

如果 ctxfile 帮你避免了冷启动，点个 Star，让更多人发现它。

许可证

Apache-2.0。“ctxfile”和 ctxfile 徽标是 ctxfile 的商标；许可证适用于代码，不适用于名称。