czearing/cairn

# Cairn [](https://github.com/czearing/cairn/actions/workflows/ci.yml) [](./LICENSE) Cairn 是一个为 AI agent 提供的共享、持久化记忆库。它将每个想法存储为一个*神经元* (neuron)：包含一个问题、它的答案，以及指向相关神经元的链接。Agent 通过 [MCP](https://modelcontextprotocol.io) 对其进行读写，并根据语义回忆过去的思考，从而让工作得以积累，而不是每次都从头开始。 它是一个记忆层，而不是一个 agent。不需要运行任何服务。你将获得一个本地 SQLite 数据库、三个 MCP 工具，以及一个提示注入层，用于引导 agent 在回答之前先进行搜索。 ## 安装 ``` # macOS, Linux, WSL2 curl -fsSL https://raw.githubusercontent.com/czearing/cairn/main/scripts/install.sh | bash ``` ``` # Windows irm https://raw.githubusercontent.com/czearing/cairn/main/scripts/install.ps1 | iex ``` 安装程序会检查你的环境，将 Cairn 接入 Claude Code，下载本地 embedding 模型，并在结束前运行一次快速的往返测试以证明“大脑”正常工作。它还会添加一个全局的 `cairn` 命令，因此日常你只需输入 `cairn doctor` 或 `cairn verify`。之后重启 Claude Code 即可加载工具。 如果是通过克隆仓库安装，请运行 `bun install && bun run install:claude`。 以后若要更新，请运行 `cairn update`。它会拉取最新代码、重新安装并重新应用配置。 ## 命令 | 命令 | 功能 | |---|---| | `cairn doctor` | 检查你的环境，并打印出如何修复缺失项的说明。 | | `cairn verify` | 在一次性数据库中创建并回忆一段记忆，以确认其能正常工作。 | | `cairn update` | 更新到最新版本并重新应用配置。 | | `cairn uninstall` | 移除 hooks 和 MCP 注册。你已保存的记忆将被保留。 | | `cairn install --dry-run` | 展示安装操作会更改的内容，但不会实际写入任何东西。 | | `cairn --version` | 打印已安装的版本。 | ## 工具 Agent 通过 MCP 使用三个工具： | 工具 | 参数 | 功能 | |---|---|---| | `brain_search` | `query` | 通过语义查找相关神经元，并返回每个神经元及其连接的子图。 | | `brain_create` | `text`, `edges?` | 添加一个神经元并返回其 id。 | | `brain_mutate` | `id`, `text?`, `answer?`, `edges?` | 更新一个神经元。设置 `answer` 会将其标记为已解决。 | ## 运作机制 “大脑”本身对 Claude Code 一无所知。由两个适配器将它们连接起来： - **MCP server** 将这三个工具暴露给任何 MCP 宿主（Claude Code、Cursor、VS Code 等）。 - **Hooks** 会在 Claude Code 的生命周期事件中触发，并注入提示，从而驱动一个“分解、研究、回答”的循环。 ``` prompts/ editable policy, one markdown file per moment src/ core/ the brain (db, embeddings, neurons, search). No host code. mcp/server.ts the three tools, over core inject/ events, matchers, dispatch hosts/claude-code/ the Claude Code adapter scripts/ installer bootstrap and the sandbox harness ``` ## 适用于任何模型的记忆库（代理） 并非所有工具都支持 MCP。对于像 Ollama 这样的本地模型，或者任何兼容 OpenAI 的客户端，请改用运行代理： ``` cairn proxy ``` 它会在 `http://localhost:11435/v1` 上提供一个兼容 OpenAI 的 API。将你客户端的 `base_url` 指向它即可。在每次 chat 请求时，代理会使用你的最新消息去搜索“大脑”，并将找到的内容添加到 system prompt 中，然后将请求转发给模型。模型完全不需要了解 Cairn。 只需一个变量即可切换后端： ``` CAIRN_PROXY_UPSTREAM=ollama cairn proxy # default, http://localhost:11434/v1 CAIRN_PROXY_UPSTREAM=openai cairn proxy # needs OPENAI_API_KEY CAIRN_PROXY_BASE_URL=http://host:1234/v1 cairn proxy # any other OpenAI-compatible server ``` 在未运行模型的情况下查看其运行效果： ``` bun scripts/proxy-demo.ts ``` 目前代理已经能够回忆记忆（读取）。而在对话后写回新记忆的功能是可选的，且目前依然非常有限，因为“大脑”是一个由问题和答案构成的精选图谱，而不是一份聊天记录。 ## 配置 一切均通过环境变量进行设置。无需寻找配置文件。 | 变量 | 默认值 | 用途 | |---|---|---| | `CAIRN_DB_PATH` | `~/.cairn/cairn.db` | 本地“大脑”的存放位置。 | | `CAIRN_LIBSQL_URL` | 无 | Turso 主数据库的 `libsql://…` URL。与 token 一起设置，即可跨设备同步“大脑”（见下文）。 | | `CAIRN_LIBSQL_TOKEN` | 无 | Turso 主数据库的认证 token。 | | `CAIRN_LIBSQL_LOCAL` | `~/.cairn/cairn-replica.db` | 同步模式下使用的本地副本文件，与仅限本地的“大脑”分开保存。 | | `CAIRN_LIBSQL_SYNC_PERIOD` | `60` | 从主数据库自动后台拉取的间隔秒数。 | | `CAIRN_EMBED_PROVIDER` | `local` | `local` 在进程内运行 MiniLM；`openai` 调用 API。 | | `CAIRN_EMBED_MODEL` | 提供程序默认值 | 例如 `text-embedding-3-small`。 | | `CAIRN_EMBED_API_KEY` | 无 | 用于 `openai` 提供程序。 | | `CAIRN_EMBED_BASE_URL` | OpenAI | 用于 Azure 或其他兼容 OpenAI 的 endpoint。 | | `CAIRN_RELEVANCE_THRESHOLD` | `0.3` | 神经元必须达到的相似度才能被视为相关。 | | `CAIRN_RELATIVE_FLOOR` | `0.7` | 自适应相关性阈值：对于查询，保留得分 `>= max(阈值, 最高得分 × 该值)` 的结果。设为 `0.7` 时，广泛性查询会被修剪为最相关的聚簇，而狭窄的查询仍能返回其答案。设为 `0` 则禁用此功能。 | | `CAIRN_SEARCH_LIMIT` | `0` (关闭) | 对 `brain_search` MCP 工具的可选 top-N 数量上限，作为相关性阈值之上的后备保障。`0` 表示完全由阈值决定。 | | `CAIRN_PROXY_UPSTREAM` | `ollama` | 代理转发到的目标模型后端（`ollama`、`openai`）。 | | `CAIRN_PROXY_BASE_URL` | 预设值 | 覆盖任何兼容 OpenAI 的服务器的上游 URL。 | | `CAIRN_PROXY_PORT` | `11435` | 代理监听的端口。 | | `CAIRN_PROXY_MEMORIES` | `5` | 每次请求注入的回忆神经元数量。 | 通过修改这些内容即可替换 embedding 模型。无需更改代码。 ## 跨设备同步 (Turso) 默认情况下，“大脑”是一个单一的本地 SQLite 文件。若要在多台机器间共享同一个大脑，请将 Cairn 指向一个免费的 [Turso](https://turso.tech) 数据库，它会以 **libSQL 嵌入式副本** 的形式运行：读取操作保持在本地且迅速，写入操作直接发往云端主数据库，而其他设备的更改会在后台被拉取。无需运行任何服务器，并且在离线时会自动回退到本地副本。 1. 在 [Turso 仪表盘](https://app.turso.tech) 中，创建一个数据库并复制其 URL，然后创建一个 token。 2. 在 Cairn 运行的任何地方（你的 MCP 宿主的 `env` 或你的 shell 中）设置这两个变量： CAIRN_LIBSQL_URL=libsql://your-db.turso.io CAIRN_LIBSQL_TOKEN=your-token 3. 若要将现有的本地大脑一次性迁移到云端，请运行： CAIRN_LIBSQL_URL=… CAIRN_LIBSQL_TOKEN=… bun scripts/migrate-to-turso.ts **添加另一台设备：** 导出相同的这两个变量并运行 `cairn install`（或 `bun run install:claude`）。安装程序会将它们直接绑定到 Claude Code 和 Copilot 的 MCP 注册配置中——无需手动编辑配置文件。新机器在首次使用时会从云端拉取现有的“大脑”；请勿在那里重新运行迁移脚本。 如果未设置这些变量，则不会有任何改变——Cairn 将保持为一个仅限本地的 `bun:sqlite` 大脑。位于 `CAIRN_DB_PATH` 的本地文件将作为备份原样保留；同步功能使用的是单独的副本文件。 ### 成本与 Turso 免费计划 读取操作完全不触及网络——每次搜索都是针对本地副本运行的——因此它们根本不会消耗 Turso 的配额。只有写入操作（新建/编辑神经元）和 `sync()` 拉取才会。免费计划每月 500M 行读取 / 10M 行写入的额度远远超出了个人大脑的需求。唯一影响成本的调节项是 `CAIRN_LIBSQL_SYNC_PERIOD`：即使没有任何更改，每次拉取也会产生少许消耗，因此默认的 60 秒是最经济的选择——仅在你需要更快的跨设备新鲜度时才调低它。 ## 安全试运行 “大脑”是一个可能由多个 agent 共享的实时数据库。要排练完整的安装过程（包括正常路径、重复运行、离线失败、卸载）而不影响你真实的配置、“大脑”或 MCP 注册，请运行沙盒： ``` bun scripts/sandbox.ts ``` 它会将所有副作用指向一个临时目录，然后检查你真实的 `settings.json` 和“大脑”是否保持不变。 ## 编辑提示 注入的提示是 `prompts/` 目录下的纯 Markdown 文件。编辑其中一个，下一次 hook 就会将其提取应用。无需重新构建，也无需重启。要添加新的用例，只需放入一个新的 `.md` 文件并在 `src/inject/matchers.ts` 中添加一个匹配器即可。 | 提示 | 触发时机 | |---|---| | `user-message.md` | 每次用户发送消息时 | | `search-results.md` | 在 `brain_search` 之后 | | `node-created.md` | 在 `brain_create` 之后 | | `node-modified.md` | 在 `brain_mutate` 之后 | | `subtask-spawned.md` | 在子 agent 任务生成之后 | ## 子 Agent 与 Agent 团队 `cairn install` 还会向 `~/.claude/agents/cairn.md` 写入一个 `cairn` 子 agent 定义。使用该类型生成一个子 agent ——或一个 agent 团队成员——它将在**相同**的注入提示下运行：其 frontmatter 的 hooks 会调用相同的调度器（`SessionStart` 会注入工作流，`brain_*` 调用会获得相同的提醒，而其 `Stop` 会变为 `SubagentStop` 以触发记录/拆分机制），同时其 body 承载着 agent 团队路径的策略。子 agent 已经继承了 `brain_*` MCP 工具，因此它们会像你一样读取并扩展同一个共享的“大脑”。 ## 添加宿主 1. 创建 `src/hosts//`。 2. 编写 `normalize.ts`，将宿主的 payload 转换为 `NormalizedEvent`。 3. 编写 `dispatch.ts`，将 stdin 接入 normalize，再接入 inject，最后输出到 stdout。 4. 添加一个安装路径。核心部分不需要改动。 ## 开发 ``` bun test # core, MCP, hooks, installer, viewer. Run from the repo root. bun run mcp # run the MCP server over stdio bun run ui # serve the viewer at http://localhost:3737 bun run seed # write a few demo neurons ``` 在提交 PR 之前，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 查看器 `cairn ui` 为“大脑”提供了一个小型的只读视图，并在 `/node/` 为每个神经元提供链接。MCP 工具在返回每个神经元时都会带上该链接，因此 agent 可以交给你一个可点击的参考，指向它所写入的内容。它是可选的，并且与系统的其他部分相互独立。 采用 MIT 许可协议。

标签：MCP, Petitpotam, SOC Prime, SQLite, 开发工具, 本地嵌入, 自动化攻击, 记忆层, 语义记忆