内容
# tesseract-mcp
**一个用于人工智能代理的持久化、共享思维，建立在Obsidian知识库之上。**
每个Claude会话 — 在任何机器上 — 都从同一个知识库中读取和写入：一个由自我托管的LiveSync（CouchDB）复制的纯Markdown Obsidian知识库。这个MCP服务器是代理搜索、扩展和保持知识库有条理的方式。
## 工作原理
```mermaid
flowchart LR
subgraph 代理端
C[Claude 或任意 MCP 客户端]
end
C <-->|MCP 工具| S[tesseract-mcp 服务器]
S <-->|读取/写入 Markdown| V[(Obsidian 知识库)]
S <-->|可重建缓存| Q[(SQLite + ~/.tesseract-mcp/中的嵌入式模型)]
L[图书管理员 + 组织者<br/>定时维护者] -->|索引、归档、修复| V
L --> Q
V <-->|LiveSync| DB[(CouchDB)]
DB <-->|LiveSync| M2[其他机器上的知识库]
```
知识库的Markdown是单一的真实来源。服务器计算的所有内容 — 搜索索引、嵌入式模型、图缓存 — 都位于`~/.tesseract-mcp/`下，并且可以根据需求从知识库中重建，因此它永远不需要通过LiveSync本身进行传输。
## 内部结构
### 混合搜索
BM25关键词排名和嵌入式余弦相似度，与互惠排名融合 — 基于排名的融合意味着两个评分空间永远不需要相互标准化。向量在新鲜时重用Obsidian的智能连接嵌入式模型，并具有相同的本地备用模型（bge-micro-v2），因此相似度空间永远不会混合。
### 语义知识图（GraphRAG）
一个LLM通道从笔记中提取人物、组织、领域、主题、项目和来源到实体的Markdown笔记下 `Claude/Graph/` — 在Obsidian的图中可见，与其他内容同步，并镜像到SQLite进行遍历。`related_notes`在笔记之间行走实体链；`context_bundle`在一个调用中组合混合搜索和图上下文。
### 代理无法破坏的写入契约
代理仅在 `Claude/` 下自由写入（会话、概念、收件箱、任务、决策、图表）。其他所有内容都属于人类：始终可读，只有在明确确认时才可写入 — 在代码中强制执行，而不是按照惯例。人类可读的规则作为宪法存储在知识库中。
### 自主组织者
新笔记通过嵌入式邻居投票（≥0.7同意移动笔记；较少的情况会提示人类提出建议）归档到现有的文件夹分类中。每次移动都会记录并可逆转。
### 图书管理员
单个定时维护者循环（`python -m tesseract_mcp.librarian <vault>`）运行索引、组织、缓存维护、限流合并提案和健康检查 — 替换单独的索引器和组织者cron作业。扫描报告保存在`Claude/Librarian.md`中；`librarian_status` MCP工具读取最后一次运行。
### 一键知识库配置
`python -m tesseract_mcp.provision <path-to-vault>`安装固定的插件集、种子设置（嵌入式模型固定为搜索堆栈读取的内容），并安装代理约定树。`--check`报告版本漂移。
### 召回机制
Claude Code技能将知识库转化为你可以查询的记忆：`/recall`（研究答案，每个声明都作为`[[wikilink]]`引用），`/digest`（审查仪式），`/resume`（项目简介），和`/connections`（图 serendipity）。`/recall`将每个答案归档到`Claude/Answers/`，图书管理员像处理其他笔记一样索引它 — 因此答案成为检索源，知识库通过提问而不是仅通过摄入而不断增长。五个进一步的仪式被起草并等待其验收运行：`/clip`（编译外部来源到引用的Inbox笔记），`/distill`（将重复的捕获提升为常绿概念），`/decide`（仅追加的决策账本），`/rounds`（只读维护者健康检查），和`/dossier`（深度多部分简介）。技能位于[`skills/`](skills/)中，并使用`python -m tesseract_mcp.skill_sync`安装（附加；`--check`报告漂移；现有技能永远不会在没有`--force`的情况下修改）。
## 检索工作原理
```mermaid
flowchart LR
Q[查询] --> F[候选过滤<br/>标签/文件夹]
F --> B[BM25L关键词排名<br/>前50名]
F --> E[余弦相似度<br/>智能连接向量,<br/>bge-micro-v2备用<br/>前50名]
B --> R[互惠排名融合<br/>k = 60]
E --> R
F -.->|仅当BM25为空时| SUB[子字符串排名]
SUB -.-> R
R --> H[排名结果与摘录]
```
每个查询都在过滤后的候选集上运行两个排名器，RRF按排名位置合并它们 — 因此BM25分数和余弦相似度永远不需要相互标准化。子字符串排名器是针对BM25的标记化无法匹配的查询（单个字符、标点符号）的备用信号，永远不是第三个竞争者。详细内容请参见[ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 检索质量衡量
| 成功率@5 | 成功率@10 | 召回率@5 | 召回率@10 | MRR |
|---|---|---|---|---|
| 0.88 | 0.94 | 0.88 | 0.94 | 0.89 |
十六个黄金查询 — 关键词、释义、标题、标签、实体和退化输入陷阱 — 在生产`hybrid_search`路径上使用真正的bge-micro-v2嵌入式模型，在[`evals/`](evals/README.md)中提交的合成20-note语料库上运行（合成是因为此仓库是公开的；私有黄金集存储在知识库本身）。使用`python -m tesseract_mcp.evals`重现。
## 工具
| | 工具 | 用途 |
|---|---|---|
| **定向** | `onboard` | 在新会话中调用 — 宪法、路由、速查表、图状态 |
| **检索** | `search_brain` | 混合搜索（BM25 + 向量，RRF融合），可选标签/文件夹过滤 |
| | `context_bundle` | 一次调用：搜索结果 + 其图实体 + 相关笔记 |
| | `recall_bundle` | 为召回技能准备原材料 — 一次只读调用 |
| | `read_note` | 读取任意笔记 |
| | `query_notes` | 按前置元数据查询笔记 |
| | `get_backlinks` | 笔记的`[[wikilink]]`指向某笔记 |
| | `list_recent` | 最近修改的笔记 |
| | `list_tasks` | 跨知识库的复选框任务 |
| **写入** | `log_session` | 会话日志到`Claude/Sessions/` |
| | `capture` | 快速思考到`Claude/Inbox/` |
| | `upsert_concept` | `Claude/Concepts/`中的常绿笔记 |
| | `write_note` | 一般写入 — 隔离到`Claude/`除非确认 |
| | `add_task` | `Claude/Tasks.md`中的复选框任务（Obsidian任务格式） |
| **图** | `index_brain` | 从新/更改的笔记中提取实体 |
| | `find_entity` | 按名称/别名查找实体 |
| | `related_notes` | GraphRAG：通过共享实体连接的笔记，以及链条 |
| | `graph_stats` | 实体/边/提及计数 |
| | `consolidate_graph` | 合并重复实体（默认干预） |
| **组织** | `organize_vault` | 自主归档扫描（默认干预） |
| | `librarian_status` | 最后一次维护者扫描 + 健康报告（只读） |
| | `undo_move` | 撤销记录的移动 |
## 快速入门
```powershell
git clone <repo> ; cd tesseract-mcp
python -m venv .venv
.venv\Scripts\pip install -e .
# 配置新的知识库（插件、设置、约定）
python -m tesseract_mcp.provision <path-to-vault>
# 注册精选MCP服务器集（tesseract + web/paper ingest）
$env:TESSERACT_VAULT_PATH = "<path-to-vault>"
.venv\Scripts\python -m tesseract_mcp.mcp_sync
```
清单位于`mcp-servers.json`；同步仅为附加（现有条目永远不会被修改或删除）。
然后在Obsidian中打开知识库一次（禁用限制模式，完成LiveSync设置），并运行`index_brain`工具。
## 定时维护
图书管理员是知识库维护的单个定时任务：
```powershell
python -m tesseract_mcp.librarian <path-to-vault>
```
它排空索引积压，运行组织者扫描，根据需要重建图缓存，提出合并提案（仅干预），并将健康报告写入`Claude/Librarian.md`。使用`librarian_status`读取最后一次扫描而无需运行它。
**针对真实知识库的第一次运行必须使用`--dry-run`**，并由人工审查后再安排无人值守应用 — 与组织者相同的操作规则。干预运行打印格式化报告和JSON结果，而不写入状态、移动或节流基线。
`claude`提取后端（`codex`忽略）的模型选择：
| 环境变量 | 默认值 | 用于 |
|---|---|---|
| `TESSERACT_EXTRACT_MODEL` | `haiku` | 按笔记提取实体 |
| `TESSERACT_CONSOLIDATE_MODEL` | `sonnet` | 合并提案 |
## 更深入
- [架构深入](docs/ARCHITECTURE.md) — 检索管道、图设计、模块映射。
- [服务器部署](server/DEPLOY.md) — CouchDB + Caddy用于LiveSync。
