Cairn

重要

Cairn 已停止维护，本仓库已归档（只读）。 其后继项目是 rill——一个更快速、更精简、 原生支持 MCP、使用 Go 编写的记忆服务，它汲取了 Cairn 的所有成功经验 （以及失败教训）。Cairn 是第一个；后续工作将在 rill 中继续。 本仓库将作为只读归档保留——你可以探索、派生，但新开发 都将在 rill 中进行。

---

一个可自托管的持久记忆平台，服务于 AI Agent 和人类。存储一次，之后即可跨会话、跨项目查找。四个容器。运行 docker compose up。完成。

Cairn 是记忆中枢。你的 Agent 运行时负责执行——Cairn 负责记忆。做出了哪些决策、已知哪些事实，以及跨项目浮现了哪些模式。

它为系统思考者、好奇者和 T 型人才打造。为那些需要一种能按自己的方式、跨越所有事物并同时运作的记忆的人打造。

快速开始

1. 拉取并运行

curl -O https://raw.githubusercontent.com/jasondostal/cairn-mcp/main/docker-compose.yml
docker compose up -d

四个容器将启动：

• cairn，端口 8000（MCP 服务 + REST API）
• cairn-ui，端口 3000（Web 仪表板）
• cairn-db（PostgreSQL 16 + pgvector）
• cairn-graph（Neo4j 5，知识图谱）

首次启动时会运行迁移。大约一分钟后即可就绪。

2. 连接你的 IDE

将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "cairn": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

配置文件位置：

IDE	配置文件
Claude Code	项目根目录中的 .mcp.json
Cursor	.cursor/mcp.json
Windsurf	.windsurf/mcp.json
Cline	VS Code 中的 MCP 设置面板
Continue	.continue/config.yaml
PiClaw	.pi/mcp.json

也可以运行设置向导——它会引导你完成所有配置：大模型后端、数据库、嵌入、身份验证和 IDE 配置：

git clone https://github.com/jasondostal/cairn-mcp.git && ./cairn-mcp/scripts/setup.sh

选择一个层级（本地开发、推荐、企业或自定义），向导只会收集该层级所需的信息。支持在 CI 中使用 --dry-run 和 --non-interactive。

3. 使用

告诉你的 Agent 记住一件事：

“记住，我们选择 PostgreSQL 作为存储，因为它无需单独的向量数据库就能处理混合搜索。”

之后再搜索：

“我们对存储层做了什么决定？”

就这样。共有 11 个工具可用。你最常用的工具有：

工具	功能
store	保存记忆并自动补充信息。支持 event_at 和 valid_until，用于双时态跟踪
search	查找记忆（向量 + 关键词 + 时效性 + 标签）。时态筛选器：as_of、event_after、event_before
recall	获取特定记忆 ID 对应的完整内容
orient	启动会话并载入规则、近期活动、信念和未完成的工作
rules	加载行为准则（全局或针对单个项目）
beliefs	持久的认知状态——以置信度跟踪为基础，凝练、质疑、撤回知识
work_items	创建、认领和完成带有依赖项和关卡的任务
working_memory	捕获短暂想法——假设、问题、矛盾——并随显著性衰减
projects	管理项目文档（简介、PRD、计划）
code_query	结构化查询：依赖项、影响、调用方、被调用方、死代码、复杂度、热点
arch_check	根据导入规则验证架构边界

其余工具：modify、insights、think、status、consolidate、ingest。

包含内容

可跨会话持久保存的记忆。 你的 Agent 在凌晨 2 点做出一个决定。第二天早上，换了一个会话，它仍能找到那个决定。这就是核心功能。双时态跟踪将事件发生的时间（event_at）与获知事件的时间（created_at）区分开来。未被访问的记忆会自然衰减；重要记忆则会受到保护。相关记忆会自动整合为更高阶的洞见。

信念。 持久的认知状态——以一定置信度持有的知识。将假设提炼为信念，用反面证据质疑它们，并在它们出错时撤回。信念会与规则和记忆一同出现在会话启动时，让 Agent 清楚了解组织已知什么，以及对此有多大把握。

