KLYPIX Shared Project Memory

为 Claude Code、Codex、Cursor 和其他 MCP 编码工具提供共享项目记忆。一个 brain.klypix 文件随代码一同提交，记录项目的决策、纠正和待解决问题。受支持的 Agent 会在任务开始时读取它，并在工作过程中补充内容；自动完成的程度取决于宿主。任何人都可以打开同一个文件并进行修正。

_{这是 klypix.com 上会话影片的 14 秒剪辑。 真实终端输出位于下文。}

▶ 观看： 面向编码团队（40 秒，含声音） · 只需纠正一次（20 秒） · 完整介绍（4 分钟） · KLYPIX 网络

三步完成安装

你需要 Node.js 20 或更高版本（node -v）。

1. 在项目目录中运行：

   npx klypix-mcp install
   

   如果项目还没有 brain.klypix，此命令会为它创建一个；接着配置它在这台机器上找到的编辑器，并在退出前检查工具是否正常响应。

2. 重新打开你的编码工具，或重新连接其 MCP 服务，并在收到提示时允许使用 KLYPIX 工具。

3. 检查是否正常。 运行 npx klypix-mcp doctor，然后 记录你的第一个决策和纠正，再从一个新会话中询问相关内容。

你将获得什么

• 可延续的决策。 下一次会话，无论使用相同还是其他工具，都会基于项目已有的决策开始：在 Claude Code 中自动延续，在其他宿主中则由 Agent 调用 brain_sync。更正会替换旧决策，而旧卡片会保留为历史记录。
• 工作重叠时收到提醒。 每个会话都会说明自己正在做什么，以及预计会修改哪些文件。当两个会话提到同一个文件时，双方都会收到提醒。对于重叠的工作，KLYPIX 会发出提醒，但绝不会阻止编辑。这在一台电脑上即可使用。在两台电脑上都安装 KLYPIX network（klypix-mcp 1.106.0 或更高版本）后，还会列出队友电脑上同一项目中的会话。
• 会话之间的备注与交接。 Agent 可以给另一个会话留言，即使该会话已经关闭也可以。备注会在该会话下一次执行 KLYPIX 操作时送达，因此不需要你手动转发。当会话在工作完成前停止时，这台电脑上的下一个会话会看到它正在做什么，而知识库中的交接卡片会通过 Git 延续后续步骤。
• 共享检出目录的 Git 防护（Claude Code）。 多个会话共享同一个检出目录时，如果某条 Git 命令会把另一个活动会话尚未提交的工作一并纳入你的提交，该命令就会被拦截。若命令会丢弃工作内容，则会先保存一份救援副本，再询问你。此功能覆盖一台电脑上通过 Claude Code 工具运行的 Git 命令。
• 及时捕捉重复错误的经验。 知识库记录的经验可以转化为项目规则，并由人员批准：只检查差异，不在检查时使用 AI。规则会在会话规划文件、编辑文件和提交时发出提醒。只有经人员批准并设为阻止级别的规则才会阻止工作：Claude Code 会在写入违规行之前阻止操作（Codex 会发出提醒）；提交时则由选择启用的 Git 钩子执行，适用于任何工具或人员。规则会检查差异，不会运行你的测试。
• 由你掌控的文件。 知识库是仓库中的一个 .klypix 文件：普通 ZIP 文件，由 Git 进行版本管理。引擎采用 Apache-2.0 许可，在你的电脑上运行，无需 KLYPIX 应用或账户。知识库数据保存在你的文件中；Agent 读取的内容仍会发送给该 Agent 使用的模型提供商。

主机

集成程度取决于主机。详情请参阅完整表格。

主机	可用功能	设置方式
Claude Code	六个生命周期钩子（1.105.0 及更高版本）：会话开始时提供简报、每次提示词时提供上下文、轮次结束时自动捕获、状态信息和 git 防护	install
Codex	原生 MCP 工具、状态信息和 brain_sync；可通过 --codex-hooks 启用可选钩子。不支持自动捕获	install
Cursor, Cline, VS Code (Copilot / Continue), Gemini CLI, Antigravity	MCP 配置和常驻规则文件。Agent 会自行调用 brain_sync 和 brain_note	对找到的编辑器运行 install，或运行 link
Windsurf, Aider	规则文件。Windsurf 使用自己的全局 MCP 配置；Aider 使用命令行	link
Claude Desktop	一次性配置项	在 KLYPIX 应用的 Settings 中设置，或手动配置
Claude，作为插件使用	一个固定版本、关键词搜索，不支持钩子	klypix-plugin

klypix-mcp 在 Linux 和 macOS 上提供 27 个 MCP 工具，在 Windows 上提供 28 个，其中新增了 show_in_klypix。运行 npx klypix-mcp doctor 可查看当前安装的工具数量。

一个项目。多个 Agent。一份最新共识。

KLYPIX 不会启动、运行、监控或取代你的 Agent。它不是 Agent 运行时、模型路由器、工作树管理器，也不是 Git 的替代品。它保存项目当前的共识。

KLYPIX 是一个可移植的共享大脑项目工作区。此仓库是其本地 MCP 服务。可选的 Windows 工作区让用户在文件旁查看同一个 大脑；基于应用的共享有独立的云端路径（请参阅 安全与权限）。对于项目与创意路径，即在 ChatGPT 或 Claude 聊天中保存 项目材料，请参阅 保存项目材料并与助手搭配使用。 该方式通过 KLYPIX 独立托管的连接来访问你授权的空间；安装此本地 服务并不会设置该连接。

指南：共享项目记忆设置 · 记忆工具对比（其中链接到各工具的 官方文档，并说明该指南由 KLYPIX 编写） · klypix.com/klypix-mcp

---

目录

• 开始： 问题所在 · 60 秒：两个 Agent，一个项目 · 快速开始 · 你的第一个决策与修正
• 参考： 大脑的工作方式 · 支持的宿主及其集成级别 · 作为 Claude 插件运行 · 任务简报 · 记录与修正 · 项目规则 · 在线状态与任务意图 · 重叠警告 · 使用其他计算机的队友 · 交接与消息 · 以证据为门槛的完成确认 · KLYPIX 中的人类控制 · 自行测量 · Git 与并发 · 共享检出中的 Git 守卫：这是谁的？ · 命令行 · 动词 · 一个可随身携带的文件 · 将其用作库 · A2A · 更新 · 安全与权限 · 当前限制 · 数据与方法 · 卸载
• 参与贡献 · 为什么要做这个 · 许可证

---

问题所在

你正在同一个代码库上运行多个编码 Agent——这里有一个 Claude Code 会话，另一个终端里运行 Codex，旁边还开着 Cursor。在一个工具中保存的上下文可能不会出现在下一个工具中：

• 新会话会遗漏之前的决策，你不得不再次解释同一套架构。
• 只记录在 Claude 对话中的决策，在你的 Codex 会话中无法使用。
• 某个 Agent 实现了团队已经否决的方案，因为否决原因留在一段已结束的聊天中。
• 两个会话开始修改相同文件，直到审查时才有人发现。
• Git 保存代码历史；变更背后的原因仍然需要记录。

你的 Agent 可以独立运行，但它们对项目的理解不应彼此隔离。

---

60 秒：两个 Agent，一个项目

