内容
# 为每个项目提供智慧
### 不是第二大脑，而是共享大脑
你已经看到了这样的设置：在一个笔记文件夹前放置一个AI，观察思维导图逐渐填充，然后称之为大脑。仔细观察——**人类从未触及过任何东西**。即使模式的发明者也表示： *"你永远不会自己编写维基……我实时浏览结果。"* 人类只是阅读者，AI是唯一的编写者。那不是大脑——那是水族馆。
**`klypix-mcp` 为你的项目提供一个你允许进入的大脑**。在你的仓库中，只有一个文件—— `brain.klypix` ，通过git进行版本控制，你的AI代理读取、写入并从中争论。在 [KLYPIX 应用](https://klypix.com) 中，你在代理工作时与它协同工作：你的光标在一个卡片中输入，而代理决策则出现在你的旁边，每个决策都在其区域内，并用箭头解释为什么——保存功能拒绝写入丢失卡片的文件。
> *他们的AI为你的项目保留日记。我们的AI与你一起在同一个房间工作——而这个房间记得一切。*
## 快速开始
**Claude 代码（原生 - 实时钩子，零努力）：**
```bash
npx klypix-mcp install
```
你机器上的每个仓库，只要有 `brain.klypix` ，就会自动为每个会话简要介绍项目状态，并自动捕获决策。给一个项目添加大脑，只需在项目中添加 `brain.klypix` 即可—— [KLYPIX 应用](https://klypix.com) 可以一键完成（ *保存画布为项目大脑* ），或者 `create_canvas` 可以从任何代理创建大脑。
**所有其他代理工具（每个项目一个命令）：**
```bash
npx klypix-mcp link
```
将大脑扩展到 Cursor & VS Code/Copilot（MCP 配置 + 规则）以及 Cline、Windsurf、Gemini CLI、Aider 和任何读取 AGENTS.md 的代理 - 始终开启的规则，教导工具读取和捕获大脑。
## 项目大脑的作用
与笔记文件夹的区别不是形状 - 而是这种记忆是一种 **机制，而不仅仅是一种归档方式** :
- **它会介绍每个会话。** 每个代理会话开始时都会知道项目的决策、开放问题和固定规则 - 一个简洁的简介 (≈3–5k tokens，即使有 600+ 张卡片，也会呈亚线性增长)。在我们自己的大脑中测量： **73% 的过去决策在一次搜索中恢复（55% 仅限简介）vs 0% 冷启动** （n=20）。
- **它会反驳。** `brain_challenge`：提出决策，大脑会用收据回复 - *"你曾在 6 月 12 日推翻了这个；这里是修正 - 由不同代理捕获，请在覆盖之前协调。"* 仅限确定性证据（修正提示，相反极性），而非单纯的话题相似性。一个不能与你争论的记忆只是一种阿谀。
- **它知道自己何时过时。** 决策卡可以锚定到他们被决策的代码（git blob OID）。当代码发生变化时，卡片会在下一个简介中举手。他们的笔记会默默地腐烂；我们的笔记会自我承认。
- **它从过去回答。** `brain_ask` with `as_of: 2026-03-01` 回答项目在当时相信的事情 - 未来的修正不会向后泄露。
- **位置意味着某些东西。** 将卡片拖入 📌 焦点区域，它将引导每个未来会话的简介。布局是指令，而不是装饰。
- **许多代理，没有混乱。** 并发会话获取捕获锁（零捕获丢失，在四个同时写入器上测试），标记 **谁** 编写了每个卡片，通过大脑相互消息（ `brain_message` ）和真正的矛盾以红色箭头显示，供人类仲裁 - 永远不会自动解决。
- **有测量的检索，包括失败。** 混合设备搜索（语义 + 词汇 + 跨编码器重新排序，无云）：真实源卡的召回率@5 从 **5% → 15% → 40%** 提升，跨我们的升级（n=20 个冻结的人类意译问题） - 而倒退的实验（短卡上的上下文前缀）被记录在赢项旁边。
## 你可以持有的一个文件
整个大脑 - 布局、决策、箭头，**以及实际字节** （图像、PDF、音频、代码） - 是一个单独的 `.klypix` 文件。 通过电子邮件发送它。 通过git发送它。 将它交给代理。 文件夹的markdown指向其附件；这个文件 **携带** 它们。
而且它不是一个笼子：所有内容都 **导出为Markdown和JSON Canvas** 通过一个命令，并且 **Obsidian `.canvas` 文件直接在KLYPIX中打开** 。 普通的markdown是地球上最便携的文本 - 这就是为什么我们导出它。 完整规范： [FORMAT.md](FORMAT.md)。
**"项目"意味着任何项目。** 两个展示大脑在 [`examples/`](examples/) 中交付，引擎相同，生命周期不同： [`showcase-brain.klypix`](examples/showcase-brain.klypix) 是 *Aurora*，一个虚构的天气应用（雷达瓷砖，API上限，带有收据的修正） - 和 [`showcase-wedding.klypix`](examples/showcase-wedding.klypix) 是 *Our Wedding* （场地，供应商，宾客名单，修正机制指向餐饮）。 相同的 📌 焦点，相同的箭头，相同的简介。 如果有值得保留的决策，它就会有一个大脑。
## 为普通MCP客户端设置
任何MCP客户端都可以在没有钩子的情况下获得工具。 对于 **Claude Desktop**，在 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"klypix": {
"command": "npx",
"args": ["-y", "klypix-mcp", "--vault", "/absolute/path/to/canvases"]
}
}
}
```
然后询问你的代理类似 *"我们对auth有什么决定？"*, *"挑战这个：让我们切换到轮询"*, 或 *"将这些笔记转换成一个板。"*
## 16种动词
| 工具 | 它做什么 |
|---|---|
| `brain_ask` | 全脑问题解答 - 具有纠正意识，`as_of` 时间旅行 |
| `brain_challenge` | 大脑反驳：带有收据的矛盾，已尝试和已反转的链条，固定规则，其他代理提供证据标记 |
| `brain_note` | 捕获整个生命周期 - 覆盖 / ✓ 解析 / ~ 更新 / 🛠 技能 / 关闭： |
| `brain_reconcile` | 查找过时-修正对和未记录的迁移 |
| `brain_insights` | 中心，未解决的决策，过时的提问，区域大小 |
| `brain_garden` | 大脑的维护通道 |
| `brain_doctor` | 自我诊断：版本对齐，钩子连接，投影漂移 |
| `brain_message` | 会话到会话的协调笔记 |
| `brain_connect` | 查找 + 绘制相关但未链接的卡片 |
| `canvas_view` | 将棋盘作为MCP应用 - 具有应用能力的聊天获得交互式空间视图；其他人获得干净的文本 |
| `read_canvas` | 将棋盘作为markdown（卡片，连接图，`[[链接]]`，`#标签`） |
| `search_canvases` | 按名称 + 内容搜索棋盘 |
| `search_all_brains` | 跨项目内存搜索每个注册的大脑 |
| `create_canvas` | 从卡片 + 连接新建 `.klypix` |
| `add_to_canvas` | 追加卡片/连接（保留位置） |
| `list_canvases` | 列出 vault 中的每个 `.klypix` |
### 工具 vs. *自动* 大脑
此包是 **代理中立的读写表面** - 任何MCP客户端根据需要（*拉取*）在任何项目中获得上述工具。 **自动** 大脑 - 从您的工作中自动捕获决策，将简介注入每个会话，协调并发会话（*推送*） - 在主机 **钩子** 中运行， `npx klypix-mcp install` 为Claude Code（和 [KLYPIX 桌面应用](https://klypix.com) 内置）连接。 其他工具通过 `link` 获得始终开启的规则。
### 更新 - 传播契约
`install` 将整个大脑（钩子 + 引擎 + 本地MCP服务器）放入 `~/.claude/project-brain` ，并且发出的配置从 **安装的捆绑包** 运行服务器（无npx缓存过期）。 然后更新是自动的：钩子在启动时检查npm（≤1/24h，失败打开，禁用 `KLYPIX_AUTO_UPDATE=0` ）并自行安装更新版本。 一个诚实的警告：运行的stdio服务器无法热交换 - 一个新的二进制文件在下一次完整应用启动时加载（或 `/mcp` 重新连接）； `brain_doctor` 的RUNNING行告诉你何时需要这样做。
## 也支持A2A（Agent-to-Agent）
```bash
npx -p klypix-mcp klypix-a2a --vault ./canvases # 127.0.0.1:41241
# 代理卡： http://127.0.0.1:41241/.well-known/agent-card.json
```
技能： `make_board`, `remember`, `recall`, `read_canvas`, `list_canvases`, `brain_insights`, `search_all_brains`. 与典型的A2A代理返回文本不同，KLYPIX返回 **`.klypix` 棋盘本身** 作为多模态神器。 详情： [A2A.md](A2A.md).
## 作为库使用
```js
import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown } from 'klypix-mcp';
```
```bash
npx -p klypix-mcp klypix-read path/to/board.klypix # → markdown 简介
echo '{ "title": "Plan", "cards": [{ "text": "kickoff" }] }' \
| npx -p klypix-mcp klypix-write --out plan.klypix
```
## 它打开的工作空间
大脑是开放和自由的 - 这个包，钩子，格式。 **[KLYPIX](https://klypix.com)** 是围绕它的Windows应用： 将大脑视为一个有生命的空间地图，在其中工作时你的代理写入，从任何地方捕获任何内容，与代理一起行动，共享加密。 双语英语/阿拉伯语。
## 诚实笔记
- 狗粮测试： **KLYPIX本身就是用它自己的大脑构建的** - 600+ 张卡片，多个并发代理会话，文件中的收据。
- 所有引擎智能都是确定性和本地的 - 唯一的LLM是 *你的* 代理。 无遥测，无云调用，离线工作。
- 上面的每个数字都在我们自己的项目大脑上测量；评估工具包在存储库中提供。
## 为什么存在
前沿实验室正在竞赛，将你的上下文放入 *他们的* 内存中 - 一个漫游酒店，你的工作寄存并永远不会离开竞争对手。 `klypix-mcp` 是相反的： **你的项目，你的文件，任何模型，离线。** 一个任何代理都可以读写的大脑是实验室在结构上不愿构建的东西。
Apache-2.0 © [Dahshan Labs](https://klypix.com). KLYPIX 桌面应用是一个单独的专有产品 - 文件和此服务器是完全开放的，无需它即可工作。