融合多种信号的搜索。 通过倒数排名融合（Reciprocal Rank Fusion）综合向量相似度、时效性、访问频率、关键词匹配和标签重合度。可按项目、类型或时间范围筛选。支持时间查询：通过 as_of 查询“截至周二我们知道什么？”，通过 event_after/event_before 查询“上周发生了什么？”。

知识图谱。 实体和事实会被提取到 Neo4j 图谱中，通过共同的人物、地点、项目和概念串联记忆。此功能可选，但在跨领域工作时非常强大。

思考序列。 结构化推理——从目标开始，添加想法（观察、假设、分析、备选方案），最后得出结论。人类和 Agent 都可以参与。探索过程本身也会成为可搜索的记忆。

工作管理。 支持依赖关系跟踪的分层工作项、可暂停以等待人工决策的关卡，以及活动日志记录。此功能仍处于实验阶段，会随着我们不断摸索有效做法而持续演进。

Web 仪表板。 浏览记忆，使用 OKLCH 着色的切换筛选器、分数渐变条和可分享的 URL 状态。探索知识图谱及实体关系。查看分析数据并管理工作项。端口 3000。

_{按类型展示的记忆增长、令牌用量跟踪，以及完整导航栏。}

代码智能。 独立工作进程使用 tree-sitter（30 种语言）为代码库建立索引，并在 Neo4j 中构建代码图谱。服务端查询图谱时完全不会接触源文件。提出结构性问题——“哪些内容依赖此文件？”、“哪些地方调用了此函数？”、“影响范围有多大？”——即可从代码图谱中获取答案。支持调用图提取、圈复杂度计算和死代码检测。通过 YAML 规则强制执行架构边界。支持跨项目使用。

支持的语言（30 种）

类别	语言
系统语言	C、C++、Rust、Go、Zig
JVM	Java、Scala、Kotlin、Groovy
.NET	C#
脚本语言	Python、Ruby、PHP、Lua、Bash
Web	TypeScript/TSX、HTML、CSS
Apple	Swift、Objective-C
ML/科学计算	OCaml、MATLAB
配置与数据	JSON、YAML、TOML、HCL（Terraform）、Dockerfile、Makefile、SQL、Markdown

多用户身份验证和 RBAC。 默认关闭，通过一条命令即可从零配置到企业级。./scripts/setup.sh 包含身份验证配置，也可以单独运行 ./scripts/setup-auth.sh。支持选择身份验证模式（none / local JWT / OIDC SSO）、生成 JWT 密钥并验证 OIDC 提供商。为机器客户端提供个人访问令牌，为 MCP 提供 stdio 身份。设有三种角色，支持项目级范围控制，并由首位用户自动成为管理员。支持通过 OIDC 同步群组。请参阅**身份验证指南**。

灾难恢复。 提供适用于 Cron 的脚本，可转储 PostgreSQL 并导出 Neo4j 图谱，且保留期限可配置。恢复流程经过测试，并包含迁移安全检查。请参阅**备份指南**。

我需要大模型吗？

不需要。存储、搜索、回忆和规则都可以在没有大模型的情况下运行。你将无法使用自动丰富功能（摘要、标签、重要性评分）、知识提取和思考功能。

如果你需要内容丰富功能：

后端	设置
Ollama（默认）	安装 Ollama，拉取一个模型。Cairn 会连接到 host.docker.internal:11434。
AWS Bedrock	设置 CAIRN_LLM_BACKEND=bedrock，导出 AWS 凭据。
Google Gemini	设置 CAIRN_LLM_BACKEND=gemini，添加 CAIRN_GEMINI_API_KEY。提供免费套餐。
兼容 OpenAI 的服务	设置 CAIRN_LLM_BACKEND=openai，添加密钥。可与 OpenAI、Groq、Together、LM Studio、vLLM 配合使用。

配置

所有配置都通过环境变量设置。以下是重要变量：

