cairn — 石堆纪念碑

cairn 是一个本地混合索引，用于收集代码库、设计文档、审计笔记、网页、PDF、原始文本等内容。它支持三种操作：curate（策划）、ingest（导入）和retrieve（检索）。cairn 有两种运行模式：一种是使用 SQLite 文件，无后台进程（embedded）；另一种是使用后台进程（ollama）。

cairn 的主要功能包括：

Hybrid chunk search（混合块搜索）：使用 FTS5 和向量嵌入相结合的方式进行搜索，返回排名的文本块。 Knowledge graph（知识图谱）：从代码和 markdown 中提取实体和边，构建知识图谱。 Composed retrieval（组合检索）：将搜索和实体上下文结合在一起，减少搜索和图谱之间的往返。 Shortest path（最短路径）：在两个实体之间找到最短路径。 Batched layer fetch（批量层次获取）：使用 BFS 算法获取最短路径。 Tag-filtered retrieval（标签过滤检索）：使用标签过滤搜索结果。

cairn 支持多种查询接口，包括 search、graph、ask、path 和 tags。它还支持跨源链接和软删除。

使用 cairn 的步骤包括：

• 导入 cairn 库：import { Cairn } from 'cairn-index'
• 创建 cairn 实例：const cairn = new Cairn()
• 添加内容：await cairn.ingest.add({ kind: 'code', path: './src', label: 'my-project' })
• 搜索内容：const hits = await cairn.retrieve.search('how does the chunker handle overlap', { k: 5 })
• 关闭 cairn：cairn.close()

cairn 还提供了 CLI 和 MCP 接口。CLI 接口支持添加、搜索、图谱和路径等操作。MCP 接口提供了 search、list、add、graph、ask、path 和 tags 等工具。

cairn 的运行时有两种选择：ollama 和 embedded。ollama 是默认的运行时，embedded 是可选的运行时。cairn 的模式有两种：一种是使用 SQLite 文件，无后台进程；另一种是使用后台进程。

cairn 的安全性和隐私包括：

无网络出口，除非用户明确要求。 无遥测。 无 API 密钥。 无账户。 无远程代码执行。 内容存储为文本，永远不会被评估。 只读模型侧接口。 MCP 暴露了导入（添加、刷新）以便模型可以策划索引，但删除/链接/取消链接/重新索引仅限于 CLI - 破坏性或更改拓扑的操作需要人类。

cairn 的依赖项包括 better-sqlite3、sqlite-vec、linkedom、unpdf、zod、MCP SDK 和三个 tree-sitter 语法。node-llama-cpp 仅在 CAIRN\_RUNTIME=embedded 时使用。

cairn 的验证包括 16 个测试，包括 5 个纯测试和 11 个实时测试，包括 LLM 文档提取和嵌入式运行时端到端测试。实时测试涵盖了实际的 ollama 和 node-llama-cpp 路径，而不是模拟。文档提取 LLM 通过使用 ollama 的格式（或 llama.cpp 的语法）进行 JSON-Schema 强制输出，即使默认的聊天模型也会发出形状有效的概念/边/标签。哈希门重新提取。概念在刷新时重新出现；文档派生边从头开始重建；解析