Cairn

Cairn

一款本地优先、开源的工具套件，帮助 AI Agent 整理文件。

将 Claude Code、Codex、Cursor——任何 MCP 客户端——指向一个文件夹，你的 Agent 就能获得一整套文件整理工具：列出、读取、搜索、grep、编辑、移动、标记、导入文档，以及语义检索。无需账户、无需云服务、无需界面。你的文件绝不会离开你的设备。

claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

然后让 Agent “整理这个文件夹并为所有内容添加标签”——它就会使用在本地处理你自己文件的工具来完成任务。

Cairn 是用来标记路径的一堆石头。这个 Cairn 会让你的文件井然有序，为你指明其中的路径。

---

快速入门（2 分钟）

如果你使用 Claude Code，只需一条命令即可完成设置——唯一的前提是安装 uv，它会提供 uvx：

# 1. Install uv if you don't have it (provides uvx)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Add Cairn to Claude Code, pointed at a folder you want organized
claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

重新打开 Claude Code 并询问：

“整理这个文件夹并为所有内容添加标签。”

Cairn 的工具在本地处理你的文件——读取操作可自由执行，而任何移动、重命名或编辑操作都会先请求确认。首次运行时会自动下载软件包（约 5 秒）；无需克隆、构建或账户。

提示

首次运行时，将 --workspace 指向一些笔记的副本——Cairn 可以移动、重命名和编辑文件。

使用 Codex？ 流程同样只需一条命令（然后在会话中运行 /mcp 进行确认）：

codex mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

使用 Cursor 或其他 MCP 客户端？ 使用同一个软件包，配置 JSON：

{ "mcpServers": { "cairn": { "command": "uvx",
  "args": ["cairn-mcp-server", "--workspace", "~/Documents/notes"] } } }

Cairn 会展开 ~，所以无论是在 CLI 还是配置文件中，~/Documents/notes 都可以正常使用。

只想试试看，不用 Agent？

uvx cairn-cli --workspace ~/Documents/notes tree

为什么需要工具套件

Agent 工具套件生态逐渐形成了一个清晰的模式：模型和 Agent 循环由客户端（Claude Code、Codex、OpenCode）提供，都是现成的组件。持久的价值在于工具和本地数据。因此，Cairn 提供的是工具，而不是 Agent——客户端负责循环、审批提示（由我们的工具注解决定）和聊天。Cairn 只是一套本地文件整理工具，可接入你已有的任意工具套件。

架构

所有界面都是基于一个标准库核心的轻量适配器，因此彼此之间永远不会出现偏差。

core/          cairn-core — the engine (stdlib only): the .uni document format,
               file operations, tags, retrieval; optional document ingestion
               (docx/pdf/pptx/xlsx/md) and embeddings-based search.
mcp-server/    cairn-mcp-server  — MCP server: 26 tools with read-only/destructive
               annotations, resources, and prompts.        ← the flagship
cli/           cairn-cli  — scriptable CLI, a local HTTP API (`serve`),
               and an `mcp` launcher.
web/           cairn-web  — optional zero-build local web UI
               (browse / edit / view / tag / search).

使用方法

在 Claude Code / Codex / Cursor 中（主要方式）：

claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes
# with real-document import: uvx --with "cairn-core[convert]" cairn-mcp-server ...

服务会公开只读工具（列出、读取、搜索、grep、检索），客户端可自由运行这些工具；对于破坏性工具（移动、删除、编辑），则会先进行确认——这一流程由 MCP 工具注解决定，因此你无需使用我们的界面也能获得审批提示。

作为 CLI 使用：

uvx cairn-cli --workspace ~/Documents/notes tree
uvx cairn-cli --workspace ~/Documents/notes retrieve "budget planning"

使用可选的 Web UI：

pip install cairn-cli cairn-web
cairn --workspace ~/Documents/notes serve   # → http://127.0.0.1:4177/

.uni 格式

.uni 文件是一个小型 JSON 文档——{ uuid, content: "<html>", metadata, tags }——标签存储在文件中。工作区就是一个目录：完全可移植，无需外部数据库。源文档（docx/pdf/pptx/…）会导入为可编辑的 .uni 文档；默认情况下会保留原始文件。

本地优先，自备密钥

• 无需账户、无需登录、无需云同步。文件系统是唯一可信的数据源。
• 默认检索器采用词法检索，无需任何配置。嵌入功能为可选项，需自备密钥（支持任何兼容 OpenAI 的端点，包括 Ollama 或 LM Studio 等本地服务）；向量保存在 <workspace>/.cairn/ 下的本地 SQLite 索引中，绝不会离开你的设备。

路线图

Cairn 还处于早期阶段。以下是大致方向，也欢迎大家在这些方面提供帮助：

• 支持更多文档格式 — 增强 frontmatter 支持（嵌套元数据、日期），并支持将编辑内容转换回导入时的源格式。
• 更智能的摘要 — 配置嵌入模型后，使用该模型生成摘要；并支持保存的视图（.cairn/views/*.md）。
• 支持更多检索后端 — 可插拔的重排器；除通用的 OpenAI 兼容方案外，提供开箱即用的本地模型预设（Ollama、LM Studio）。
• 编辑器/Agent 集成 — 提供轻量的配置指南，帮助将 Cairn 接入常见的 MCP 客户端和笔记工具。
• 打包 — 提供签名版本和 Homebrew formula。

遇到不适用的用例？提交 issue 或发起一场讨论。

贡献

欢迎任何规模的贡献 — 项目结构、开发环境配置以及如何添加工具，请参阅 CONTRIBUTING.md。适合新手的 issue 已标记为 good first issue。

开发

make setup      # uv venv (3.11) + editable install of all packages + extras
make test       # run the suite
make serve WORKSPACE=~/Documents/notes   # web UI

许可证

MIT — 详见 LICENSE。