Klypix MCP 为编码智能体提供共享的项目记忆。它面向同时使用多个编码工具（如 Claude Code、Codex、Cursor 等）的开发者，解决上下文在不同工具和会话之间丢失的问题。
用途
当你在同一个代码库上运行多个编码智能体时，一个工具中保存的上下文可能在另一个工具中缺失。Klypix MCP 通过一个随代码提交的 brain.klypix 文件，让项目决策、修正和待解决问题跨会话、跨工具传递。它不启动、运行、监督或替代你的智能体，也不是智能体运行时、模型路由器、工作树管理器或 Git 的替代品。它只保存项目当前所相信的内容。
主要能力
- 决策生命周期：新决策若与旧决策矛盾，会取代旧决策。过时卡片被归档并标注箭头和日期，不会删除；后续回答会呈现修正而非过时内容。若后续决策回到更早被取代的立场，高置信度谱系会在新卡片上留下带日期的重新采纳标记，并保留原始历史。
- 显式修正：取代由大写修正提示或显式边触发。brain_reconcile 仅提出过时与修正的配对供人工确认。
- 证据锚点：卡片可以引用其决策所依据的代码。ev: 锚点记录文件:行号以及捕获时的 git blob OID，引擎可标记所引用代码已发生变化的卡片。它检测代码已变，而非断言变为虚假。
- 位置含义：将卡片拖入 📌 Focus 区域，它会在未来每个会话的简报中优先显示。这是简报优先级，不是检索排名提升。
- 历史查询：brain_ask 配合 as_of: 2026-03-01 可按卡片生命周期日期重新加权排名，使后来做出的修正不会向后泄漏。
- 本地检索：使用设备端模型（“按含义搜索”）时，brain_ask 和 search_all_brains 使用 BGE 语义排名，并辅以词法帮助处理精确标识符、路径和版本，完全在本机运行。没有该模型时，检索仅基于关键词。
使用方式
需要 Node.js 20 或更高版本。在项目内运行安装命令，它会创建 brain.klypix（若项目没有）、连接本机检测到的编辑器、若为 git 仓库则注册 .klypix 合并驱动，并在真实 MCP 握手统计到工具响应后才退出。安装后重新打开编码工具或重新连接其 MCP 服务器，并允许 KLYPIX 工具。可在项目中运行 npx klypix-mcp doctor 检查安装。
典型流程：智能体调用 brain_sync 开始会话并声明预期修改的文件，调用 brain_note 记录决策或修正，调用 brain_ask 检索项目当前信念。文件重叠警告是建议性的，不会阻止编辑。
适用场景
- 同一代码库上运行多个编码智能体，需要共享项目理解。
- 团队需要将架构决策及其原因与代码一起版本化保存。
- 需要追踪决策的取代历史，并检测所引用代码是否已变化。
限制
- 独立设置下，brain 数据保留在你的文件中，但智能体的提供商仍可能收到智能体读取的内容。
- 独立实时存在和文件重叠警告仅限同一机器和操作系统用户。
- 集成深度因宿主而异。
- 语义搜索模型约 150 MB 下载，磁盘约 110 MB；无终端安装需显式 --semantic 才获取。
- 修正提示本身不保证匹配；需确认修正命名了更早的决策。
- 小型试用仅检查捕获和召回路径，不建立大型 brain 的检索质量，也不证明宿主自动化。