_{真实输出，而非模拟效果：两个窗格都通过真实 MCP 客户端连接到此服务 (docs/demo/ — GIF 由 CI 使用脚本录制内容针对此服务渲染，而非手动录制；当服务的响应发生变化时，也会重新渲染）。}

示例调用和响应：请在两个会话中都将 /absolute/path/to/project 替换为同一个项目根目录 （例如，Windows 上的 C:/work/api）。

会话 A — Claude Code，在你的代码仓库中：

brain_sync { project: "/absolute/path/to/project", phase: "start",
             intent: "rewrite the auth token refresh", files: ["src/auth/token.ts"] }
// → task-relevant memory capsule (bounded, ~2.8KB)
// → peers: none

会话 B — Codex，在同一个代码仓库中，半分钟后：

brain_sync { project: "/absolute/path/to/project", phase: "start",
             intent: "add rate limiting to the auth routes",
             files: ["src/auth/token.ts", "src/auth/routes.ts"] }
// → task capsule
// → peers: 1 active session (claude-code) — "rewrite the auth token refresh"
// → overlap: src/auth/token.ts — declared by both sessions

会话 A 在下一次执行 KLYPIX 操作时，也会看到同样的重叠提示。两边的编辑都不会被阻止—— 此警告仅供参考，而且只有当双方都声明了预期修改的文件时，双方才会看到重叠提示。

接着，大脑会在决策之前提出异议，而不是事后：

brain_challenge { claim: "move token storage to localStorage" }
// → "reversed on June 12 — here's the correction card, captured by a different agent."

并且会记录这项决策，方便下一个会话查找：

brain_note { text: "Token refresh moves to an httpOnly cookie; localStorage was reversed 2026-06-12." }

使用两个真实且相互隔离的 MCP 客户端，在你自己的机器上，针对你安装的确切构建版本，验证以上所有内容：

npx klypix-mcp conformance

它会在临时测试夹具中运行，不会触碰其他内容。它会检查工具发现、任务记忆、如实报告同伴、 显示重叠、主动记录，以及通过带内方式传递同伴备注。它会验证 15 项必需的协作行为—— 并非每个工具，也不包括检索引擎。

---

快速开始

你需要 Node.js 20 或更高版本（运行 node -v 检查）。所有连接方式都会通过 node 运行服务——npx、已安装的程序包，以及 KLYPIX 设置按钮写入的入口——并且都不会 事先检查 Node 是否已安装。

请在项目目录中运行：

npx klypix-mcp install

一条命令即可配置此机器上检测到的受支持编辑器。它会查找项目根目录（逐级向上查找， 因此从 src/ 运行也没问题），为尚无大脑的项目创建大脑，为你实际安装的 Agent 配置工具， 如果项目属于 Git 仓库，则注册卡片级 .klypix 合并驱动，并在退出前验证结果：

示例输出；检测到的编辑器、文件数、工具数和耗时会因机器和安装的版本而异：

  project   E:\work\api  (git repository root)
  brain     created brain.klypix — a starter brain, ready for its first decision
  editors   Claude Code · Cursor · Codex · Gemini CLI · Antigravity · VS Code
  wired     9 file(s) · 9 updated   (skipped 5 for tools you don't have)
  git       .klypix merge driver registered
  verified  ✓ 25 tools reachable via .mcp.json (892ms)

最后这一行才是关键。MCP 配置出错时会悄无声息——错误的条目意味着服务永远不会启动， Agent 会在没有任何提示的情况下失去所有大脑操作，也不会报告任何错误。因此，install 会针对刚写入的配置执行真实的 stdio 握手，并统计成功响应的工具数量。损坏的条目会在约 100 毫秒内以 Connection closed 退出，并被报告出来，而不是直接交付。

内容写入位置：

• 机器全局，仅需配置一次——引擎和运行时位于 ~/.claude/project-brain，Claude Code 的六个 生命周期钩子（1.105.0 之前的版本为五个）位于 ~/.claude/settings.json，以及 ~/.codex/AGENTS.md 中的指导区块。因此，在该机器上任何拥有 ./brain.klypix 的项目中，都能使用 Claude Code。
• 每个项目单独配置——Cursor、Codex、Cline、Windsurf、Copilot、Gemini CLI / Antigravity 和 Aider 的 MCP 配置与规则。请在每个项目中运行一次 install。

以下三件事是它刻意不会做的：

• 为尚未安装的编辑器编写配置。 只会为这台机器上检测到的宿主投射配置——使用同一种编辑器的两人团队，不必再为从未打开过的另外六种编辑器提交规则。无论如何，项目已有的文件都会继续维护，因此你无法悄悄停止更新团队已提交的配置。
• 为非项目目录接入配置。 它会拒绝你的主目录、驱动器根目录，以及没有 brain、没有 git 仓库且没有项目清单的目录。输错命令不会在 C:\Users\you 中植入 brain。
• 替换项目自带的服务。 仓库相对路径的启动命令（如 node scripts/klypix-mcp-server.mjs）是有意为之——它可以离线解析，并依赖由仓库版本控制的套件——因此会原样保留并报告。显式执行 link 仍会重写所有内容：对于你没有要求的操作，它会比你主动要求的操作更加保守。

使用 --no-project 选择退出（用于 CI 镜像和脚本化配置）。--json 会将报告输出为结构化数据；--verify-all 会对每个已写入的配置执行握手，而不只检查一个。

可选、由你选择启用，并在 Codex 内部批准：

npx klypix-mcp install --codex-hooks

六个 Codex 生命周期钩子，可自动为每个提示词注入上下文，并在编辑前发出文件重叠警告。信任决策由 Codex 掌控，它会要求你审核这些钩子。brain_doctor 会将此层单独报告为关闭、执行未经验证或已启用。即使启用了它，Codex 也绝不会自动捕获决策——Codex 钩子不会写入 brain。

显式重新投射所有内容：

npx klypix-mcp link

install 已会为你安装的编辑器完成此操作。当你想要管理全部 14 个带哈希戳的文件（无论安装了哪些编辑器）或修复配置偏差时，请使用 link——其中包括面向六种宿主的 MCP 服务配置，以及面向八种宿主的规则文件。托管区块会合并到现有指令文件中，绝不会覆盖你的内容。

npx klypix-mcp link --check    # audits without writing; exits non-zero on drift

两种形式都有效，在 CI 中也都安全：npx -p klypix-mcp klypix-link --check 过去会丢弃 --check 并照常写入——现已修复，并由 test/cli-args.mjs 锁定测试；该测试会断言独立 bin 和分发器对参数的解析完全一致。

为项目添加 brain，只需在其中放入一个 brain.klypix—— KLYPIX 应用只需单击一次即可完成（将画布另存为项目 brain），或者让任意 Agent 使用 create_canvas 创建一个。

你的第一个决策及修正

安装后，重新打开你的编码工具或重新连接其 MCP 服务，并允许 KLYPIX 工具（如果你的宿主要求这样做）。在项目中运行 npx klypix-mcp doctor 来检查安装情况；配置报告正常并不能证明你的宿主已加载这些工具。

请在一次性试用项目中尝试以下操作，或者在保存前将示例决策替换为真实决策。这些是供你的 Agent 调用的 MCP 工具，并非 shell 命令。请将 /absolute/path/to/project 全部替换为你的项目根目录。files: [] 范围表示此次试用不会计划修改源代码。

1. 记录一项决策及其理由。 请你的 Agent 调用：

   brain_sync { project: "/absolute/path/to/project", phase: "start",
                intent: "Record the trial storage decision", files: [] }
   brain_note { area: "Storage",
                text: "Use SQLite for the trial project database because this prototype runs on one machine." }
   brain_sync { project: "/absolute/path/to/project", phase: "complete" }
   

2. 在同一项目中开启一个新会话，也可以改用其他受支持的编码工具。请它检索该决策，而不是根据代码推断答案：

   brain_sync { project: "/absolute/path/to/project", phase: "start",
                intent: "Review the trial storage decision", files: [] }
   brain_ask { question: "Which database does the trial project use, and why?" }
   

   检查返回的卡片是否包含 SQLite 和仅有一台机器的理由。如果缺少该工具，请重新连接宿主，并查看宿主集成表。如果缺少该卡片，请确认两个会话使用的是同一个项目，并且 brain_note 报告了成功记录。全新的 brain 只知道已记录的内容。

3. 明确更改试用决策，然后再次提问：

   brain_note { area: "Storage",
                text: "CORRECTION: Use PostgreSQL instead of SQLite for the trial project database because the trial now needs concurrent writes from several machines." }
   brain_ask { question: "Which database does the trial project use now, and why?" }
   brain_sync { project: "/absolute/path/to/project", phase: "complete" }
   

   检查返回的来源卡片：PostgreSQL 应是当前决策，而 SQLite 应作为已被取代的历史记录保留。确认修正内容提到了先前的决策；仅有修正提示并不能保证匹配。这项小型试用用于检查你的记录和检索路径，但不能证明更大规模 brain 的检索质量，也不能证明宿主自动化有效。

如果团队成员使用不同的机器，请按照 Git 共享步骤操作，并在每个克隆中完成安装。独立运行时，实时状态和文件重叠警告仅适用于一台机器和一个 OS 用户；每台电脑都启用 KLYPIX network 后，这些功能也会覆盖同一项目中队友的会话。请将已批准的架构记录和稳定约定与 brain 一起保留。

---

参考

以下内容均为参考信息：介绍各部分的工作方式、写入的内容，以及功能边界。上方的目录链接到各个章节。

大脑的工作原理

它与笔记文件夹的区别不在于形式，而在于这份记忆是一种机制， 而非归档约定。

• 决策有生命周期。 新决策与旧决策矛盾时，会取代旧决策。过时卡片会带着箭头和日期归档，绝不会删除；之后的回答会呈现修正内容，而非已失效的旧内容。如果后续决策又回到更早的、已被取代的立场，高置信度的沿袭关系会在新卡片上留下带日期的 re-adopts 标记，并添加一条较早→当前的边；原有的 A→B→C 历史保持不变。
• 修正会明确标出，而非靠猜测。 遇到大写的修正提示或显式边时，才会触发取代。brain_reconcile 只会提出过时内容与修正内容的配对，供人工确认。
• 卡片可以引用作出决策时对应的代码。 ev: 锚点会记录文件:行号，以及采集时的 git blob OID，因此引擎可以标记出引用代码后来已有变动的卡片。它只能检测代码发生了变化，绝不会判断该说法已不再正确。
• 位置有意义。 将卡片拖入 📌 Focus 区域，它就会成为今后每次会话摘要的优先内容。这影响的是摘要优先级，而非检索排名。
• 你可以询问项目当时的认知。 使用 as_of: 2026-03-01 调用 brain_ask，会根据卡片生命周期日期重新调整排名，因此后来作出的修正不会倒灌到过去。
• 检索在本地进行。 使用设备端模型（“按含义搜索”）时，brain_ask 和 search_all_brains 会使用 BGE 语义排名，并结合词法匹配来处理精确标识符、路径和版本——仍完全在你的机器上运行。不使用该模型时，检索仅基于关键词。此前的交叉编码器可通过 KLYPIX_RERANK=1 用于实验，但默认关闭，因为在冻结的人类释义评测中，它降低了精确率并增加了延迟。
• 已为你安装按含义搜索（1.97）。 用户在终端中运行 npx klypix-mcp install 时会安装它：首次下载约 150 MB；移除 Node 永远不会加载的文件后，磁盘占用约 110 MB。使用 --no-semantic（或 KLYPIX_SEMANTIC=0）可跳过安装。没有终端的安装场景——CI、脚本或运行安装的 AI Agent——只有使用 --semantic 才会安装。Claude 插件绝不会下载它。在冻结的 102 个问题集上测得：启用后，54 个问题的正确卡片排在前 5 位；不启用时为 19 个。
• 准备大脑时，提问无需等待。 每张卡片只会转换成一次语义向量（笔记本电脑 CPU 上每张约 45 毫秒，一次处理一张，峰值内存约 305 MB）；低优先级后台任务会从最新卡片开始处理，并在过程中保存结果。对于尚未准备就绪的大脑，提问会立即根据已准备的内容和关键词作答，并说明准备进度（“正在为此大脑准备按含义搜索：已处理 3,670 张卡片中的 900 张，预计还需约 5 分钟”）。此后，只会处理新增或编辑过的卡片。

有界语义记忆运行时

长期运行的 MCP 和 A2A 工作进程默认使用有界语义记忆运行时。只有在请求语义处理时才会加载模型；每个进程内的原生推理会串行执行；嵌入处理会拆分为小批次；临时张量会在使用后释放。已加载的模型会在空闲一段时间后卸载，并在下次语义请求时透明地重新加载，因此温热查询仍然快速，同时不会永久占用原生模型内存。这些控制仅改变资源生命周期；脑卡片、项目协作和磁盘上的脑数据格式均保持不变。

旧版运行时仍可用于紧急回滚。在 MCP 服务环境中设置 KLYPIX_SEMANTIC_MEMORY_MODE=legacy，然后重新连接或重启宿主。这会恢复模型的预热加载和之前的推理路径，不会迁移或删除脑数据。移除此变量（或将其设为 bounded）即可返回有界运行时。

运行确定性生命周期测试：npm run test:memory。如需选择性运行真实模型的长时间压力测试，请将 KLYPIX_MEMORY_SOAK_BRAIN 设为可丢弃或已备份脑数据的路径，然后运行 npm run test:memory:soak。

如需进行进程级归因，请运行 npx klypix-mcp runtime（或添加 --json；--watch 30 表示每 30 秒采样一次）。该命令会分别报告 KLYPIX 工作进程、监督进程和旧版启动器的开销，不包含所属 IDE／聊天应用的 RAM，会对命令行机密进行脱敏，并且绝不会打开脑数据或终止进程。同一宿主下的多个进程会报告为并行会话；在没有权威逻辑会话凭据的情况下，不会将其称为重复进程。

项目地图：在了解项目的基础上查看当前结构

如果项目包含兼容的 NetworkX node-link graph.json，Agent 就可以通过一次只读调用，获取有界的代码结构证据和当前脑数据上下文：

project_map_context {
  "question": "what owns refresh-token rotation?",
  "graph_path": "graphify-out/graph.json"
}

使用 compare_to 和另一个相对于项目的图产物，即可根据两个有界查询邻域，添加精确的节点／边总数差异以及新增／移除项。两个路径都限制在声明的项目根目录内；不安全的源路径会被隐藏；过大或不受支持的产物会被拒绝。如果返回的脑卡片指向某个精确映射的源路径，结构化响应还会包含一条仅供审阅的证据链接建议。该功能绝不会把相似性提升为事实，也不会将图事实或链接写入 brain.klypix。

Graphify 是第一个兼容的生成工具。KLYPIX 会读取用户单独生成的产物，不会捆绑、安装或运行 Graphify，也不表示双方存在合作关系。兼容的通用 graph.json 也可通过相同的供应商中立接口使用。

如需在每个拉取请求和主分支推送时生成可复现的地图产物，请将附带的只读工作流安装到 Git 检出目录中：

npx -y -p klypix-mcp klypix-project-map setup-github /path/to/project

除非明确指定 --force，否则该命令不会覆盖已有工作流。安装的工作流具有 contents: read 权限，所有操作均按提交 SHA 固定版本，graphifyy==0.9.33 也已固定版本；它会验证图契约，并将 graphify-out/ 作为保留 14 天的构建产物上传。这是可选的 CI 代码：本地 MCP 工具仍绝不会安装或启动 Graphify。

支持的宿主及其集成级别

各级别均如实标注。对于 link 宿主，仅测试了写入配置的部分；宿主端的行为未经验证。

宿主	级别	接入方式	注入上下文的简报	决策记录	实时状态
Claude Code	全自动（自 1.105.0 起支持 6 个生命周期钩子）	install	会话开始时自动注入；每次提示词均按任务排序检索	自动，在轮次结束时	是
Codex	原生 MCP + 状态检测 + Context Gateway；可选 --codex-hooks	install	通过 brain_sync；仅使用 --codex-hooks 时才会逐条提示词注入	仅显式记录（brain_note）——绝不自动记录	是
Cursor	MCP 配置 + 始终生效的规则文件	link	模型必须调用 brain_sync	模型必须调用 brain_note	针对 MCP 连接
Cline	MCP 配置 + 始终生效的规则文件	link	模型必须调用 brain_sync	模型必须调用 brain_note	针对 MCP 连接
VS Code（Copilot / Continue）	MCP 配置 + 指令文件	link	模型必须调用 brain_sync	模型必须调用 brain_note	针对 MCP 连接
Gemini CLI / Antigravity	MCP 配置 + 始终生效的规则文件	link	模型必须调用 brain_sync	模型必须调用 brain_note	针对 MCP 连接
Windsurf	仅规则文件	link	通过 Windsurf 自己的全局 MCP 配置使用工具	模型必须调用 brain_note	通过其自己的 MCP 配置
Aider	仅规则文件（无 MCP）	link	CLI 路径：npx -y -p klypix-mcp klypix-read	CLI 路径：npx -y -p klypix-mcp klypix-append	—
Claude Desktop	一次性配置：使用 KLYPIX 的 Settings 按钮，或手动编辑	KLYPIX 应用或由你操作	模型必须调用 brain_sync	模型必须调用 brain_note	针对 MCP 连接

install 和 link 是不同的操作，不能互换：install 会设置机器引擎和钩子，然后为此项目检测到的受支持宿主接入（见 快速开始）。 link 则是针对每个项目的显式修复／投射路径，会处理全部 14 个受管理文件，无论安装了哪些宿主。

Claude Desktop——在 KLYPIX 桌面应用中，依次选择 Settings → Project → Connect Claude Desktop，即可为你写入此条目；也可以手动将其添加到 claude_desktop_config.json。无论采用哪种方式，电脑上都需要 Node.js；在工具列表中看到这些工具之前，必须完全退出 Claude Desktop（托盘图标 → Quit）并重新打开：

{
  "mcpServers": {
    "klypix": {
      "command": "npx",
      "args": ["-y", "klypix-mcp", "--vault", "/absolute/path/to/canvases"]
    }
  }
}

作为 Claude 插件运行

KLYPIX Claude 插件会以 npx -y klypix-mcp@<version> 的形式启动此服务，使用其 .claude-plugin/plugin.json 中指定的版本：必须是一个确切版本，不能是版本范围或 latest。它会设置三个变量：KLYPIX_PLUGIN=1、KLYPIX_PLUGIN_DATA=${CLAUDE_PLUGIN_DATA} 和 KLYPIX_VAULT=${CLAUDE_PROJECT_DIR}。 KLYPIX_PLUGIN=1 会启用插件模式，只会改变 MCP 服务的行为，不会影响其他内容。每条 npx klypix-mcp 命令（install、link、doctor、sessions 等）都与本 README 其他部分所述完全一致。只有 KLYPIX_PLUGIN=1 才会启用插件模式；单独设置 CLAUDE_PLUGIN_ROOT 不会启用。

插件模式绝不会执行的操作

• 自行更新。 它不会向 npm 查询是否有更新版本，也不会安装新版本，无论 KLYPIX_AUTO_UPDATE 设置为何。你运行的是插件固定的版本；只有发布新版插件时，你才会获得更新版本。
• 运行软件包之外的代码。 它只运行固定软件包内的 worker。它不会启动或切换到 npx klypix-mcp install 放入 ~/.claude/project-brain 的副本，也不会从该文件夹加载可选的本地语义模型。搜索仅基于关键词，因此它绝不会下载模型权重。
• 写入项目配置文件。 它绝不会在本项目或任何其他项目中创建或重写规则文件、编辑器 MCP 配置（.mcp.json、.cursor/、.codex/config.toml 等）或 AGENTS.md 简介块。在插件模式之外，brain_sync 和更新程序会写入这些文件；安全与权限一节会说明具体情况。
• 更改 Claude 的设置。 它绝不会写入 ~/.claude/settings.json、hooks、权限或任何其他宿主配置。
• 收集数据或读取凭据。 它不会发送遥测或使用数据，不会读取 API 密钥或账户令牌，也不会打开网络端口。它读取的唯一令牌是 KLYPIX 应用运行时为 AI 工具写入的本地桥接令牌（见下文）；该令牌绝不会被记录或返回。

网络。 插件模式会发起两类请求，且都发送到公共 npm 注册表。第一类是 npx 在插件启动服务时下载固定的软件包。第二类是执行一次 npm view klypix-mcp version，且仅当 Agent 调用 brain_doctor 并设置 check_npm: true 时才会执行。除此之外不会发起其他请求。

它在你的电脑上运行的程序。 在项目中执行只读的 git 命令（查看当前分支、标签和日志），用于协作和发布检查。还会运行本节末尾介绍的 brain_reopen。此外，在 Windows 上，当 KLYPIX 已关闭时，若以 bring_to_front: true 调用 show_in_klypix，它会请求 Windows 在 KLYPIX 中打开该画布文件（PowerShell Start-Process），每 30 秒最多一次；KLYPIX 正在运行时绝不会这样做。

KLYPIX 应用运行时（本地，不涉及网络）。 在 Windows 上，需要使用 KLYPIX 应用的工具调用（Klypix 中的人工控制下的应用模式）会通过本地命名管道与应用通信，即在这台电脑上进行进程间通信。插件模式允许这样做，与插件模式之外完全相同。服务启动时不会建立任何连接；只有在此类调用发生时，它才会读取 %APPDATA%\klypix\agent-bridge\endpoint.json 和 KLYPIX 写入 %LOCALAPPDATA%\klypix\agent-bridge 的桥接令牌。如果 KLYPIX 已关闭，或其此电脑上的 AI 工具开关已关闭，则完全不会建立连接。

它读取的内容。 在你的项目中：brain.klypix、.klypix 画布、package.json 的 version 字段和 git 标签。在你的电脑上：下表中的协作文件。如果已安装 KLYPIX 桌面应用，它还会以只读方式读取应用的数据文件夹（%APPDATA%\klypix），以确认应用是否正在运行、打开了哪些画布，以及它保存在卡片上的读数；在需要使用运行中应用的调用中，它还会读取应用的桥接令牌（见上文）。它绝不会读取聊天记录、转录文本或 Claude 的记忆。

它写入的内容及位置

位置	内容	原因
你的项目	仅包含工具调用所需的内容：brain.klypix（brain_note 和其他 brain 工具）、画布（create_canvas、add_to_canvas）、调用 project_map_scan 时使用的 klypix-map/graph.json、要求 brain_sync 发布版本声明时使用的 .klypix/claims/<owner>.json，以及 brain_rules 添加、批准或退役规则时使用的 .klypix/rules.json。仅当你运行 npx klypix-mcp check --install-hook 时，才会在 .git/hooks/pre-commit、pre-push 和 post-commit 中添加标记区块；npx klypix-mcp rules allow 会将其一小时例外记录在 .git/klypix-rules-allow.json 中。写入 brain 期间会持有 .claude/brain-capture.lock；如果项目中没有 .claude/ 文件夹，就会创建该文件夹。写入完成后会删除锁文件，但保留文件夹。创建画布时，会短暂在该文件夹中持有 .klypix-create.lock。	KLYPIX 应用和其他所有写入 brain 的会话都会使用相同的锁，因此两个写入方不会互相覆盖。
插件的数据文件夹（KLYPIX_PLUGIN_DATA）	连接回执（.supervisors/）、运行中服务的心跳信息（.running-servers.json）、你使用过其 brain 的项目列表（search_all_brains 会读取 registry.json），以及每个项目中记录的最后一个版本和 git 标签（ship-observations/）。还包括 extracted/：将你询问的画布中的 PDF、Office 文件和其他文件复制到此处，再以本地路径交给你的 AI 工具，供 read_card_contents 使用。	只有此服务会使用这些文件。如果未设置 KLYPIX_PLUGIN_DATA，或其中仍包含未填入值的 ${...}，则会使用 CLAUDE_PLUGIN_DATA。如果两者都不可用，文件会存放在 ~/.claude/project-brain 中；但 extracted/ 会存放在 <system temp>/klypix-mcp/extracted 中（在插件模式以外也始终存放于此）。
~/.claude/project-brain（共享）	在线状态通道（sessions/）、写入锁（locks/）、恢复点（history/），以及根据你的 brain 生成的小型记录：.capture-gap.json，还有在使用相关工具时生成的 enrichment/、provenance/、.brief-cache-* 和 .guards-*。rules/ 会统计每条项目规则在这台电脑上触发、拦截或被覆盖的次数。	这台电脑上的其他 KLYPIX 会话（Claude Code、Codex、Cursor、该应用）会有意共用这些文件。借助这些文件，同一项目中的插件会话和终端会话可以互相查看、在计划编辑相同文件时收到警告，并传递备注。恢复点保存在此处，因此即使你移除插件，npx klypix-mcp brain-history 仍可撤销对 brain 的写入。

brain_reopen。 有时，一个会话会给另一个已经关闭的会话留备注。 此时，Agent 可以调用 brain_reopen，KLYPIX 会先征求你的同意：在聊天中显示带有 Reopen 和 Not now 按钮的提示，或弹出一个小对话框（Windows 上使用 PowerShell，macOS 上使用 osascript，Linux 上使用 zenity 或 kdialog）。只有选择 Reopen 后，它才会打开一个新的可见终端，运行应用自身的恢复命令：claude --resume <id> 或 codex resume <id>。详情请参阅 Reopen on your OK。

卸载插件后。 Claude Code 会移除插件并删除其数据文件夹。以下内容会保留：属于你的 brain 和画布；brain 写入在项目中创建的任何 .claude/ 文件夹；以及 ~/.claude/project-brain 中的在线状态通道、写入锁和恢复点。这台电脑上的其他 KLYPIX 工具会共用该文件夹。如果你不使用其他 KLYPIX 工具，可以将其删除。

任务简介

每次 Claude Code 会话启动时，都已了解项目：上下文中包含一份不超过 2KB 的精简简介，完整简介则写入磁盘，以便在需要查阅广泛历史或状态时使用。

其他宿主每次通过一次 brain_sync 调用获取一份约 2.8KB 的精简任务摘要，另有一段精简的常驻加载 AGENTS.md 内容，告知 Agent 在任务开始、范围变更和任务完成时调用该工具。网关摘要经过专门设计，能够快速进行词法检索。新捕获的未解决事项只有在达到常规词法相关性门槛后，才能占据标记为 RECENT OPEN 的专属位置，这样新近且相关的发现就不会被较早的领域词汇挤掉。调用声明了 files 时，提及这些文件的经验会优先列出，置于“适用于你文件的经验”标题下：最多四条，按精确路径、文件名、glob 和文件夹排序。Claude Code 简介也会对检出内容正在更改的文件（未提交内容及最近三次提交）执行相同操作，然后再列出最新内容。

在 Cursor、Cline、Copilot、Gemini CLI 或 Antigravity 上，简介不会自动注入——这些宿主没有生命周期钩子。

实时投影——Agent 遵循的文件

协调测试台显示，Agent 更信任启动时加载的指令文件，而不是工具或钩子告知的内容，并且各宿主读取的文件位置也各不相同。因此，大脑的状态会分成两部分投影到这些文件中：

• 已提交，来自大脑：AGENTS.md 中的精简简介块（常驻规则、修正、未解决的交接卡），仅当内容发生变化时才由 Claude Code Stop 钩子刷新，以保持差异安静。
• **机器本地，来自工作通道（klypix-mcp 1.104.0）：**此电脑上正在运行的会话及其占用的文件、已停止会话遗留的工作，以及每条“不要碰这个文件”备注旁的依据——由 Claude Code 和 Codex 钩子在会话开始时及每次 Stop 时写入项目根目录的 CLAUDE.local.md（Claude Code 会在加载 CLAUDE.md 时一并加载此文件；KLYPIX 通过 .git/info/exclude 将其排除在 git 之外，绝不提交），并写入 Codex 全局指令文件中每个项目各自的一个部分（如果有 ~/.codex/AGENTS.override.md，则写入该文件，否则写入 ~/.codex/AGENTS.md）。绝不会写入项目级的 AGENTS.override.md：Codex 每个目录只加载一个文件，因此它会遮蔽你的 AGENTS.md。

该块是一个快照，并会明确说明这一点：大小限制约为 2.4KB，仅当内容发生变化时才会重写（仅时间戳变化绝不会触发写入）；超出预算时，保留勿碰文件的依据优先；并会用文字明确写出“当前没有活动项”，以免旧快照被误认为仍然有效。该块包含钩子打印的相同字符串，因此文件内容与会话上下文不会相互矛盾。超过一天未触及的项目会从 Codex 文件中清理，最多保留八个项目；uninstall unlink 会移除该块（仅当 CLAUDE.local.md 中没有其他内容时才会删除该文件）。brain_sync 仍是实时信息源；该块会告知 Agent 调用它。

捕获与修正

brain_note 接受结构化的支持性引用和不执行的验证文本：

{
  "text": "Retry failed uploads with a bounded backoff to preserve queued work.",
  "area": "Storage",
  "evidence": [{ "kind": "file", "ref": "src/uploads.mjs:42" }],
  "verify": "node test/uploads.mjs"
}

文件引用必须位于项目范围内。捕获内容会记录工作文件的指纹，并在可用时记录仓库 HEAD 修订版。指纹未变化表示源未变化，并不代表记忆中的说法正确，也不代表测试已通过。脏工作文件会按当前状态生成指纹；仅 HEAD 无法描述这些字节。读取结果会区分源已更改、缺失和未验证。外部引用（pr、url、commit、run）会被保留，但不会获取或验证。verify 会作为已记录文本显示，绝不会执行。可选的 verifiedAt 明确表示由调用方报告。 在修订（marker: "~"）时，省略的元数据会保留；evidence: [] 和 verify: "" 会清除过时的元数据。解决（✓）会归档现有证据；附加新证据时，请提供里程碑和 closes，或先修订再解决。CLI 可通过标准输入接受相同的 JSON，也可使用 --evidence '<JSON array>' 和 --verify '<text>'。

在 Claude Code 中，每轮结束时都会从转录中的内联 🧠 BRAIN [Area]: 标记自动捕获决策，在捕获锁下进行去重。

标记末尾可以带可选后缀，顺序不限：closes: <card title or [[wikilink]]>、 ev: <file[:line]>, PR#<n>、verify: <command>、q: <the question this answers?> 和 rule: <glob>[,<glob>] never "<text>"（或 never /<regex>/、must "<text>"、 listed-in <file>[,<file>]、keep-eol、costly）。这些后缀只有在行尾连续出现时才会被识别，并且必须用小写形式写成 key: value；每个值都必须符合相应键的格式：ev: 后是引用，verify: 后是命令，q: 后是问题（以疑问词开头，以 ? 结尾）。其他内容都会保留为卡片文本，因此“a Q: and A: layout”、“the ev: field”或“every agent verify: the tag”都不会提前截断笔记。格式错误的片段即使出现在格式正确的片段之后，也会保留在文本中，而其他后缀仍会生效；钩子会在下一次提示时告知 Agent。在 ✓ 和 ~ 标记上，closes: 是普通文本，因为这些标记不会关闭任何内容。无法生效的 closes: 会让整句话保持原样：它没有指向任何未关闭的卡片，或指向的卡片超过四张。若 closes: 前面没有句子结尾、[[wikilink]] 或其他后缀，它只会关闭标题与其内容完全匹配的卡片。若它指向的卡片已经关闭，就不会再关闭其他内容。若 ~ 更新内容太少，不足以替换原卡片（少于六个实质性词语，且不足原卡片的一半），则会作为带日期的 (~ amended …) 行追加到该卡片。卡片会保留原有日期、颜色和探针，预览中会将最新的修订显示在最前面。修正会生效，不会丢失任何内容。

rule: 后缀会让新的经验（决策、+ 或 !）具备成为规则的条件。其 glob 必须匹配仓库中受跟踪的文件，且 /regex/ 必须能够编译；规则会以可见的 ⚙ rule candidate: 行记录在 🛠️ 卡片上，并且 brain_rules 会在读取任何正文前先读取它。在有人批准规则之前，它不会检查任何内容。未通过这些检查的规则不会被记录，但经验会保留，钩子会在下一次提示时说明原因。brain_note 也会在文本末尾接受相同的后缀。

Stop 钩子每次都会读取完整转录，因此 ~ 或 ✓ 行只会生效一次。升级后，旧版钩子（1.85 或 1.86.0）已捕获的标记不会再次捕获。如果 1.86.0 提前截断了笔记，系统会在原处将残缺文本恢复为完整内容。标记未按预期生效时，下一次提示会告知 Agent。已结束会话留下的回执会交给该项目中启动的下一个会话。

在其他所有宿主环境中，捕获需要显式执行：brain_note 会运行与钩子相同的捕获引擎，包括去重、取代、往返重新采纳回执、✓ 解决、~ 原位更新、+ 技能和 closes:，并注明编写卡片的 Agent。✓ 问题偏好只会为已满足原始词汇重叠和两个主体身份锚点条件的候选项排序；泛化的生命周期措辞不能让重叠度不足的候选项变成关闭对象。 （如果通过 KLYPIX 应用安装 git 提交钩子，或运行 npx klypix-mcp git-hook install， 提交消息也会为任何 Agent 自动捕获。） brain_challenge 则反其道而行：提出一项决策，由大脑给出证据——与之确定性矛盾的过往决策、对此有异议的既定规则，以及曾尝试后又撤回的方法（若由其他 Agent 编写，则会标明）。证据仅限确定性证据（明确的纠正提示、极性相反的配对），绝不会仅凭主题相似性判断。没有结果表示未发现矛盾信号，并不代表已验证一致性。无法与你意见相左的记忆，只是在奉承你。

项目规则：避免重蹈覆辙的经验

有些经验可以通过差异进行检查：每个新增路由都必须同时列入路由列表、此文件夹中的测试必须使用相对路径导入共享代码、不得更改此文件的换行符格式。brain_rules 会将这些经验转换为 .klypix/rules.json 中的规则，并为每条规则注明其来源卡片。每条规则都需要由人员使用只有他们能打印出的代码批准（npx klypix-mcp rules code promote <ids>）。在此之前，规则只是候选项，不会进行任何检查。

启用后的规则会在三个地方运行：brain_sync 会列出与会话文件相关的规则；编辑钩子会在编辑期间向 Claude Code 和 Codex 报告检查结果；选择启用的 git 钩子（npx klypix-mcp check --install-hook）会在提交和推送时打印规则。规则默认发出警告。人员使用 --block 批准的规则会阻止任何工具或人员提交或推送，并会阻止 Claude Code 写入违规行；Codex 只会收到警告，因为它的钩子无法阻止操作。检查会针对差异进行 glob、正则表达式和换行符格式检查：耗时仅几毫秒，可离线运行，且不使用模型。例外、绕过和误报都会记录在大脑中，npx klypix-mcp rules 会显示每条规则的阻止、例外和误报记录。

规则的编写、批准和弃用方法：docs/brain-rules.md。若要查看一组规则在某个代码库自身的历史记录中会标记哪些问题，scripts/brain-rules-proof.mjs 会在该代码库的拉取请求和失败的 Actions 日志上重放这些规则，并显示这些运行的成本。 团队操作指南：阻止 AI Agent 重复犯同样的错误。

在线状态和任务意图

活跃会话是指已授权的 MCP 连接或主机生命周期适配器在 TTL 内发送过心跳。最近聊天列表中的一行代表历史记录，而非在线状态。

每个 MCP 连接都会在初始化时注册自身，并在断开连接时移除自身；TTL 用于覆盖崩溃情况。可选的主机适配器会合并到同一逻辑会话中，而不是重复计数；它们会补充意图和文件信息，并且只移除自身的通道。未声明任务的会话仍会计入，但会单独显示为范围未知，不会填充对端列表。

未来的主机只需连接 MCP 服务即可获得基础支持。更深入的适配器可以导入 klypix-mcp/presence，并将生命周期事件映射到 upsertSession、removeSession、peekMessages 和 receiveMessages。共享契约接受 id、client、surface、model、branch、intent、已触及的 files 和适配器的 channel。

重叠警告

brain_sync 会报告与同一项目大脑中的其他活动会话之间的三种重叠情况：

• 同一文件。 两个会话都声明编辑了同一路径，或被观察到正在编辑同一路径。你可以看到对方会话、其任务和共同涉及的路径；系统还会向先到的会话排队发送一次性提醒，确保后来者并非唯一知情的一方。
• 合并时可能发生冲突。 两个会话位于不同分支，且对两个分支的最新提交进行测试合并（git merge-tree，git 2.38 或更高版本）时，在指定文件中发生冲突，尽管它们声明的文件并无重叠。这项检查只考虑已提交的工作：未提交的编辑对 git 不可见。系统也会发送一次性提醒。项目大脑工具在每个分支上都会重新生成的文件（AGENTS.md、规则文件、.mcp.json、brain.klypix）不计入。
• 同一文件夹（提示）。 两个会话在同一个文件夹中工作，但目前没有共同涉及的文件。不会发送提醒。至少有三个会话且其中超过一半会话涉及的文件夹会被视为噪声，不予报告。

这些警告仅作提示，不会阻止操作。编辑不会被拦截。未声明文件且从未被观察到编辑的会话，不会出现在文件和文件夹检查中。

在其他电脑上的队友（KLYPIX 网络）

默认情况下，在线状态、重叠警告和便条仅在一台电脑上可见。从 klypix-mcp 1.106.0 起，如果两台电脑都安装了 KLYPIX network 这个独立的小型后台程序（curl -fsSL https://klypix.com/network/install.sh | sh，或 Windows 上的 irm https://klypix.com/network/install.ps1 | iex），这些信息也会传到队友的电脑上：

• brain_sync 还会列出队友电脑上同一项目中的 Agent 会话，并显示其单行任务和声明的文件，同时提供与本机其他会话完全相同的精确文件重叠警告。
• brain_message 也能联系这些会话。它们的 ID 以 net: 开头。发送给所有会话的便条会同时发给本机和队友电脑上的会话。

会离开电脑的信息：项目密钥（git 远程地址的哈希值）、单行任务、相对于仓库的文件路径，以及你发送给对方会话的便条文本。卡片、文件、差异和屏幕内容不会通过这种方式传输；项目大脑本身仍通过 Git 同步。不同电脑之间没有已读回执，也不会协调结果。警告仅作提示，与单台电脑上的警告完全相同。

如果没有安装该程序，一切照旧。设置 KLYPIX_NETWORK=0 时以及在插件模式下，该功能会关闭。目前尚未发布双电脑测试结果。

交接与消息

brain_message 会为其他会话留下一次性协调备注——无论会话正在运行、处于空闲状态还是最近刚关闭。通过会话 ID 指定接收方：正在运行的会话会在下一次操作时收到备注；KLYPIX 之前识别过、但当前不在通道上的会话（已关闭或处于静默状态）也会在下一次操作时收到定向备注——定向备注会保留 7 天，发送方会收到“已排队”而非“已送达”的通知。这就避免了让人类在两个 Agent 之间传话：每个主机收到的常驻规则都是，本来需要请用户转达或粘贴的消息，应改用这种方式发送。这里的操作都不会自行启动或唤醒会话——备注会一直等待，直到有人打开会话；何时打开由用户决定（见下文的由你确认后重新打开）。受支持的 KLYPIX 操作会在模型可见的上下文中提供备注；下一次独立的受支持操作会再次提供该备注并记录确认。此确认只能证明后续操作发生在备注提供之后——不能证明有人读过备注，也不能证明 Agent 采取了行动。接收模型调用 brain_message_receipt 并提供准确的消息 ID 和每位接收者对应的提供令牌之前，备注会持续重放；只有绑定该令牌的操作才会记录为 consumed。待处理、已提供和已确认的备注在重新连接后仍会保留。过期或因容量限制而被逐出时，会记录失败的接收者级回执，而不是悄悄显示为已送达。发送时的受众名单固定不变，无法解析的定向发送会失败关闭，核心通道仅限本机使用，发送给所有会话的备注会在 24 小时后过期，定向备注会在 7 天后过期，并且备注绝不会写入 brain。

由你确认后重新打开

如果会话已经关闭，发给它的备注通常要等到有人再次打开该会话时才能送达。用户想尽快处理时，发送方 Agent 会调用 brain_reopen，随后 KLYPIX 会征求用户的同意——在支持 MCP elicitation 的应用（Claude Code、Codex）中显示聊天内的重新打开 / 暂不提示，否则显示一个小型原生对话框。只有选择重新打开后，KLYPIX 才会在新的、可见的终端中，在该会话工作过的文件夹里，使用主机自己的恢复命令（claude --resume <id>、codex resume <id>）打开该 Claude Code 或 Codex 会话；会话会在第一次操作时收到等待中的备注，发送方也会像往常一样看到回执。

• 由用户决定，绝不由模型决定：答案来自应用的提示或 KLYPIX 自己的对话框，任何 Agent 都无法点击。如果两者都不可用，就不会打开任何内容，并会向用户提供要运行的命令。
• 只有收到发给自己的备注的会话才会重新打开——KLYPIX 重新打开对话是为了让备注送达；它不会启动、路由或监督 Agent。
• 重新打开的会话收到的第一条提示词是固定文本，告知它收取备注；备注本身会通过带标签的消息通道作为来自另一会话的信息送达，绝不会被输入成仿佛是用户说的话。发送方的会话身份不会泄露给接收方。
• 暂不会被记住：一段时间内不会再次向同一会话显示提示，连续双击也不会打开两个窗口。
• 在终端中：npx klypix-mcp sessions 会列出此项目已关闭的会话及等待送达给它们的备注；npx klypix-mcp sessions reopen <id> 会重新打开其中一个会话（--quiet 会让它等待你，而不是因收到备注而启动）。

会话交接——与任意 Agent 在下一个会话中继续

这个功能旨在解决这样的情况：Claude Code 会话在任务进行到一半时达到使用限额，于是用户打开 Codex（或一个全新的 Claude Code 会话）并说继续。在 1.99.0 之前，唯一的交接方式就是用户粘贴内容。现在有两个层次，而且用户不必主动要求任何一种。

自动——无论哪个 Agent 停下。 每个会话的最后状态都会记录在原本用于记住会话、且会保留两周的通道上，具体方式取决于主机提供的功能：

宿主	自动记录的内容
Claude Code (hooks)	最后一条提示词、最后一条回复的尾部内容、编辑过的文件、它自己提交的 commit
Codex (hooks)	最后一条提示词、最后一条回复的尾部内容、编辑过的文件、它自己提交的 commit
任何 MCP 宿主 — Cursor、VS Code、Windsurf、Gemini CLI，……	通过 brain_sync 声明的任务和文件

自己提交的 commit 是该会话的 git commit 打印出的 SHA，而不是分支范围，因为二十个会话可以共用一个检出副本。会话在过去 24 小时内停止、尚未完成任务且留下了记录时，就会列出——静默十分钟，或已关闭。没有记录任何内容的会话永远不会列出，因此已结束的聊天不会越积越多。

项目上的下一个会话，无论使用哪个 Agent，只要其任务是继续某项工作（“继续 Codex 在发票上的工作”会优先显示该会话），或会话触及了其中某个会话碰过的文件，就会在首次调用 brain_sync 时看到 ⏸️ 其他会话可能留下的未完成工作。会话启动时也会看到同一列表。每条记录都包含其状态、文件、commit、最后的话和恢复命令。文本和 JSON（state、working:false、holdsFiles:false）都会说明该会话并未运行、不占用任何文件，也说明它留下的“请勿触碰”备注已不再适用：该列表是历史记录，不是锁。Agent 使用 brain_handoff {action:"take", session:"<id>"} 接手一条记录，让其他会话知道该记录已被接手，然后将其标记为 done。这一层与这条工作流程的其他部分一样，仅限本机使用。

主动交接。 会话知道自己即将停止时——用户要求交接、上下文或用量限额将至、一天结束、遇到阻塞或正在切换工具——就会调用 brain_handoff {action:"write"}，写明任务、已完成的内容、接下来按顺序要做的事、相关文件和验证方法。这会成为项目知识库中的一张 🤝 HANDOFF 卡片：一张用户可以在画布上查看并修正的开放卡片，以相关文件作为证据锚点，随仓库一起流转，并像其他卡片一样同步。在某个会话接手（{action:"take", id}）并完成卡片（{action:"done", id}，该操作会将其归档）之前，这张卡片都会显示在会话启动简报和 brain_sync 启动响应的最前面。后续交接可以注明其 continues 哪张较早的卡片。每条提示词触发的钩子都会在用户说出 handoff 或提到限额时，提醒 Agent 创建交接卡片。

由 KLYPIX 起草 — 会话来不及自行创建交接卡片时。 用量限额、崩溃或关闭窗口可能导致没有时间调用 brain_handoff。从 1.103.0 开始，知识库会自行创建卡片：任何会话在下一次 brain_sync 启动时，或任何会话调用 brain_handoff list 时，如果某条记录符合条件——会话已关闭或已静默 30 分钟，留下了实际工作（自己的 commit，或编辑过的文件和回复尾部内容），没有卡片也没有接手者，并且任务来自用户而非应用——就会代替该会话创建一张 🤝 HANDOFF 卡片，原因标为 中断。卡片会在单独一行写明 Drafted: by KLYPIX，在 已完成 部分仅列出 Git 能证实的内容，提醒读者在触碰任何内容之前先用 git status 确认状态，并原样保留该会话的最后几句话。记录及每份列表都会注明该会话没有自行创建卡片。如果会话恢复并完成任务，这张自动起草的卡片会在下一轮处理时归档。每轮最多起草三张；起草失败绝不会导致触发它的同步失败。 对话覆盖范围。 卡片和自动回复尾部可能会遗漏后续请求。 现在，接手卡片时会检查其源对话，并报告 needs-review、reviewed 或 unknown。brain_handoff {action:"review", id} 会返回分页的 Claude Code 或 Codex 对话轮次，包括没有收到回复的用户请求。使用返回的 revision 继续请求 nextCursor； 阅读完每一页后，使用包含已完成和仍待处理请求的 summary 确认最终的 reviewToken。 仅限会话的接手操作使用带 session 的 review，先创建可审核的草稿。首次审核涵盖整个对话， 包括卡片创建前的请求；源内容字节发生变化会使审核失效，必须重新审核。 已保存的审核是 Agent 的确认声明，并非任务完成的证明。它不会关闭工作项。 对话记录保留在本机，且只从受支持主机的对话记录文件夹读取。 缺失、格式错误、有歧义、超出大小限制或不受支持的来源会报告 unknown；附件 占位符需要检查原始媒体。读取器的限制为每份对话记录 128 MiB、每条 JSONL 记录 16 MiB、 对话文本 8 MiB，以及 12,000 个发现条目。达到限制时绝不会静默丢弃对话轮次或确认覆盖完整。 继续操作前，请根据对话和仓库证据核对卡片的 Next 列表。

主机覆盖范围（1.108.0）。 共享交接卡不受 Agent 品牌影响。对话恢复的覆盖范围则各不相同：

来源	可用证据
Claude Code、Codex	原生本地对话记录读取器
Gemini CLI	原生旧版 ConversationRecord JSON；JSONL 变更日志目前返回 UNKNOWN
Antigravity、Cursor、Cline、Roo Code、Kilo Code、GitHub Copilot、Continue、Windsurf、OpenCode、自定义 MCP 客户端	通过相同的 MCP 操作进行与主机无关的捕获；不声称提供原生历史记录读取器
仅限 CLI 的集成，例如 Aider	共享交接卡；捕获需要调用此操作的 MCP 桥接

在没有原生读取器的主机上，请在收到请求时使用以下方式保留请求： brain_handoff {action:"capture", turns:[{id:"stable-turn-id", role:"user", at:1792860000000, text:"Observed request"}]}。 使用实际已知的时间戳（毫秒）、稳定的 ID 以便重试，并且只记录实际观察到的文本。 也要捕获助手回复。不要编造缺失的历史记录或时间戳。服务端会将捕获内容绑定到已连接的会话和项目；调用方不能提供其他会话身份或文件路径。 后续会话使用相同的 review 工作流。新捕获的对话轮次会使之前的审核令牌失效。 重复的相同对话轮次会去重；拒绝重复使用但内容冲突的 ID。

捕获是明确的 Agent/工具操作，并非自动访问 IDE 私有聊天存储的能力。 结果始终会标明覆盖范围为 captured-only，并说明完整主机历史记录为 UNKNOWN， 即使审核后也是如此。它无法恢复从未捕获的请求。主机名称回归测试样例验证的是共享协议， 而非这些应用内部的端到端运行情况。 捕获的文本保存在大脑之外的 ~/.claude/project-brain/handoff-captures 中，按 项目和会话进行分类。它不会与卡片同步，也不会自动过期；在本地移除后，覆盖范围信息将不可用。限制为每次调用 30 个对话轮次、每轮 24,000 个字符，以及每份日志 8 MiB。Gemini 的发现过程有 128 MiB 的总读取预算，并会拒绝有歧义的来源。

重要决策仍应作为卡片存入大脑——交接卡是唯一关于进行中工作的卡片，工作完成后便会关闭。

由证据门控的完成

当任务发布量化或其他可通过机器检查的声明时，可以在 brain_sync { phase: "complete" } 中附加一个或多个有版本号的结果清单。每份清单都会将声明绑定到报告哈希、生成者／运行来源、明确声明的任务范围、重要工件哈希、评估输出、公开指标表述、输入／配置指纹，以及带有计数和容差的命名指标。匹配的同伴证据会记录为佐证；相冲突或不可比较的证据会返回 needs-reconciliation，并使任务范围保持激活状态。

该门控采用默认拒绝策略。任务一旦提交结果证据，就不能通过不附带清单的方式重试完成流程来绕过无效或冲突的结果；即使工作进程重启、休眠或透明热切换，这项义务仍然有效。新的 phase: "start" 是显式的新任务边界。严格的架构和可复用的验证器通过 klypix-mcp/result-reconcile 导出。Schema-v2 回执可转换为绑定到提交的发布证据，并使用 klypix-mcp/release-evidence 独立检查；旧版 schema-v1 结果仍可用于协同，但不能授权发布。

Klypix 中的人工控制

不是第二个大脑，而是共享的大脑。

没人能检查的大脑，只是一个营销做得好的数据库。KLYPIX 桌面应用会将同一个 brain.klypix 呈现为动态空间地图，并提供健康度、新鲜度、来源和天体仪表盘视图、未解决问题的分类处理视图，以及一键式流程，可将文件夹的大脑连接到六种编码 Agent。你可以阅读、更正、归档并重新关联 Agent 记录的内容。

该文件由双方共同持有。应用保存大脑时，会在与 Agent 钩子相同的捕获锁内重新读取磁盘副本，并进行并集合并而非覆盖，因此即使你打开文件时 Agent 捕获了一张卡片，该卡片也会保留。合并过程会验证自身输出；如果输出文件缺少卡片，就会中止，而不会将其写出。删除操作需要明确的墓碑记录，因此绝不会仅凭卡片缺失就推断其已被删除。

该应用是独立的专有 Windows 产品。格式、本服务和钩子采用 Apache-2.0 许可，即使未安装应用也可运行。应用界面提供英语和阿拉伯语（部分较新的面板仍仅提供英语）。

KLYPIX 画布与 AI 工具

除了项目知识库，同一连接还可以读取和写入保存在你 PC 上的 KLYPIX 画布（空间）。你的 AI 工具会读取 KLYPIX 已经读取的内容，以及已保存画布中包含的文件：

• read_canvas 会列出每张卡片及其 ID；read_card_contents 会返回卡片中的内容。来自 KLYPIX 已保存的内容：视频卡片上的转录文本、为短视频或网页创建的文本卡片 Read contents、照片的 OCR 卡片，以及文件夹中的文件列表。来自已保存画布中嵌入的文件，即使 KLYPIX 已关闭也可读取：文本文件中的文字、照片（文件较大时会读取较小副本），以及 PDF、Office 和其他文件的本地路径，以及 KLYPIX 保存的预览——参见下文的 读取卡片中的内容。音频和视频只会返回路径；其中的语音内容来自 KLYPIX 保存的读取结果。对于短视频、网页或视频，请先在 KLYPIX 中选择 Read contents（选中卡片后按 Enter），等待画布保存，再向 AI 工具提问；或者，在 Windows 上打开 KLYPIX 时，让 AI 工具请求 KLYPIX 读取内容（见下文的 应用模式）。
• KLYPIX 会遵循用户的设置：已锁定、禁止 AI 工具访问的框中的卡片不会出现在任何读取结果中；冻结的卡片会标记为只读；折叠的框、评论和标签都会显示出来。
• klypix_status 会告诉 AI 工具 KLYPIX 目前在这台 PC 上能做什么，以及用户需要执行哪个步骤。
• **KLYPIX 中打开的画布不会被写入。**包含打开画布租约的 KLYPIX 版本（%APPDATA%\klypix\agent-bridge\endpoint.json，其中没有密钥）会让 add_to_canvas 拒绝写入该画布并说明原因；项目知识库除外，因为 KLYPIX 会对其进行合并。对于较旧版本的 KLYPIX，add_to_canvas 会执行写入，并在回复中提示用户关闭该画布的标签页后重新打开。
• 从卡片、网页、短视频和文件返回的文本都会被标记为数据，而非指令。

应用模式：AI 工具在 KLYPIX 运行时使用它

在 Windows 上，只要 KLYPIX 应用处于打开状态，且 Settings → Project → AI tools on this PC 已启用（默认启用），同一连接即可访问正在运行的应用。此时，KLYPIX 会运行自己的代码来处理请求，因此它的密钥、同意设置、限制、冻结和撤销规则都会生效。关闭 KLYPIX 或关闭此开关后，所有工具都会按上述说明以文件模式运行；需要应用才能执行的步骤会用一句话说明原因（APP_NOT_RUNNING、ACCESS_OFF、BLOCKED、NEEDS_APP 等）。

工具	KLYPIX 已打开（应用模式）	其他情况（文件模式）
read_card_contents	对于在 KLYPIX 中打开的画布，由 KLYPIX 自行读取卡片，就像其「读取内容」功能一样；每条结果都会说明由谁支付（paid_by）	读取 KLYPIX 已保存的内容，以及嵌入画布中的文件
read_canvas	实时读取在 KLYPIX 中打开的画布：未保存的更改、用户的视图（镜头、筛选器、已折叠的框），以及每张卡片是否在屏幕上、被筛选器隐藏、位于已折叠的框内或在屏幕之外。视图筛选器不会移除卡片	已保存的文件；画布在 KLYPIX 中打开时，回答会说明未保存的更改不包含在内
add_to_canvas	对于在 KLYPIX 中打开的画布，卡片会立即出现，标记工具名称，一次撤销即可撤回，并由 KLYPIX 保存	写入文件；如果画布已在 KLYPIX 中打开，则拒绝操作。项目大脑始终以文件形式写入，由 KLYPIX 合并
show_in_klypix（仅限 Windows）	在该画布的标签页中选中并定位卡片，可选显示一行横幅并标注工具名称	APP_NOT_RUNNING；设置 bring_to_front: true 后，Windows 会在 KLYPIX 中打开画布文件
brain_lens	新鲜度、来源、活动、天体仪和未解决项均来自 KLYPIX 自己的镜头代码：即用户看到的画面	根据已保存的文件计算
klypix_status	还会报告用户面前的画布、其选区、视图、KLYPIX 可读取的内容，以及该工具今天剩余的 Gemini 读取次数	已保存的文件和租约中的信息

谁为新读取付费（paid_by）：

卡片	KLYPIX 的操作	paid_by
网页链接	从这台电脑获取并提取页面内容，绝不通过已登录的调试端口浏览器	none
照片	将原始图像交给你的 AI 工具，由其使用自己的模型；如果启用了 OCR，还会附上 KLYPIX 的 OCR 文本	ai_tool
PDF、Office 或文本文件、文件夹	在这台电脑上读取嵌入画布中的文件	none
YouTube 链接、短视频	由 Gemini 观看：使用用户自己的密钥，否则使用 KLYPIX 内置的 AI。只有在用户已允许 KLYPIX 的视频助手时，才会读取短视频；否则读取其字幕和封面，并标记为部分内容	own_gemini_key 或 included_ai
视频或音频文件	如果这台电脑上已安装转录功能，则在本机转录；否则使用上述 Gemini 方式	none，或如上所述

• 已保存的读取结果会优先返回，不消耗任何额度；refresh: true 会请求新的读取结果。
• AI 工具的 Gemini 读取次数由额度上限约束，而非由提示词决定：每个工具每天 20 次，所有 AI 工具合计每天 40 次；每次调用最多读取 5 张卡片，每个工具最多同时运行 3 次读取。
• 新读取结果会用箭头和工具名称固定在卡片旁边；完整读取结果显示为翠绿色，部分读取结果显示为琥珀色；在 KLYPIX 中按一次 Ctrl+Z 即可移除。用户的选区和视图不会改变。
• 每个回答都会在约 45 秒内返回。仍在运行的读取会返回 still_reading 和 retry_after_seconds；使用相同参数再次请求即可继续获取同一次读取结果，不会额外消耗额度。
• 输入架构没有变化。read_card_contents 仍然需要 canvas 和 card_ids：若要读取用户在 KLYPIX 中选中的内容，请先调用 klypix_status，它会列出用户面前的画布和选中的卡片 ID。
• KLYPIX 的 since、storage 和 weight 镜头在 brain_lens 的 view 列表中没有对应名称，因为该列表是固定的；klypix_status 会报告用户当前打开的镜头。

控制。 AI 工具默认处于开启状态。用户可以在 KLYPIX 的「设置 → 项目」中关闭 AI 工具或屏蔽某个工具；其中会列出每项请求的时间、工具、请求内容、画布和结果，但绝不会列出卡片文本、链接或令牌。工具名称由各 AI 工具自行报告，因此只是标签，不能证明其身份。 连接的工作方式。 启用开关期间，KLYPIX 会监听一个命名管道，该管道的名称在每次启动时都会随机生成；同时，它会在你的 Windows 配置文件中将一个新的随机令牌写入 %LOCALAPPDATA%\klypix\agent-bridge\token。每次调用需要使用该应用时（启动时不会），klypix-mcp 都会重新读取 endpoint.json 和令牌；发送请求前，双方都会证明自己持有该令牌。klypix-mcp 不会向无法证明自身身份的管道发送任何内容。令牌和管道名称绝不会被记录、返回给 AI 工具或由 brain_doctor 显示。在你的 Windows 账户下运行的任何程序都可以读取该令牌。

读取卡片中的内容

KLYPIX 保存的画布会保留每个拖入文件的副本。read_card_contents 会将这些文件原样交给你的 AI 工具，由它使用自己的模型和文件工具读取——KLYPIX 本身不会在这里提取任何内容（不进行 OCR、转录或文档文本提取；这些操作由 KLYPIX 应用完成）。传入 read_canvas 输出的 ID；每张包含内容的卡片都会有一行 Inside:，说明返回的内容。

卡片	AI 工具会获取什么
文本文件（.txt、.md、.csv、.json、源代码等）	文件中的文字，以代码围栏包裹并标记为数据（每张卡片最多 max_chars 个字符，每个回答最多 48,000 个字符）。如果文件更长，内容会被截断并标记为 truncated，同时提供整个文件的本地路径。
照片	照片本身。如果照片太大，无法放入单个回答，则会以较小的 JPEG 副本形式提供（长边不超过 1,568 px，并根据 EXIF 方向信息旋转至正向），同时提供原始完整尺寸文件的本地路径。视觉模型无法处理的格式（BMP、HEIC、TIFF）会以路径形式提供，并说明原因。
PDF	PDF 的本地路径——Claude Code 的 Read 工具会打开它——以及 KLYPIX 保存的第 1 页图像。
Word、Excel、PowerPoint 和其他文件	文件的本地路径，以及 KLYPIX 保存的预览：文档的开头文本、工作表的前几行。
文件夹	文件列表。添加 entry_paths（列表中最多 8 个文件路径）即可按相同方式获取这些文件。无法访问文件夹之外内容的路径会被拒绝；超过 64 MB 或解压后体积超过存储大小 200 倍的条目会被拒绝，并附上其大小。保存在磁盘上的文件夹（非嵌入式）会从其所在位置读取，绝不会读取其外部的内容。
音频、视频	KLYPIX 保存的转录内容（如果有）。否则会提供本地路径，并明确说明回答中没有关于其内容的信息；如果有视频保存的海报帧，也会附上并标注为单帧。

如果 KLYPIX 已经读取过 PDF、Office 或文本文件，返回内容还会首先包含 KLYPIX 保存的文本（method: document_text），并在旁边附上文件路径。仅当卡片仍包含读取时对应的文件时，才会使用这些文本：不会提供或显示较早版本文件的读取结果，也不会通过 read_canvas 显示或通过 search_canvases 匹配该结果；文件本身则会按上述方式交付。

限制及原因：

• 单个回答不超过 1 MB。 Claude Desktop 会拒绝超过 1 MB 的完整工具结果，因此单个回答中的图像共用 800,000 个 base64 字符的额度（read_card_contents 和 read_canvas 中最多 4 张图像）。即使缩小后仍无法放入回答的照片会列出名称并说明原因。
• 文件通过路径提供，而非作为嵌入式二进制内容。 MCP 嵌入式资源若携带 PDF，目前会被 claude.ai 的连接器层拒绝，因此 PDF 和 Office 文件会被复制一次到缓存文件夹，并以路径形式提供：作为 Claude 插件运行时，路径位于插件数据文件夹中的 extracted/；否则位于 <system temp>/klypix-mcp/extracted，文件名为 <sha-256 prefix>-<original name>。超过 150 MB 的文件不会被复制出来。没有文件读取工具的 AI 工具（未连接文件系统的 Claude Desktop）会获取预览和路径，而不是整个 PDF。
• 添加到共享空间的 iPhone 照片或文件不会存储在画布文件中（KLYPIX 会在运行期间获取它），因此无法从已保存的画布中交付；回答会对此作出说明。
• 锁定为不允许 AI 工具访问的框内卡片，绝不会被读取、复制或附加。

亲自测量

关于共享大脑的说法——“什么都不会丢失”“速度始终很快”——在陌生人能够重新运行测试之前都无法证伪，因此基准测试已随包提供 （）：

npx klypix-mcp bench            # ~25s, or --quick for a smaller run

它会测量真实操作系统进程间的并发写入安全性、协调延迟、包含漂移的 1,000 次查询压力测试，以及 SIGKILL 下的崩溃安全性，最后打印运行测试的机器信息。

它会先运行负向对照。 绕过锁的写入者会先于实际写入者运行，因为除非同一套测试程序能够检测到丢失，否则“丢失数为 0”毫无意义。在参考机器上，这些未加锁的写入者丢失了 22 张卡片中的 17 张；通过锁定协议承受相同竞争时，46 张卡片中丢失数为 0。如果对照组始终没有丢失，测试结果会报告为无法得出结论，而不是通过。

最新结果及硬件和日期信息见：BENCHMARKS.md。

这会改变 Agent 的行为吗？ 要回答这个问题，需要使用真实 Agent，因此相关内容放在代码仓库中，而不是软件包里：bench/coordination/ 会在四个小型仓库上运行 Claude Code 或 Codex。在这些仓库中，另一个会话掌握着 Agent 所需的信息（今天刚变更的决策、另一个分支上重叠的工作、已结束会话留下的备注，或另一家供应商的会话发现的根因）。每次运行都会在 Agent 完成后，通过编写的测试进行评分，并与以下方式比较：不使用共享渠道、人工复制粘贴、保持整洁或追加内容的 AGENTS.md，以及仅通过 MCP 使用 KLYPIX。每个数字都会附上样本量和区间；尚未测量的工具会标记为未测量。运行 --dry-run 不会产生费用，并且可以验证评分程序。

Git 与并发

仓库中的一个文件，与你的代码一起提交——可纳入版本控制、可分支、可移植。这样，两位开发者就已经像共享代码一样共享一个大脑：克隆、分支、拉取。

准确来说，git 本身的作用是：brain.klypix 是一个二进制 ZIP 文件。Git 会显示 Bin 1308328 -> 1309005 bytes，且不会生成任何行级差异，因此开箱即用时，发生冲突就只能全盘采用我方或对方的版本，审阅者也看不到任何内容。卡片级合并安全性由 KLYPIX 引擎提供——但从 1.48.0 起，你可以把该引擎交给 git，并在 PR 中查看其输出：

npx klypix-mcp git-driver install     # once per clone, in any repo

这会为 *.klypix 注册一个合并驱动程序（添加一行针对单台机器的 git 配置，并提交一条 .gitattributes 规则），同时部署它所需的引擎。两人修改大脑，其中一人拉取时，git 会调用引擎而不是停止操作：保留双方新增的卡片；仅一方编辑的卡片采用该方的编辑；双方编辑方式不同的卡片则两个版本都保留——第二个版本作为关联副本，绝不静默覆盖。（“采用该方的编辑”有一项例外：如果某张卡片的含义与其旁边的冲突副本完全相同（指整张卡片，而不仅是文字），就不会更改任何一个版本；驱动程序的摘要行会说明这一点。删除你不想要的那个。）删除操作也会同步：被删除的卡片会在大脑的已删除卡片中留下凭据，驱动程序会对这些记录进行三方合并，因此，某个分支上已删除或永久删除的卡片会继续保持删除状态，不会从另一分支复原，除非另一分支编辑了它。如果删除分支记录了该删除操作（即卡片在其已删除卡片中留有凭据），这项编辑会作为新卡片恢复；如果没有记录，编辑过的卡片就会保留。即使如此，永久删除的卡片仍会保持删除状态：驱动程序的摘要行会统计它丢弃的编辑，而这些编辑仍保留在该分支的 git 历史中。返回结果前，合并程序会断言结果仍包含双方所有未删除的卡片；如果有卡片丢失，就会拒绝返回结果。

需要坦诚说明其适用边界：未运行 git-driver install 的机器只会遇到旧式二进制冲突——这属于安全降级，而非数据损坏；而且 git 会保留每次合并的两个父提交，因此即使不喜欢某次合并，也可以还原。这种合并发生在拉取时，而非实时同步。

在代码审查中，两个命令可以把二进制文件转换成人类可读的内容：

npx klypix-mcp diff main            # card-level: what was added / updated / removed
npx klypix-mcp pr-brief origin/main # the brain cards that reference this PR's changed files

diff 比较的是含义，而不是字节（重新保存会重设时间戳，这不算更改）。 pr-brief 会将卡片的 #file-… 证据锚点与变更路径匹配，让审阅者看到关于眼前代码已经记录的决策。examples/github/brain-pr.yml 只使用代码检出和默认的 GITHUB_TOKEN，就能通过这两个命令生成固定的拉取请求评论——无需调用 KLYPIX 服务。

并发会话会在捕获锁后依次执行；每次写入都会先写入临时文件，再通过原子重命名完成，因此写入过程中崩溃也能保留之前的有效文件。该锁仅提供建议性约束，预算约为 3.6 秒：超时后，写入方仍会继续操作，并在运行状况日志中标记此情况，因此持续争用仍可能导致更新丢失。这是一项有意为之的权衡——舍弃这些标记被认为更糟——但它确实存在限制，并非保证。

恢复点

合并、整理和维护旨在保留所有无人删除的卡片（有一个刻意设定的例外：永久删除某张卡片后，在其他副本同步时，该卡片也会从大脑的其他副本中消失，包括经过编辑的副本；合并报告会显示这次编辑）。永久删除并不能保证文本在所有地方都消失：如果有人差不多同时在另一台机器上恢复了该卡片，或恢复后调整了大小或进行了编辑，该副本可能仍然存在，也必须在那里删除；此外，恢复点和 git 历史会保留其中已有的内容。它们都无法撤销的是看似有意的删除：你选中十几张卡片，将它们删除并保存。这不是需要防止的错误——大脑必须能够纠正，而无法纠正的记忆比没有记忆更糟——但我们需要提供恢复途径，因为大脑是共同所有的：钩子、MCP 服务、提交捕获机制和其他机器上的对等端都会在无人留意时写入其中，因此你可能会毁掉自己从未见过的新内容。

因此，每次写入大脑前，都会先为此前的字节创建一个恢复点：

npx klypix-mcp brain-history list          # age, card count, delta against the brain now
npx klypix-mcp brain-history restore <id>  # and this is itself undoable

恢复操作会将内容合并到当前的大脑中，而不是覆盖文件，并会显示所做的更改。恢复点中的卡片会回来——自恢复点创建后被删除的卡片会以新 ID 返回，因此大脑的所有其他副本都会一致认为旧卡片已被删除——而恢复点之后写入的卡片会移至已删除卡片（npx klypix-mcp brain-deleted list），其中每张卡片都可以恢复。永久删除的卡片仍会排除在外，除非传入 --include-purged。

恢复点存储在 ~/.claude/project-brain/history/ 下，而不会放在大脑旁边——不会有任何内容进入 git、合并驱动程序的路径或差异中；即使 .klypix 文件本身被删除，它们也会保留。常规写入会去重，并限制为每分钟一次；移除卡片的写入永不受此限制，因为这正是恢复点要处理的情况。保留策略是最新的 20 个，以及 14 天内每天一个，因此即使错误逐渐累积，也仍可恢复，同时避免无限增长。无法写入的快照会记录日志并跳过——绝不会阻止保存。

普通画布不会有这些机制。这类画布上的每一笔都由一个人完成，且每次更改都清晰可见；大脑则不同，那里并非如此。

这是谁的内容？共享工作区的 git 防护

从 1.105.0 起，当多个 AI 会话共享同一个工作区时，Claude Code 钩子会在 git 命令运行前进行检查：

• 如果某条命令会将另一个活跃会话尚未提交的工作一并纳入你的提交（git add -A、git commit -a 或指定对方的文件），就会被拦截。提示会指出该会话，并给出仅针对你自己的文件的精确命令。
• 如果某条命令会丢弃工作（git reset --hard、git checkout -- <file>、git stash、git clean），系统会先保存一个救援副本（refs/klypix/rescue/*），然后询问你。若无人可询问（绕过模式），则会拒绝执行。使用 npx klypix-mcp rescue restore <id> 恢复副本；使用 npx klypix-mcp rescue list 查看副本。
• git status 会指出哪些已更改文件属于其他会话。
• 不会拦截已停止会话留下的内容。如果 Agent 仍在继续这项工作，系统会告知它可以完成并提交这些内容。

模式：KLYPIX_WHOSE=enforce（默认）、shadow（仅警告并记录日志）或 off；也可以在 ~/.claude/project-brain/whose.json 中使用 {"mode": ...}。Codex 所做的编辑也会被记录，以便防护机制知道内容属于谁。

适用范围：它会防护通过 Claude Code 工具运行的 git 命令，且仅限一台计算机。它不会防护文件编辑或其他工具中的工作，也无法防止冲突。在协调测试中，与 KLYPIX 一样，一条谨慎的指令也在 5 次“清理”运行中的 5 次保护了另一个会话的工作。

命令行

以下 MCP 动词是 Agent 调用的。这些是你调用的：

命令	功能
npx klypix-mcp init	在此处初始化一个入门版 brain.klypix，并打印 MCP 配置
npx klypix-mcp install	完成所有设置：机器引擎和钩子，然后设置此项目——脑库、你所用编辑器的配置、合并驱动，并进行验证（参见快速开始）
npx klypix-mcp link	重新生成全部 14 个受管理文件，无论当前安装了什么（--check 用于审计）
npx klypix-mcp doctor	给出一项综合结论：版本、宿主、活动会话、工具数量、偏差。退出码非零，可用作 CI 门禁
npx klypix-mcp runtime	被动统计每个连接的进程和内存占用（--json，可选 --watch seconds）；绝不终止进程或去重
npx klypix-mcp conformance	针对当前构建启动两个真实 MCP 客户端，并验证协同行为
npx klypix-mcp git-driver	为仓库注册卡片级 .klypix 合并驱动（使用 status 检查）
npx klypix-mcp git-hook	接入与 Agent 无关的提交捕获钩子：在提交时，将来自任何 Agent、分支或工作树卡片中带有理由的 feat/fix/perf 提交写入脑库（install/remove/status；会话会在钩子插槽空闲时自动安装此钩子）
npx klypix-mcp brain-history	此脑库的还原点——使用 list 列出，使用 restore <id> 还原。每次写入脑库前自动创建，保存在机器本地；对于会删除卡片的写入，绝不会因限流而省略
npx klypix-mcp diff [ref]	以 Markdown 格式显示脑库与某个 Git 引用的卡片级差异
npx klypix-mcp pr-brief [ref]	以 Markdown 格式显示引用自某个引用以来已更改文件的脑库卡片
npx klypix-mcp garden-code	打印 brain_garden 要求的人工批准码
npx klypix-mcp check	在工作树、--staged 或 --base <ref> 上运行此项目的规则（.klypix/rules.json）；--install-hook 用于接入可选的提交前、推送前和提交后钩子
npx klypix-mcp rules	项目规则中面向使用者的部分：每条规则的计数和建议、code promote|retire <ids>（批准码）、allow <id> --reason（一小时）、false-alarm <id> --reason
npx klypix-mcp rescue	恢复丢弃前保存的 Git 保护副本：list、show <id>、restore <id> [paths…]、prune
npx klypix-mcp sessions	此项目已关闭的会话及等待这些会话处理的笔记；sessions reopen <id> 可重新打开一个会话

这些动词：27 个，Windows 上为 28 个

工具	功能说明
brain_ask	全脑问答——支持修正感知和按 as_of 时间回溯
brain_challenge	让大脑反驳：提供矛盾及证据、尝试后又撤销的链条、常驻规则，以及其他 Agent 的来源标记
brain_note	记录完整生命周期——取代／重新采纳／✓ 解决／~ 更新／🛠 技能／closes:
brain_reconcile	提出过时内容与修正内容的配对、未记录的迁移，以及某个版本引用所含提交看似关闭的未完成卡片；然后关闭你确认的确切配对
brain_insights	枢纽、孤立决策、过时问题、各区域大小
brain_lens	机器可读的时效性、来源、活动、时间线、星盘和未解决内容视图；在 KLYPIX（Windows）中打开的画布上，前五种视图由 KLYPIX 自带的镜头代码提供
brain_garden	维护流程——先提出建议；整合操作必须使用人工生成的审批码才能应用。单独的 repair:"duplicate-partials" 流程先进行试运行，无需代码（只删除完全重复的内容，不归档任何内容）
brain_rules	根据大脑的经验教训制定项目规则：propose 将每条经验教训分流到规则、指令或备注；add 将候选项写入 .klypix/rules.json；promote 和 retire 会在 MCP 表单或 Windows 审核对话框中征求用户意见（也可使用终端代码）；启用阻止功能需要批准 block:true；check 根据差异运行规则；status 显示阻止、覆盖、误报和退役建议。检查时不使用 AI（文档）
brain_doctor	自检：版本、核心／增强型宿主适配器、活动会话、工具数量、投影偏差
brain_message	会话间协调备注——发送给正在运行的会话，或排队等待未运行的会话下次启动时接收——受众在发送时固定，并提供每位接收者的待处理／已提供／已确认／已消费／失败回执（定向备注保留 7 天，广播保留 24 小时；绝不会写入大脑）
brain_message_receipt	使用确切的消息 ID 和每位接收者的提供令牌，明确记录模型端的消费情况；仅确认绝不会消费备注
brain_handoff	会话交接。工作尚未完成便停止会话时，write 会在大脑中写入一张 🤝 卡片，记录任务、已完成事项、后续顺序、文件和验证；任何 Agent 的下一次会话都会在首次 brain_sync 时看到并接手（take），然后将其标记为 done。list 还会显示 KLYPIX 为每个会话自动记录的未完成工作（最后回复、文件、自有提交，以及自 1.103.0 起的工作目录和每个检出工作树的未提交状态，因此侧边检出工作树中遗留的修复会直接列出，无需搜索），并可按会话 ID 接手。自 1.103.0 起，若会话停止时没有写入卡片（例如达到使用限额或崩溃），则会在下一次 brain_sync 启动或 list 时根据该记录由 KLYPIX 起草一张卡片，并标记为 Drafted:，原因是中断；若该会话后来完成任务，则会将其归档
brain_reopen	重新打开已关闭的 Claude Code 或 Codex 会话，让等待该会话的备注立即送达——仅当用户在聊天提示中或 KLYPIX 自带的对话框中回答重新打开后才会执行；在该会话的文件夹中打开一个新的可见终端，并使用宿主提供的恢复命令
brain_sync	上下文网关：任务摘要、活动任务中的协作方、精确文件重叠、一次性提醒、时间信息，以及可选的结果清单协调
brain_connect	查找并绘制相关但尚未关联的卡片
project_map_context	在修正感知的大脑上下文旁提供只读且有界限的代码图谱证据，并提出精确路径审核建议；支持外部产物（例如 Graphify），但绝不会在本地安装或运行
project_map_scan	KLYPIX 自带的零安装扫描器：遵循 gitignore 的文件清单和文件级导入边（解析相对路径、tsconfig 别名和 monorepo 工作区导入），并写入 klypix-map/graph.json，之后 project_map_context 会自动使用该文件
project_map_drift	只读偏差报告：列出引用的文件已删除或移动的大脑卡片（附带重命名候选项）；若检出工作树落后于其 origin 默认分支，还会提供摘要提示
canvas_view	将画布作为结构化渲染规范和文本摘要返回，并声明一个 MCP Apps (SEP-1865) UI 资源
read_canvas	在 KLYPIX（Windows）中打开的画布会由应用实时读取：包括未保存的更改、用户的视图和每张卡片的可见性。否则以 Markdown 形式提供画布内容：每张卡片及其 ID、连接图、[[links]]、#tags 和标签胶囊、状态、评论、回应、冻结和折叠的框，以及 KLYPIX 已保存的链接、视频和照片卡片读取结果；附上照片卡片的图像（较大图像会附上缩小副本），并标注对应卡片；每张含有内容的卡片都会列出可返回该内容的 read_card_contents 调用。用户锁定为不可供 AI 工具访问的框内卡片会被排除，并统计数量。使用 KLYPIX 显示的标题作为名称
read_card_contents	读取最多 5 张卡片的内容——影片、YouTube 视频、网页、视频或音频文件、照片、PDF、Office 或文本文件，或文件夹。在 KLYPIX（Windows）中打开的画布上，由 KLYPIX 使用自带读取器读取，并说明费用由谁承担（paid_by）。否则，提供 KLYPIX 已保存的读取结果（卡片上的转录文本、其“读取内容”和 OCR 结果卡片、文件夹列表）——用数据围栏括起，标明完整或部分内容，并注明读取来源（此 PC 或云端 AI）；以及画布中保存的嵌入文件内容：文本文件的文字；照片（较大照片会附上缩小副本，以及原始文件的本地路径）；PDF、Office 和其他文件则以缓存的本地路径及 KLYPIX 保存的预览提供（PDF 首页、文档开头的文字、工作表的前几行）；文件夹条目则根据相同规则列在 entry_paths 中。音频和视频会以路径形式返回；只有 KLYPIX 已保存读取结果时，才会附上其中的语音内容。单次答复不超过 Claude Desktop 的 1 MB 限制。如果卡片需要 KLYPIX 当前无法生成的读取结果，会返回用户需要采取的一项操作；klypix-mcp 本身不会提取文本
klypix_status	显示 KLYPIX 当前在此 PC 上的功能：应用是否正在运行以及打开了哪些画布、从何处读取画布，以及每项功能还需要用户提供什么。KLYPIX 打开时，还会显示用户面前的画布、其选择和视图、KLYPIX 准备读取的内容，以及此工具今天剩余的 Gemini 读取次数
show_in_klypix	仅限 Windows。在正在运行的 KLYPIX 应用中选择并定位卡片，可选显示一行标注工具名称的横幅；KLYPIX 绝不会因 AI 工具而切到前台。KLYPIX 关闭且 bring_to_front: true 时，Windows 会在 KLYPIX 中打开画布文件
search_canvases	按名称、内容、标签和标签胶囊，以及 KLYPIX 保存的卡片读取结果搜索所有画布；返回卡片 ID 和日期。绝不搜索用户锁定为不可供 AI 工具访问的框内内容
search_all_brains	跨项目搜索此计算机上所有已注册大脑中的记忆
create_canvas	根据卡片和连接创建新的 .klypix
add_to_canvas	添加卡片／连接（保留位置），并以边框显示，确保在 KLYPIX 的深色和 Paper 主题下均清晰易读；卡片的 group 会将其放入以该名称命名的框中。在 KLYPIX（Windows）中打开的画布上，卡片会直接添加到 KLYPIX 中：实时更新、注明来源，并可一步撤销。如果 KLYPIX 无法接收，则会拒绝添加（OPEN_IN_APP、ACCESS_OFF、BLOCKED）、框已锁定为不可供 AI 工具访问（SCOPE_LOCKED）或框已冻结（FROZEN），且不会写入任何内容；项目大脑是第一种情况的例外。返回新卡片 ID
list_canvases	列出库中的所有 .klypix
在 Linux 和 macOS 上为 27 个，在 Windows 上为 28 个（其中注册了 show_in_klypix）；可通过 npx klypix-mcp doctor 进行机器验证。其 TOOLS 行应用相同规则，App bridge 行则会说明 KLYPIX 是否正在运行，以及访问权限是开启还是关闭。

**canvas_view：**目前尚未观察到任何 MCP Apps 主机渲染 UI 资源——没有 截图，也没有主机级测试。不支持此扩展的主机会显示纯文本，这是目前 实际验证过的路径。

brain_doctor、brain_lens 和 brain_insights 是只读的内省工具。brain_reconcile 也只读，但有一个例外：当 mode:"claims" 和 mode:"release" 时，你可以传入 confirm / dismiss 来关闭已验证的配对。确认时请指定准确的卡片 ID——不会根据 描述文字进行匹配；若只覆盖多项子句中的一部分，则会写入 ✔ partial，并保持卡片打开， 除非你传入 whole:true。如果调用中的所有条目都被拒绝，大脑将保持逐字节不变。 dismiss 会被记录为两个卡片之间的 not_fulfilled 边，因此，仅有原始提交作为证据的提示 没有可指向的对象——请指定 cardId，或直接解决未关闭的卡片。brain_garden、brain_reconcile 和 brain_connect 始终会先提出方案，再应用。 npx klypix-mcp doctor 会给出一个判定，并在状态偏移时以非零状态码退出，因此也可用作 CI 门禁。

一个可以随身携带的文件

整个大脑——布局、卡片、箭头以及实际字节内容（图片、PDF、音频、视频）——都在一个 .klypix 文件中：这是一个普通 ZIP，包含 manifest.json、canvas.json、每张卡片各一个 JSON 文件，以及一个 assets/ 文件夹。可以通过电子邮件发送、提交到 Git，或交给 Agent。 Markdown 文件夹只会指向附件；这个文件则会将附件一并携带。（将文件拖到画布上时， KLYPIX app 会嵌入二进制文件；本软件包的 create_canvas / add_to_canvas / buildKlypix 会写入卡片和箭头，而不是资源——它们可以读取资源，只是不会创建资源。）

解析器属于本软件包，采用 Apache-2.0 许可证，因此任何工具或 Agent 都可以读写这种格式。完整 规范：FORMAT.md。

Markdown 导出、JSON Canvas 1.0 导出，以及直接打开 Obsidian .canvas 文件，都是 KLYPIX 桌面应用的功能，不属于本软件包——本软件包的可执行文件中没有导出命令。

“项目”可以是任何项目。 npm 软件包和 GitHub 仓库的 examples/ 下都附带了两个 展示用大脑，它们的引擎相同，内容各异： showcase-brain.klypix 是虚构天气应用 Aurora 的开发中版本 （雷达图块、API 限额，以及附有凭据的更正）；而 showcase-wedding.klypix 是 Our Wedding （场地、供应商、宾客名单，以及针对餐饮承办方的同一套更正机制）。它们拥有相同的 📌 Focus、 相同的箭头和相同的简报。只要有值得保留的决策，就可以为它创建一个大脑。

它们包含在 tarball 中，因此你可以直接从 node_modules 读取：

npm i klypix-mcp
npx klypix-read node_modules/klypix-mcp/examples/showcase-brain.klypix

两者都仅包含文本和箭头——14 张卡片、4 个箭头，没有 assets/ 条目——因此它们展示的是 卡片 / 容器 / 连接模型，而不是格式中嵌入二进制文件的部分。

将其用作库

import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown } from 'klypix-mcp';

npx -p klypix-mcp klypix-read   path/to/board.klypix      # → markdown brief
echo '{ "title": "Plan", "cards": [{ "text": "kickoff" }] }' \
  | npx -p klypix-mcp klypix-write --out plan.klypix

也支持 A2A protocol v0.3.0——实验性功能

npx -p klypix-mcp klypix-a2a --vault ./canvases     # 127.0.0.1:41241
# Agent Card: http://127.0.0.1:41241/.well-known/agent-card.json

默认提供八个知识库 / 项目技能：make_board、remember、learn_skill、recall、 read_canvas、list_canvases、brain_insights、brain_connect。面向整台机器的 search_all_brains 是第九个技能，需通过 --allow-cross-project 明确启用。与典型的 A2A Agent 返回文本不同，KLYPIX 会将 .klypix 画板本身作为多模态工件返回。详情见： A2A.md。

请将此功能视为预览版：对抗性 A2A 冒烟测试已包含在默认的 npm test 流程中，但尚未使用第三方 A2A 客户端测试过该服务。

更新——传播约定

MCP 入口是一个稳定的 stdio 监督器，它会在可替换的工作进程运行核心逻辑时，保持由宿主拥有的连接打开。分阶段更新会先进行哈希验证、并行初始化、检查工具架构是否向后兼容，并在监督器切换请求之前，将当前 brain_sync 任务范围交给新工作进程。新增工具使用标准的 notifications/tools/list_changed 信号。如果候选版本失败或存在破坏性变更，就会被拒绝，旧工作进程则继续提供服务。连接空闲 10 分钟后会释放其工作进程并保留连接；在宿主发送请求之前，连接会保持休眠状态。届时启动的新工作进程也会通过相同的检查。如果检查不通过，连接会恢复到上次运行的版本，或者返回可重试的 /mcp reconnect 错误，而不会陷入循环重启。被阻止的结果声明会保存在持久化的项目／会话标记中，因此更换工作进程不会导致证据检查失败后仍无结果地完成任务。

因此，兼容的引擎更新会在同一个活动连接后方生效，无需重新连接或重启宿主。但以下三种情况仍需主动重新连接或手动安装：一次性的旧版→监督器迁移、监督器代码变更，以及主版本更新或移除工具的版本。监督器自身的修复只有在执行一次 /mcp 重新连接或重启宿主后才会应用到连接；工作进程和 doctor 的变更则会热切换。brain_doctor 会报告活动中的监督器（包括仍在运行较旧监督器代码的数量）以及自动更新计划：上次结果、该结果对应的安装，以及下次检查的运行时间。MCP 工具也会以结构化数据返回这些信息。

无论打开多少个会话，更新器每台机器每 6 小时只检查一次 npm。如果另一次安装升级了此运行时，或将其从开发者部署版切换为正式发布安装版，则还会再检查一次，且距离上次尝试至少间隔 5 分钟。例如，手动运行 npx klypix-mcp install 安装较新版本，或正式发布版替换开发者部署版。检查失败后，将分别在 15 分钟、1 小时和 4 小时后重试，之后恢复为每 6 小时检查一次。每次尝试都会先记录为失败，再访问网络，因此若检查中途退出，会进入退避，而不会陷入循环重试。检查由已打开的 KLYPIX 会话执行：监督器和工作进程每 10 分钟检查一次，新会话则在启动 2 秒后检查。

更新器会以 --runtime-only 模式安装同一主版本的精确稳定版，同时保留宿主设置和项目文件；新主版本始终需要手动安装。更新器绝不会降级。若主动降级（npx klypix-mcp@<older> install --force）到高于 1.89.0 的版本，则会暂缓更新：更新器不会重新安装被回滚前的版本，只会安装更新的版本。若要重新安装暂缓的版本，请运行 npx -y klypix-mcp@latest install（或者在下方列出的 KLYPIX_AUTO_UPDATE 已设置的环境中，将 KLYPIX_AUTO_UPDATE_FORCE=1 设置为仅对一次检查生效，然后移除）。回滚到 1.89.0 或更早版本也会一并回滚更新器，而这些版本没有暂缓机制：它们会在上次检查后的 24 小时内重新安装同一主版本中的最新版本。若要继续使用此类版本，请在下方列出的每个位置设置 KLYPIX_AUTO_UPDATE=0，并在使用期间保持设置；若降级未被暂缓，brain_doctor 会发出警告。更新器不会为开发者所有的安装获取任何内容，也不会覆盖此类安装。检查在分离进程中运行，失败时默认放行，并发会话会通过同一个锁合并。

设置 KLYPIX_AUTO_UPDATE=0 即可选择退出。每个进程都会读取自己的环境变量，因此请在每个宿主的启动环境中设置：每个 KLYPIX MCP 服务条目的 env，以及 Claude Code 运行其钩子时所用的环境。该设置会在宿主下次启动监督器或执行 /mcp 重新连接时生效。 还有一个次要的小型探测。在脑项目（包含 ./brain.klypix 的目录）中，Claude Code Stop hook 会刷新本地 npm 版本缓存，下一次 SessionStart 会读取该缓存，以提示是否有可用更新。该提示还会说明更新器将如何以及何时处理这项更新。此探测：

• 每天最多运行一次，包括由开发者管理的安装；
• 发出与更新器相同类型的匿名请求，即 GET 请求 https://registry.npmjs.org/klypix-mcp/latest，不携带任何用户或机器标识符；
• 如果更新器在过去一天内获取过 npm 的最新版本，则跳过；
• 在 Claude Code 运行 hooks 所用的环境中读取 KLYPIX_AUTO_UPDATE=0，并以相同方式关闭探测；
• 绝不安装任何内容。

如果可选的语义运行时已启用，更新还会安排一次脱离主流程的单写入者缓存迁移，覆盖所有已注册的脑。这样可避免模型或缓存升级后首次查询时耗费数分钟重新索引；缓存写入按模型区分，并可在多个并发 Agent 会话间保持原子性。仅使用词法功能的安装不会下载任何内容。设置 KLYPIX_SEMANTIC_WARM_ON_UPDATE=0，即可继续采用首次使用时延迟索引。

安全与权限

• Apache-2.0，源码公开，地址：github.com/dahshanlabs/klypix-mcp。
• 大脑引擎不会发起网络调用，也不会发送遥测数据。 引擎的所有智能都是确定性的，并在本地运行；唯一的大模型是你自己的 Agent。本软件包中有两个例外，即上文所述的两项更新探测。一项是更新程序每 6 小时检查一次 npm 版本；运行时升级后还会额外检查一次，检查失败后则会重试（15 分钟、1 小时、4 小时）。发现有更新的同一主版本时，它还会运行该版本的 npm install。另一项是 Claude Code Stop hook 的版本探测，在大脑项目中最多每天进行一次。两者都是匿名 GET 请求，用于获取软件包的 latest 版本；设置 KLYPIX_AUTO_UPDATE=0 即可关闭这两项探测。
• 可选的语义模型在设备上运行。 启用模型（或升级模型）时，可能会从 Hugging Face 获取模型权重；检索推理和大脑数据均保留在本地。
• 协调状态存储在本地文件中。 大脑是你仓库中的一个文件；在线状态通道是你主目录下的一个文件。不会上传任何内容——只有一个明确且默认关闭的例外：跨 PC 在线状态中继，它仅在你通过 KLYPIX 桌面应用逐个大脑授权后，才会通过该大脑的云通道共享列入许可名单的在线状态字段，以及一次性协调备注的文本。KLYPIX 不会自动附加文件／卡片内容、差异或屏幕数据，但备注中继会传送发送者输入的任何内容（自动重叠提醒会标出相关的声明文件路径）。授权范围带有版本号：旧版的仅元数据授权不包含备注文本，必须重新授权。没有当前授权，就不会传输任何帧。
• KLYPIX 网络是一个独立的可选程序。 安装后，brain_sync 会向其发送本次会话的项目密钥（git 远程地址的哈希，绝不包含路径）、单行意图和相对于仓库的文件路径；brain_message 会向另一台计算机上的会话发送备注文本。不会发送其他内容。计算机之间的流量经过加密；需要中继时，中继也只传递加密流量。未安装、设置 KLYPIX_NETWORK=0 或处于插件模式时，程序都不会运行。
• install 会写入你的主目录： ~/.claude/project-brain（引擎 + 运行时）、~/.claude/settings.json（自 1.105.0 起包含六个 hook——即使未安装 Claude Code，也会写入）、~/.codex/AGENTS.md（指导说明块），以及使用 --codex-hooks 时写入的 ~/.codex/hooks.json。它还会在你运行命令的项目内部写入 <cwd>/.codex/config.toml，并从全局 ~/.codex/config.toml 中移除任何 KLYPIX 条目。link 会在你运行命令的项目内部写入 14 个文件；link --check 会审查这些文件，但不写入。
• 除插件模式外，MCP 服务也会写入这些项目文件。 这 14 个文件不只由 link 和 install 写入。在包含 brain.klypix 的项目中，每当 brain_sync 开始一个任务（phase: "start"）时，服务都会执行两项操作。首先，将该项目添加到计算机的注册表 ~/.claude/project-brain/registry.json（Claude Code hook 也会在此处添加项目）。然后检查项目由 KLYPIX 管理的文件，并创建或重写任何缺失或过期的文件。检查涵盖全部 14 个文件，无论你使用哪种编辑器。其中包括 .mcp.json，其条目会启动已安装的程序包；如果没有已安装的程序包，则会运行未固定版本的 npx -y klypix-mcp，以及 .codex/config.toml。自动更新程序会在安装更新后立即对过去 14 天内出现过的每个已注册项目执行同样的操作；否则最多每天执行一次。KLYPIX_AUTO_UPDATE=0 会停止更新程序执行此操作。插件模式（KLYPIX_PLUGIN=1）会停止这两项操作，并将注册表保存在插件的数据文件夹中；请参阅作为 Claude 插件运行。
• Codex hooks 需要通过 Codex 自身的信任批准，并且必须通过 --codex-hooks 选择启用。
• KLYPIX 应用桥接使用本地 IPC。 在 Windows 上，需要正在运行的 KLYPIX 应用的工具调用会通过此 PC 上的命名管道连接（请参阅应用模式）。KLYPIX 启动时、关闭时或 AI 工具开关关闭时，都不会建立连接；客户端会先验证应用持有本次启动的令牌，再发送请求，并且绝不会记录或返回该令牌或管道名称。

当前限制

在基于其中任何内容进行构建之前，请先阅读本节。

• 除非安装了 KLYPIX network，否则协同仅限本机和当前 OS 用户。 状态文件保存在你的主目录中。单独使用 klypix-mcp 时，两位使用不同机器的开发者看不到彼此的会话、重叠或消息。两台电脑都安装 KLYPIX network（1.106.0+）后，他们就能在同一项目中看到彼此的会话及其意图和声明的文件，收到针对完全相同文件的重叠警告，也能互发备注；已读回执、结果协调和合并测试仍仅限本机。项目匹配依据是 git 远程地址（若没有，则依据文件夹名称）。此软件包还为桌面应用的云通道提供跨机器状态 核心（./presence-relay，默认需征得同意），这是另一条独立路径。
• 文件重叠按完全匹配的路径判断。 会话需要声明文件或有已观察到的编辑，才能进行检查；src/auth/token.ts 与重命名后的路径不匹配。文件夹重叠仅供参考。合并测试只检查已提交的工作，需要 git 2.38 或更高版本，且仅适用于同一仓库中位于不同本地分支的会话。
• 项目规则检查的是差异，不是行为。 它们会检查文件名、新增行、行尾和路径；不会运行代码或测试。除非用户通过 --block 批准规则，否则规则只发出警告；Codex 编辑时会收到警告，但不会被阻止；提交钩子则需要在每个克隆仓库中选择启用。批准码和 Agent shell 中的拒绝机制可以防止意外操作，但无法阻止蓄意绕过。
• 重叠警告仅供参考。 不会阻止任何操作。载荷中的一个严重性字符串是 blocking，但机制并不会阻止操作。
• Codex 不会自动捕获内容，无论是否使用 --codex-hooks。Codex 钩子绝不会写入 brain。
• 卸载不会移除各项目中的文件。 npx klypix-mcp uninstall 用于处理机器全局安装；link 写入每个项目的 14 个文件会由 npx klypix-mcp link --check 列出，并由 uninstall unlink 按项目逐个移除。
• 漂移检测仅限单主机，且需为每张卡片单独启用。 它需要由卡片作者写入 ev: 锚点，并且只会在 Claude Code 钩子路径中运行——MCP 工具不会计算新鲜度。
• search_all_brains 只能搜索已注册的项目。 跨项目注册表由 Claude Code 钩子写入；任何 MCP 主机启动任务时，brain_sync 也会写入。如果某个项目两者都未执行过，该项目就不会出现在结果中，也不会有任何提示：搜索只会返回空结果。在插件模式下，服务会在插件的数据文件夹中维护自己的列表，并将其与共享列表一并搜索。
• npx klypix-mcp link 不会管理 CLAUDE.md。 它管理 AGENTS.md 和另外七个规则文件。只有桌面应用会写入 CLAUDE.md。
• 语义检索取决于安装路径。 通过交互式终端安装时，默认启用设备端搜索运行时。CI 和非交互式安装需要使用 --semantic；使用 --no-semantic（或 KLYPIX_SEMANTIC=0）则表示选择退出。Claude 插件仍仅支持关键词检索。没有模型时，检索会使用关键词；即使正在下载模型或准备 brain，也不保证能找到特定决策。
• 捕获锁在争用超过约 3.6 秒后会以失败开放方式处理（参见 Git 和并发）。
• 已发布的 tarball 不包含 test/。 请从克隆仓库运行测试套件。发布工作流确实会以测试套件作为发布门槛——gate 作业会运行 npm ci、断言测试链完整、运行 npm test、验证版本/标签并检查打包后的 tarball；publish 声明了 needs: gate，因此如果门槛未通过，npm 就不会收到 tarball。
• 应用模式仅支持 Windows，且需要 KLYPIX 应用正在运行并允许使用 AI 工具。其他平台上，工具会以文件模式运行。KLYPIX 中的工具名称只是各 AI 工具报告的名称，并非经过验证的身份：任何以你的身份运行的程序都能读取桥接令牌。
• canvas_view 的 MCP Apps UI 从未在真实的 Apps 主机上经过验证。

数字与方法论

此处的所有数字均基于我们自己的项目大脑测得。以下内容均未发布、未进行基准测试，也未经过独立验证。

• Dogfood 规模。 KLYPIX 本身就是用自己的大脑构建的：2,695 张卡片和 2,333 条连接，由多个并发 Agent 会话编写，文件中留有记录。截至 2026-09-16 的数据。
• 召回率。 一轮搜索找回了 73% 的过往决策，仅凭简报找回 55%，冷启动时为 0%。随数据一并说明的注意事项：n=20，使用我们自己的大脑、问题由我们自行撰写，并由大模型评判。
• 排序器（brain_ask）。 2026-09-16 在实际的 2,695 张卡片的大脑上测得，使用生产环境的嵌入模型，n=107 道冻结问题（由 Agent 撰写、经对抗性验证，分为四个层级）；真实源卡片的模型无关排序：recall@5 63%（95% CI 53–71），recall@10 65%，recall@20 69%，MRR 0.43，top-1 33%。最重要的是诚实反映能力的这一层：与卡片没有任何共同用词的释义问题，recall@5 为 44%；状态、时间和多跳问题为 81–93%，因为它们仍然共享词汇。仅用词法匹配时，同一测试集上的得分为 0%。
• 调用方使用的措辞（brain_ask，1.96）。 问题末尾可以再加一行：Also: <可能会出现在回答该问题的卡片中的措辞>；调用 Agent 本身就是大模型，因此可以零额外成本地猜测卡片的措辞。这些词只会加入语义查询。2026-10-11 在同一个大脑上测得，当时大脑已扩展至 3,829 张卡片（冻结问题中仍有 102 道可回答）；使用 Gemini 2.5 Flash 撰写措辞，作为调用 Agent 的替代：recall@5 54% → 59%（新增 8 道，减少 3 道），recall@8 61% → 68%，recall@20 68% → 76%，MRR 0.375 → 0.424。没有本地模型时（例如使用 --no-semantic 安装，或使用 Claude 插件），这些词会作为额外关键词，以半权重计入： recall@5 19% → 24%（新增 5 道，无减少），recall@10 25% → 31%。不加这一行，排序结果逐字节不变。
• 另一个项目的大脑。 在另一个项目的大脑上使用同一排序器（1,601 张卡片，19 道手写释义，首次跨大脑测试）：recall@5 42%（CI 23–64），top-1 11%，MRR 0.25。释义召回能力可以跨大脑迁移；排序器并非针对构建它时使用的大脑调优。它只是普遍不擅长处理释义问题——这是嵌入模型的上限，已在 rankForQuestion 中记录。
• 已弃用的数据。 “recall@5 30%（n=20）”、“使用重排器后从 15% 提升至 40%”以及“5% → 15% → 40%”曲线均已弃用：第一项来自 n=20 的测试集，已被更大的测试集取代；其余数据是用默认关闭的重排器测得（重新有效测量后发现它降低了 recall@5），或来自已偏离生产向量空间的测试工具（已于 2026-08-10 修正）。退步的数据与提升的数据一并记录：短卡片上的上下文前缀，以及重排器。
• 每条提示词的钩子通道（Claude Code 每个会话在每条提示词上都会收到的检索结果）在 1.86 之前从未测量过。scripts/eval-hook-lane.mjs 现在会通过生产排序器测量该通道，使用从机器自身的增强侧载文件构建的私有捕获对测试集（scripts/build-hook-eval-set.mjs）。首次测量在我们自己的大脑上使用 110 条真实提示词：词法通道对 97% 的含有实际内容的提示词触发，并有 29% 的机会将正确卡片排在前五位；但对于 93% 本不应注入任何内容的提示词（确认回复、控制台回显、转发的机器轮次），整个通道仍注入了卡片。1.86 提高了词法门槛，避免因单个标题词就触发注入；对于少于四个内容词的提示词，也会跳过缺乏佐证的语义猜测：垃圾注入率从 93% 降至 35%，垃圾提示词平均注入的卡片数从 3.6 张降至 1.5 张，代价是在 35 条真实提示词中少命中一道问题（在噪声范围内）。提示词仍为私有；扫描表格存放在源码中，紧邻据此选定的门槛。
• 我们不公布的数据。 不公布下载量：此软件包自身的自动更新程序贡献了大部分下载量，因此下载量并不代表用户数。不公布采用情况、团队或客户数据。不公布简报令牌数据——上一次是在约 600 张卡片时测得的；如今卡片数已达 2,479，该数据已过时。
• 评估工具不在此代码库中。 它位于 KLYPIX 私有桌面版代码库中。上述数据由我们负责辩护，并非供你在此复现——请据此看待这些数据。

卸载

npx klypix-mcp uninstall --check          # preview machine-global removal — writes nothing
npx klypix-mcp uninstall --yes            # remove the machine-global install
npx klypix-mcp uninstall unlink --check   # preview this project's managed files
npx klypix-mcp uninstall unlink --yes     # remove this project's managed files

它只会移除 KLYPIX 自己添加的条目——~/.claude/settings.json 中其他所有钩子和设置都会保留——并会备份它编辑的每个文件，绝不会删除 .klypix。 移除操作需要使用 --yes。不带该参数时，命令会打印计划，不做任何更改； 也不会出现交互式确认提示。要取消链接，请在每个目标项目中运行项目本地形式。只要仍有受管理的文件，预览就会以非零状态退出。项目本地形式还会移除 CLAUDE.local.md 中的实时投影区块（仅当文件中没有其他内容时才会删除该文件），并移除 Codex 全局文件中本项目对应的区块；机器全局形式则会移除其中所有实时区块。

brain.klypix 属于你——它是普通 ZIP 文件，无论是否安装此软件包，都可以读取。

---

贡献

问题反馈和拉取请求：github.com/dahshanlabs/klypix-mcp。 问题或意见：[email protected]。

此代码库包含 89 个测试文件：83 个直接列在 scripts.test 中，另有 pretest 工作流门禁。它们共同覆盖存在性通道及其跨机器中继、Context Gateway、监督器热切换、自动更新、检索质量、衰减、挑战、透镜、格式保护程序、Git 工具（包括通过合并驱动程序执行真实的 git merge）、卸载和一致性测试。从克隆的代码库运行 npm test 即可执行这些测试——它们不包含在已发布的 tarball 中，但发布工作流会将其作为门禁运行。test/mcp-supervisor.mjs 中已知存在一个间歇性的 Windows EPERM 重命名问题。

存在的意义

编码工具各自拥有记忆和指令系统。使用多种工具的团队仍需要一个共享空间来记录决策、原因和纠正内容。将这些记录保存在自己拥有的文件中，便能让受支持的 Agent 通过同一接口读取和更新它。

你的项目、你的文件、任何受支持的 Agent、离线运行。

---

许可证

此软件包——MCP 服务、Agent 钩子和 .klypix 格式解析器——采用 Apache-2.0 许可证（LICENSE，归属信息见 NOTICE）。最高至 1.28.0（含）的版本均以 MIT 许可证发布，仍可按这些条款使用；1.29.0 是首个 Apache-2.0 版本。

KLYPIX 桌面应用和 klypix.com Web 应用是独立的专有产品——其源代码不公开，其条款也不会限制 Apache-2.0 在此授予你的任何权利。此软件包无需安装任何应用即可运行。

Apache-2.0 © Dahshan Labs。