内容
<p align="center">
<img src="assets/archiver-rag-lockup.svg" alt="Archiver RAG" width="320" />
</p>
<p align="center">
<em>为您的知识图谱提供检索辅助</em>
</p>
<p align="center">
面向Obsidian知识库的代理无关内存管理系统
</p>
Archiver RAG 将您的Obsidian知识库转变为一个实时、可查询的知识图谱，任何与MCP兼容的AI代理都可以搜索、更新和重新组织——无需离开其原生界面。
连接一次。您使用的每个代理（Claude Code、Cursor、Gemini CLI或您自己的代理）都具备语义搜索、自动知识记录、维基链接感知图遍历和知识库健康监测等功能。
---
## 工作原理
```
您的Obsidian知识库（.md文件）
↓ 文件监视器 + 摄入管道
ChromaDB（持久向量存储）
↓ MCP服务器
任意与MCP兼容的代理
```
三个层次使搜索比简单嵌入更智能：
1. **上下文前缀** — 每个区块都嵌入了其笔记的元数据（文件夹、标签、维基链接），因此向量携带结构化上下文
2. **丰富的元数据过滤** — ChromaDB存储文件夹、标签、传入链接数和维基链接，以便过滤检索
3. **图重新排序** — 在向量搜索后，根据与上下文笔记的维基链接接近度和中心重要性重新评分结果
文件监视器在后台运行。 在Obsidian中编辑笔记，保存后，它会在几秒钟内被索引和自动链接 — 无需手动同步。
---
## 功能
- **语义搜索**，结合图重新排序 — 通过含义查找笔记，然后提升通过维基链接连接的结果
- **自动链接** — 每次摄入后，在`## 相关`部分追加`[[维基链接]]`，以自动构建知识图谱
- **知识记录** — 从任意代理创建带日期和分类的笔记（`决定`、`经验教训`、`注意`、`模式`等）
- **知识库健康** — 单次调用返回孤立笔记、损坏链接、缺失前置信息、标签统计和最近活动
- **维基链接感知重新组织** — 移动文件，知识库中的每个`[[链接]]`都会自动重写
- **智能聚类** — 标签传播算法根据维基链接结构对笔记进行分组，并建议文件夹组织
- **代理无关** — 暴露标准MCP接口；与任何与MCP兼容的客户端配合使用
---
## 要求
- Python >= 3.10
- [pipx](https://pipx.pypa.io/)（推荐安装）
- Obsidian知识库（本地`.md`文件）
- 与MCP兼容的代理（Claude Code、Cursor等）
---
## 安装
```bash
pipx install archiver-rag
```
> 使用`pipx`，而不是`pip install` — pipx创建隔离环境，并在`PATH`上全局公开CLI，这对于MCP注册找到正确可执行文件是必需的。
从此存储库的克隆进行本地开发时，请使用`pipx install --editable .`。
---
## 设置
运行一次性设置向导：
```bash
archiver-rag init
```
这将：
1. 询问您的知识库路径
2. 将您的知识库索引到ChromaDB
3. 在`~/.claude.json`中注册MCP服务器（或提示您为其他客户端手动注册）
4. 将后台监视器安装为launchd代理（Mac）或systemd服务（Linux）
---
## MCP注册（手动）
如果您更喜欢手动注册，请在MCP客户端配置中添加以下内容：
```json
{
"mcpServers": {
"archiver-rag": {
"command": "/path/to/archiver-rag",
"args": ["serve"]
}
}
}
```
使用`which archiver-rag`查找可执行文件路径。
对于Claude Code，具体操作如下：
```bash
claude mcp add --scope user archiver-rag $(which archiver-rag) serve
```
---
## 代理说明（技能）
注册MCP服务器使代理**访问**工具 — 但代理倾向于依赖自己的内部内存，而不是访问知识库。 [`skill/`](skill/)目录中的说明文件解决了这个问题：它们强制执行**知识库优先规则**，因此代理在执行其他操作之前在知识库中搜索和存储知识。
**技能执行的内容：**
- **在回答或读取源文件之前** — 首先调用`search_vault`；只有当知识库返回无关结果时，才回退到内部内存
- **当知识库中缺少某些重要内容时** — 主动`log_note`记录它。 如果事实、决定或上下文对整体情况很重要，而`search_vault`返回空结果，则记录它，以便知识图谱增长，而不是让上下文在单个会话中消失
- **解决非琐碎问题后** — 调用`log_note`将决定/经验教训/注意捕获回知识库
- **知识库是权威内存系统** — 内部代理内存仅作为备用
为每个代理提供一个版本，因为每个代理加载指令的方式都不同：
| 代理 | 文件 | 安装到 |
|---|---|---|
| Claude Code | [`skill/claude-code/SKILL.md`](skill/claude-code/SKILL.md) | `~/.claude/skills/archiver-rag/SKILL.md`（按需技能） |
| OpenCode | [`skill/opencode/AGENTS.md`](skill/opencode/AGENTS.md) | 项目根目录`AGENTS.md`或`~/.config/opencode/AGENTS.md` |
| Codex CLI | [`skill/codex/AGENTS.md`](skill/codex/AGENTS.md) | 项目根目录`AGENTS.md`或`~/.codex/AGENTS.md` |
| GitHub Copilot | [`skill/copilot/copilot-instructions.md`](skill/copilot/copilot-instructions.md) | `.github/copilot-instructions.md` |
每个文件都是自包含的 — 它包含该代理的MCP注册代码片段以及完整的知识库优先规则和工具参考。 对于Claude Code，文件是按需技能；对于其他代理，它是始终开启的指令文件（在每个会话中加载），这使得知识库优先行为无条件。
---
## CLI参考
```bash
archiver-rag init # 一次性设置向导
archiver-rag start # 启动后台监视器服务
archiver-rag stop # 停止服务
archiver-rag restart # 重启服务
archiver-rag status # 检查服务是否正在运行
archiver-rag index # 强制重新索引整个知识库
archiver-rag search "查询" # 从终端测试语义搜索
archiver-rag health # 区块计数和索引预览
archiver-rag logs # 跟踪服务日志
# 知识记录
archiver-rag log "标题" --type decision --tag arch --related NoteA
# 聚类
archiver-rag cluster # 建议文件夹分组
archiver-rag cluster --apply # 自动移动文件
archiver-rag place <note> # 建议单个笔记的文件夹
archiver-rag place <note> --apply # 立即移动它
# 配置
archiver-rag config --auto-cluster # 在监视器中启用自动聚类
archiver-rag config --cluster-threshold 5 # 创建新笔记数量达到触发完整聚类运行
archiver-rag uninstall # 删除所有数据、服务和MCP注册
```
---
## MCP工具（适用于代理）
注册后，代理可以访问7种工具：
| 工具 | 功能 |
|---|---|
| `search_vault` | 语义搜索，结合图重新排序。 接受`context_note`以提升维基链接邻居。 |
| `vault_status` | 知识库结构、健康诊断、标签统计和最近活动，一次调用。 |
| `get_connections` | BFS维基链接遍历 — 深度3的出站和入站链接。 |
| `move_notes` | 移动文件并自动重写知识库中的所有`[[维基链接]]`。 |
| `log_note` | 创建带日期的知识笔记；监视器索引并立即链接它。 |
| `cluster_note` | 根据维基链接邻居的位置，建议为单个笔记选择文件夹。 |
| `cluster_vault` | 整个知识库的标签传播聚类，附带文件夹建议。 |
---
## 配置
所有运行时配置都位于`~/.archiver-rag/config.json`：
```json
{
"vault_path": "/path/to/your/vault",
"install_path": "/Users/you/.archiver-rag",
"chroma_path": "/Users/you/.archiver-rag/chroma_db",
"auto_cluster": false,
"cluster_threshold": 5
}
```
`auto_cluster` — 通过监视器自动建议和应用新笔记的文件夹位置。
`cluster_threshold` — 创建新笔记数量达到触发完整`cluster_vault`运行。
---
## 知识图谱模型
知识库被视为**知识图谱**，而非文件层次结构。 笔记是节点；维基链接是边。 关系范围从紧密（直接链接）到松散（通过搜索浮现的语义接近度）。
笔记类型通过前置信息表达，而非文件夹结构：
```yaml
---
type: decision
tags: [architecture, async]
related: [[AsyncLocalStorage]], [[PrismaExtensions]]
date: 2026-04-27
---
```
笔记底部的`## 相关`部分由自动链接器在每次摄入后自动管理。 请勿手动编辑 — 它将被覆盖。
---
## 路线图
即将推出的功能：
- **RAG-Anything集成** — 将摄入范围从Markdown扩展到处理PDF、Office文档、图像和其他文件类型，以便知识库可以成为真正的多格式知识库，而不仅仅是`.md`。
- **Archiver子代理** — 专用子代理，负责代表主代理进行知识库管理（搜索、记录、重新组织、聚类），以便主代理可以委托知识工作，而不是在上下文切换到知识工作中。
---
## 许可证
MIT