变量	默认值	作用
CAIRN_PROFILE	(空)	预设：vector、enriched、knowledge、enterprise。设置功能默认值。
CAIRN_LLM_BACKEND	ollama	大模型提供方：ollama、bedrock、gemini、openai
CAIRN_DB_PASS	cairn-dev-password	数据库密码。本地使用以外的场景都应修改此项。
CAIRN_AUTH_ENABLED	false	多用户身份验证（JWT、PAT、OIDC/SSO）
CAIRN_AUTH_JWT_SECRET	(空)	JWT 签名密钥（启用身份验证时必填）
CAIRN_OIDC_ENABLED	false	OIDC/SSO 集成（支持任何符合 OIDC 标准的提供方）
CAIRN_MCP_OAUTH_ENABLED	false	面向远程 MCP 客户端（Claude.ai、移动端）的 OAuth2 授权服务器
CAIRN_GRAPH_BACKEND	(已禁用)	设置为 neo4j 以启用知识图谱
CAIRN_KNOWLEDGE_EXTRACTION	false	存储时提取实体/陈述
CAIRN_EMBEDDING_BACKEND	local	local（MiniLM，384 维）或 bedrock（Titan V2，1024 维）
CAIRN_INGEST_DIR	/data/ingest	大型文档通过文件路径导入时使用的暂存目录
CAIRN_CODE_DIR	/data/code	代码智能索引的根目录（在此处挂载代码库）

完整参考见 docker-compose.yml。每个变量都有合理的默认值。

身份验证

默认关闭。最快的启用方式是使用设置向导：

./scripts/setup.sh          # includes auth as step 2
./scripts/setup-auth.sh     # or run auth setup standalone

支持三种模式——无身份验证、本地 JWT 或 OIDC/SSO。向导会生成密钥、验证身份提供方的发现端点，并写入 .env。针对 Authentik、Keycloak、Auth0、Okta 和 Azure AD 提供特定的 URL 提示。两个脚本都支持 --dry-run 和 --non-interactive，可用于 CI。

首个注册的用户将成为管理员。基于角色的访问控制会在 REST API、MCP HTTP 和 Web UI 中强制执行权限。支持供机器客户端使用的个人访问令牌，以及与 OIDC 同步的群组。

完整参考请参阅 身份验证指南，其中涵盖所有身份验证模式、OIDC 提供方配置和 MCP 客户端示例。

安全说明： Cairn 的身份验证系统功能完备，并经过生产环境测试，但尚未接受独立审计。对于暴露在网络中的部署，请添加 TLS 终止和网络级访问控制。

远程 MCP 访问（Claude.ai、移动端）

将 Cairn 连接到 Claude.ai、Claude 移动应用或任何支持 OAuth2 的 MCP 客户端。Cairn 充当 OAuth2 授权服务器，并将用户身份验证委托给你现有的 OIDC 身份提供商。

**前置条件：**已启用身份验证（CAIRN_AUTH_ENABLED=true）、已配置 OIDC（CAIRN_OIDC_ENABLED=true），并已设置公共 URL（CAIRN_PUBLIC_URL）。

启用方法：

CAIRN_MCP_OAUTH_ENABLED=true

从 Claude.ai 连接：

1. 前往 Claude.ai Settings > Integrations > Add custom MCP
2. 输入你的 Cairn URL：https://your-cairn-domain.com/mcp
3. Claude.ai 会自动发现 OAuth2 端点
4. 你将被重定向到身份提供商进行登录
5. 登录后，Claude.ai 即可完全访问你的 Cairn MCP 工具

OAuth2 流程使用授权码 + PKCE，并结合动态客户端注册（RFC 7591）。如果你的身份提供商支持 SSO 会话，首次登录后，身份验证重定向将不可见。

有关反向代理配置、安全加固和故障排除，请参阅 远程 MCP 指南。

代码智能

代码智能以独立工作进程的形式运行，用于索引源代码并写入 Neo4j。cairn 服务器会查询图谱，但不会直接接触源文件。这种分离意味着索引过程不会阻塞事件循环，而且工作进程可以运行在代码所在的机器上。

**要求：**Neo4j（docker-compose 中的 cairn-graph 服务）必须正在运行。

快速开始

# Index a single project (one-shot, no watching)
python -m cairn.code \
  --watch /path/to/your/repo:your-project \
  --neo4j-uri bolt://localhost:7687 \
  --cairn-url http://localhost:8000 \
  --no-watch

# Index and watch for changes (long-running)
python -m cairn.code \
  --watch /home/user/working/myproject:myproject \
  --watch /home/user/working/other:other \
  --neo4j-uri bolt://my-server:7687

环境变量

