Cairn

Cairn 是一个仅追加的类型化事实存储。智能体在一个会话中断言一个事实，并在下一个会话开始时以新鲜度判定召回它。

事实持久化在 SQLite 中。Desk 是可选的。工作通过 JSON 和 MCP 进行。

安装

npx cairn init --project
npx cairn dev

init --project 创建 .cairn/cairn.db，接入 Cursor（.cursor/mcp.json），并接入 Pi（.mcp.json）。

无项目文件时的全局安装：

npx cairn init

Related MCP server: identity-storage-mcp

命令

智能体契约

向 POST /api/cairn 发送 JSON，或调用 MCP 工具 cairn_recall 和 cairn_request。

每次写入都携带一个 idempotencyKey。崩溃后重放相同的键和请求体，Cairn 会返回原始结果，而不会写入两次。

Recall 会在每条信念上返回 freshness 和 assurance。根据 response.kind 进行分支。拒绝信息包含 error.remedy.kind。

示例断言

curl -s http://127.0.0.1:4721/api/cairn \
  -H 'content-type: application/json' \
  -d '{
    "kind": "assert",
    "idempotencyKey": "s-021-deploy",
    "onConflict": "supersede",
    "draft": {
      "entity": "repo:acme/checkout",
      "attribute": "deploy.command",
      "value": { "kind": "text", "text": "bin/ship --env staging" },
      "provenance": {
        "kind": "observed",
        "command": "cat Makefile && bin/ship --help",
        "session": "s-021"
      },
      "validity": { "kind": "until-superseded" }
    }
  }'

Harness 插件

Cursor。 在 cairn init --project 之后，.cursor/mcp.json 会包含一个 cairn 服务器，它运行 npx cairn mcp。

Pi。 同样的 init 会为 Pi 和其他 MCP 客户端写入 .mcp.json。Pi 会读取 .mcp.json 以及诸如 cursor 的宿主导入。

Desk 和 Canvas

打开 Desk（/）可查看信念表和智能体 API 控制台。打开 Canvas（/canvas）可将每个智能体或会话视为一个可拖拽容器，其中包含它们贡献的事实。

智能体按 provenance.by 分组以显示被告知的事实，按 provenance.session 分组以显示观察或推断的事实。拖拽 pod 来排列画板；布局会持久化在 .cairn/canvas.json 中。

从 npm 发布和安装

npm publish
npx cairn init --project
npx cairn dev

发布的 tarball 包含完整的 Desk、Canvas、API、CLI 和 MCP 服务器。需要 Node 20+。

开发

npm install
npm test
npm run dev

当该目录存在时，数据库路径解析为 ./.cairn/cairn.db，否则为 ~/.cairn/cairn.db。可使用 CAIRN_HOME 或 CAIRN_DB_PATH 覆盖。

发布预告片（Remotion）

一个约 30 秒的 X 产品预告片位于 cairn-trailer/。在该文件夹内使用 npm run dev 预览，或渲染：

cd cairn-trailer
npx remotion render CairnTrailer out/cairn-v0.4-trailer.mp4

建议的帖子文案见 cairn-trailer/x-post-draft.md。

Cairn 拒绝什么

自由格式的 JSON 值。

语义搜索。

就地编辑事实。

在请求进行中等待人类。