Cairn MCP

______________________________________________________________________

一个用于人工智能代理和人类的自托管持久内存平台。存储一次，稍后在会话和项目之间找到。四个集装箱。 docker compose up。完成。

凯恩是记忆大脑。你的代理运行时处理执行——凯恩处理知道。做出了什么决定，知道什么事实，项目中出现了什么模式。

它是为系统人员构建的。好奇的人。t恤衫。那些需要一种记忆的人，这种记忆会以他们的方式在所有事情上同时发挥作用。

快速开始

1.拉动并奔跑

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

四个集装箱开始：

• 石堆 在端口8000上（MCP服务器+REST API）
• 凯恩ui 在端口3000（网络仪表板）上
• 凯恩数据库 （PostgreSQL 16+pgvector）
• 凯恩图 （Neo4j 5，知识图谱）

迁移在首次启动时运行。大约一分钟后准备好。

2.连接IDE

将此添加到您的MCP配置中：

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

去哪儿了：

或者运行安装向导——它会引导您完成所有操作：LLM后端、数据库、嵌入、身份验证和IDE配置：

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

选择一个层（本地开发、推荐、企业或自定义），向导只收集该层所需的内容。支持 --dry-run 和 --non-interactive 对于CI。

3.使用它

告诉你的经纪人记住一些事情：

“请记住，我们选择PostgreSQL作为存储，因为它可以在没有单独矢量数据库的情况下处理混合搜索。”

稍后搜索：

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

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

其余： modify, insights, think, status, consolidate, ingest.

盒子里有什么

跨会话持续存在的内存。 你的经纪人在凌晨2点做出决定。第二天早上，在不同的会议上，它做出了这个决定。这就是核心。当事情发生时，双时间跟踪会分开(event_at)从你学会它的时候起(created_at).遗忘的记忆自然会腐烂；重要的受到保护。相关的记忆会自动整合成更高层次的见解。

信仰。 持久的认知状态——自信地掌握知识。将假设转化为信念，用反证质疑它们，错误时收回它们。信念与规则和记忆一起出现在会话引导中，让代理清楚地了解组织所知道的内容以及它有多自信。

搜索融合信号。 向量相似度、新近度、访问频率、关键字匹配和标签重叠通过互易秩融合混合。按项目、类型或时间范围筛选。时态查询：“截至周二，我们知道什么？” as_of“上周发生了什么？” event_after/event_before.

知识图谱。 实体和事实被提取到Neo4j图中，该图通过共享的人、地点、项目和概念连接记忆。可选，但在跨域工作时功能强大。

思维序列。 结构化审议——从目标开始，添加想法（观察、假设、分析、替代方案），得出结论。人类和代理人都有贡献。探索本身就变成了可搜索的记忆。

工作管理。 具有依赖性跟踪、暂停人工决策的门和活动日志的分层工作项。实验性——随着我们学习什么有效而不断发展。

Web仪表板。 使用OKLCH彩色切换过滤器、分数渐变条和可共享URL状态浏览记忆。探索知识图谱和实体关系。查看分析，管理工作项。港口3000。

Memory growth by type, token usage tracking, and the full nav.

代码智能。 一个独立的worker使用树状图（30种语言）对代码库进行索引，并在Neo4j中构建代码图。服务器在不接触源文件的情况下查询图形。问一些结构性问题——“什么依赖于这个文件？”，“谁调用这个函数？”“爆炸半径是多少？”——并从代码图中得到答案。调用图提取、圈复杂度、死代码检测。使用YAML规则强制架构边界。跨项目工作。

Supported languages (30)

多用户身份验证和RBAC。 默认情况下，关闭此选项，在一个命令中将0设置为企业。 ./scripts/setup.sh 包括身份验证配置，或运行 ./scripts/setup-auth.sh 独立。身份验证模式选择（无/本地JWT/OIDC SSO）、JWT秘密生成、OIDC提供者验证。机器客户端的个人访问令牌，MCP的stdio标识。三个角色，项目级范围，第一个用户成为管理员。具有OIDC同步的组。看 身份验证指南.

灾难恢复。 用于PostgreSQL转储和Neo4j图形导出的Cron友好脚本，具有可配置的保留功能。通过迁移安全检查测试了恢复过程。看 备份指南.

我需要法学硕士吗？

不需要。存储、搜索、召回和规则没有一个就可以工作。你失去了自我充实（总结、标签、重要性评分）、知识提取和思考。

如果你想致富：

配置

所有这些都是通过环境变量实现的。重要的是：

完整参考资料见 每个变量都有一个合理的默认值。

认证

默认情况下为关闭。启用它的最快方法是通过安装向导：

./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客户端示例。

安全说明： 凯恩的身份验证系统已经过功能测试和生产测试，但 未经独立审计。对于网络暴露的部署，添加TLS 终端和网络级访问控制。

远程MCP访问（第ai条，移动）

将凯恩连接到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设置>集成>添加自定义MCP
2. 输入您的凯恩网址： https://your-cairn-domain.com/mcp
3. Claude.ai自动发现OAuth2端点
4. 您将被重定向到您的身份提供者以登录
5. 登录后，Claude.ai可以完全访问您的凯恩MCP工具

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

看 远程MCP指南 用于反向代理配置、安全强化和故障排除。

代码智能

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

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

快速启动

# 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

环境变量

Docker/远程代码库

将源代码装入cairn容器并设置 CAIRN_CODE_DIR:

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

或者在代码主机上运行worker，并将其指向您的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、Types/TSX和28种以上（C、Rust、Go、Java、Ruby等）

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

建筑

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，一个包含1986个问题的长对话记忆基准测试，分为五个类别。

测试配置：Titan V2嵌入（基岩，1024 dim），偶发性摄入（原始转弯+两遍事实提取），搜索V2，图形初步检索，类型路由，交叉编码器重新排序，LLM作为判断评估。完整的结果和方法 eval/.

发展

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

状态

凯恩正在积极开发中。这是一个每天在生产中使用的真实系统，随着我了解什么对代理内存有效，它也在不断发展。迁移处理架构更改。如果有什么东西坏了， 打开一个问题.

许可证

GNU通用公共许可证v3.0