变量	默认值	作用
CAIRN_NEO4J_URI	bolt://localhost:7687	Neo4j bolt URI
CAIRN_NEO4J_USER	neo4j	Neo4j 用户名
CAIRN_NEO4J_PASSWORD	cairn-dev-password	Neo4j 密码
CAIRN_API_URL	http://localhost:8000	Cairn 服务器 URL（用于解析项目 ID）
CAIRN_API_KEY	(empty)	启用 cairn 身份验证时使用的 API 密钥
CAIRN_CODE_PROJECTS	(empty)	以逗号分隔的 project=path 键值对（可替代 --watch）
CAIRN_CODE_WATCH	true	初始索引后启用文件系统监视
CAIRN_CODE_FORCE	false	即使内容哈希未更改，也强制重新索引

Docker / 远程代码库

将源代码挂载到 cairn 容器中，并设置 CAIRN_CODE_DIR：

# docker-compose.yml
volumes:
  - /path/to/code:/data/code:ro   # read-only mount
environment:
  CAIRN_CODE_DIR: /data/code

或者在代码所在的主机上运行工作进程，并将其指向你的 cairn 和 Neo4j 实例：

CAIRN_NEO4J_URI=bolt://cairn-host:7687 \
CAIRN_API_URL=http://cairn-host:8000 \
CAIRN_CODE_PROJECTS="myproject=/home/user/code/myproject" \
python -m cairn.code

索引内容

• **符号：**函数、类、方法、接口、枚举、React 组件/钩子
• 关系：IMPORTS（文件级）、CALLS（函数级）、CONTAINS（父子级）
• **元数据：**签名、文档字符串、圈复杂度、行号、内容哈希
• **语言：**Python、TypeScript/TSX，以及其他 28 种语言（C、Rust、Go、Java、Ruby 等）

查询示例（通过 code_query MCP 工具）

操作	作用
dependents	导入目标文件的文件
dependencies	目标文件导入的文件
callers	调用目标函数的函数
callees	目标函数调用的函数
call_chain	跟踪两个函数之间的调用路径
dead_code	没有调用者的函数
complexity	按圈复杂度对函数排序
impact	影响范围 — 传递依赖项
hotspots	PageRank — 结构上重要的文件
search	对符号名称和文档字符串进行全文搜索

架构

MCP clients (Claude Code, Cursor, PiClaw)    REST clients (web UI, scripts)
        |                                            |
        | MCP (stdio or HTTP)                        | REST API
        |                                            |
+-------v--------------------------------------------v--------+
|  cairn.server (MCP tools)     cairn.api (FastAPI endpoints) |
|                                                             |
|  core: memory, search, enrichment, extraction, clustering   |
|        working memory, beliefs, thinking, work items        |
|                                                             |
|  embedding: local (MiniLM) or Bedrock (Titan V2)            |
|  llm: Ollama, Bedrock, Gemini, OpenAI-compatible            |
+------+----------------------------------------------+------++
       |                                              |       |
       v                                              v       |
  PostgreSQL 16 + pgvector                    Neo4j 5 <-------+
                                             (optional)       |
                                                ^             |
  code worker (python -m cairn.code)            |             |
  tree-sitter parsing, call graph      --------+             |
  watches filesystem for changes                             |

基准测试

基于 LoCoMo 进行测试。LoCoMo 是一项长对话记忆基准测试，涵盖五个类别，共有 1,986 个问题。

系统	得分	LLM
Cairn	81.6%	Llama-3.3-70B
人类基准	87.9%	—
Letta/MemGPT	74.0%	GPT-4o-mini
Mem0	66.9%	GPT-4o

测试配置：Titan V2 嵌入（Bedrock，1024 维）、情景式摄取（原始轮次 + 两遍事实提取）、以图谱为主要检索方式的 Search V2、类型路由、交叉编码器重排序，以及由 LLM 充当评判者的评估。完整结果和方法见 eval/。

开发

git clone https://github.com/jasondostal/cairn-mcp.git
cd cairn-mcp
cp .env.example .env
docker compose up -d --build

状态

Cairn 正在积极开发中。这是一个每天在生产环境中实际使用的系统，并且随着我逐步了解哪些方法真正适用于 Agent 记忆，它也在不断演进。迁移会处理架构变更。如果遇到问题，请提交 issue。

许可证

GNU 通用公共许可证 v3.0