内容
# kb-mcp — 会话信息流转中心 & 历史记忆管理中心
> AI Agent 工作流的信息总线。
> 跨会话持久化记忆，在 Agent 之间中转大型文档，桥接历史上下文 — 全部存在一个 SQLite 文件里。
[](LICENSE)
[](https://python.org)
[](tests/)
[](https://github.com/jlowin/fastmcp)
---
## kb-mcp 是什么？
现代 AI Agent 工作流跨越多个会话和多个 Agent。一个会话产出的信息（计划、审计报告、研究结论）必须能被下一个 Agent 获取，而不是整段粘贴进每个 prompt。上下文窗口有成本，重新发现信息是浪费，在 prompt 中全文传递大块内容会降低检索质量。
**kb-mcp 是解决这一问题的信息基础设施：**
- **编排器**将计划写入 `docs/PLAN_v1.md`，调用 `kb_index_path` — 2 秒内可检索。
- 下游 **oracle** 调用 `kb_search("计划 v1")` 获取相关 chunk，永远不需要接收完整文档。
- 新会话从上次中断处无缝续接，因为所有决策、交接文档和架构摘要都存在同一个 SQLite 总线里。
一个文件。无服务。无云端。完全自主掌控。
---
## 为什么选 kb-mcp？
本地记忆 MCP 已有先例 — Mem0 的 [OpenMemory MCP](https://mem0.ai/blog/introducing-openmemory-mcp)、[mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)、以及 Qdrant/Neo4j 自托管方案。kb-mcp **不是**第一个，它的独特之处在于**极致轻量**与**主动写入工具**的结合，让它成为活跃的信息总线，而不只是可查询的归档库。
| | kb-mcp | 重型自托管（Qdrant + Neo4j + Docker） | 云端（Mem0 / Zep 平台） |
|---|---|---|---|
| **存储** | 单个 SQLite 文件 | 多服务 + 数据卷 | 第三方服务器 |
| **部署** | `uv sync` + Ollama | Docker Compose，多容器 | API key + SaaS |
| **数据位置** | 仅在你的磁盘 | 你的磁盘（更重） | 云端 |
| **备份 / 迁移** | 复制一个 `.db` 文件 | 多服务导出 | 厂商导出 |
| **实时写工具** | `kb_index_path` + `kb_add_source` | 各异 | API |
| **生命周期** | active → stale → archived → evicted + 墓碑 | 各异 | 基础 CRUD |
| **链接图谱** | 97.3% wikilink 解析率 | 各异 | 通常无 |
| **内存占用** | 低（SQLite + 本地嵌入） | 高（向量库 + 图数据库） | 不适用 |
**诚实边界：**kb-mcp 为需要"零活动部件信息总线"的个人开发者和多 Agent 系统而建，不在云规模和团队功能上与 Mem0/Zep 竞争。
---
## 核心概念
### 信息流转总线
kb-mcp 作为整个 Agent 工作流的共享记忆层。任何 Agent 都可以写入文档（`kb_index_path`）、注册新知识源（`kb_add_source`）、或检索积累的知识（`kb_search`）— 全部通过同一个 MCP 接口。
```
Agent A 写入计划 → kb_index_path("docs/PLAN_v1.md")
Agent B 读取计划 → kb_search("实现计划 v1")
新会话续接上下文 → kb_search("上次会话交接决策")
```
### 大文档中转协议
当 Agent 产出大型输出（≥ 300 行）时，将其全文注入下一个 Agent 的 prompt 既浪费 token 又降低检索质量。正确的模式：
```
1. 将文档写入磁盘： docs/PLAN_v1.md
2. 立即建索： kb_index_path("docs/PLAN_v1.md")
3. 传递引用而非全文： "通过 kb 搜索 'plan v1' 获取上下文"
4. 下游 Agent 调用： kb_search("plan v1") → 仅返回相关 chunk
```
### 历史记忆管理
五种文档来源覆盖 Agent 记忆的完整生命周期：
| 来源 | 用途 |
|------|------|
| `memory` | 持久项目笔记、规则、决策 |
| `handoff` | 会话交接文档 — 已做什么、下一步是什么 |
| `context` | 架构摘要、模块地图、系统快照 |
| `kb_native` | 项目专属文档（计划、审计、研究报告） |
| `export` | 外部导入、迁移内容 |
文档经历受管理的生命周期：`active → stale → archived → evicted`（含墓碑支持），搜索索引保持新鲜无需手动清理。
### 会话连续性
每个新会话都可以查询完整的历史决策、上下文和交接文档，无需重新读取源文件。Agent 新会话有知有据地开始，而非从零出发。
---
## 核心特性
- **混合检索** — sqlite-vec（向量）+ FTS5（全文 trigram）+ RRF(k=60) 融合，top-5 准确率约 90%
- **实时写工具** — `kb_index_path` 支持单文件即写即索；`kb_add_source` 注册新目录并立即触发索引
- **Wikilink 解析** — `[[文档名]]` → 解析为 `dst_document_id`，真实语料解析率 97.3%
- **生命周期管理** — `active / stale / archived / evicted` 四态，含审计行与墓碑支持
- **原子索引** — 每文档独立 SAVEPOINT，单文档失败不污染批次
- **MCP 原生** — 6 个工具通过 stdio 传输暴露，查询时零外部 API 调用
- **增量索引** — SHA-256 内容哈希，未变文件跳过，仅对变更文件重新嵌入
- **五源知识** — `memory · handoff · context · kb_native · export`
- **103 个测试** — 集成测试（真实 Ollama）+ 单元测试（in-memory SQLite），零 mock
---
## 系统要求
- Python **3.12+**，使用 [uv](https://docs.astral.sh/uv/) 管理
- [Ollama](https://ollama.com/) 本地运行，并拉取 `qwen3-embedding:0.6b`
- SQLite 3.35+（Python 内置）
```bash
# 拉取嵌入模型（一次性操作）
ollama pull qwen3-embedding:0.6b
```
---
## 安装
```bash
git clone https://github.com/chjien1917/kb-mcp.git
cd kb-mcp
uv sync
```
### 初始化索引
```bash
# 全量索引你的 Markdown 知识文件
uv run kb index --full
# 查看统计
uv run kb stats
```
默认自动发现 `~/.claude/` 下的文件。可通过 `~/.config/kb/config.toml` 自定义（见[配置](#配置)）。
---
## MCP 接入
### opencode
在 `.opencode/opencode.json` 的 `mcp` 块中添加：
```json
"kb-mcp": {
"type": "local",
"command": ["/你的路径/kb-mcp/.venv/bin/kb-mcp"],
"enabled": true
}
```
### Claude Code / Claude Desktop
在 `~/.claude/claude_desktop_config.json`（Desktop）或 `~/.claude/settings.json`（Code）中添加：
```json
{
"mcpServers": {
"kb-mcp": {
"command": "/你的路径/kb-mcp/.venv/bin/kb-mcp"
}
}
}
```
---
## MCP 工具
### 工具
| 工具 | 说明 |
|------|------|
| `kb_search` | 混合向量+全文检索。参数：`query`、`k`、`mode`（hybrid/fts/vec）、`tags`、`source`、`include_archived`、`expand_links` |
| `kb_get` | 按 `document_id` 或 `path` 获取文档，含完整正文、出向/入向链接、标签，并更新访问计数 |
| `kb_stats` | 数据库统计：各来源/状态文档数、chunk 总数、链接解析率、最近索引记录 |
| `kb_related` | 遍历 wikilink 图谱：获取文档的出向和入向已解析链接 |
### 写工具
| 工具 | 说明 |
|------|------|
| `kb_index_path` | 立即索引单个 `.md` 文件。写入大型文档后调用，约 2 秒内可检索。返回 `document_id` 和 `chunks_written` |
| `kb_add_source` | 将目录注册为知识源并可立即触发增量索引，持久化到 `config.toml` 的 `scan.roots`。有效来源：`kb_native · memory · handoff · context · export` |
---
## 典型 Agent 工作流
```python
# 1. 编排器：planner 产出大型计划文档
# 落盘后立即注册
kb_index_path("project/docs/PLAN_v1.md", source="kb_native")
# 2. 新项目目录？注册一次 — 后续文件自动扫描
kb_add_source("project/docs", source="kb_native", index_now=True)
# 3. Oracle / 下游 Agent：检索相关上下文，无需全文传递
results = kb_search("实现计划 数据库 schema", k=5)
# 4. 任何新会话：从上次已知状态续接
handoff = kb_search("上次会话交接决策", source="handoff")
```
---
## 配置
可选配置文件 `~/.config/kb/config.toml`：
```toml
[db]
path = "~/.local/share/kb/kb.db"
[embed]
base_url = "http://127.0.0.1:11434" # Ollama 地址
model = "qwen3-embedding:0.6b"
batch_size = 32
[[scan.roots]]
path = "~/.claude"
source = "memory"
[[scan.roots]]
path = "/你的项目/docs"
source = "kb_native"
```
环境变量覆盖：
- `KB_WORKSPACE_ROOT` — 工作空间根目录
- `KB_LOG_LEVEL` — 日志级别（默认 INFO）
---
## CLI 参考
```bash
uv run kb index # 增量索引
uv run kb index --full # 全量重建
uv run kb stats # 打印统计信息
uv run kb search "query" # 终端搜索
uv run kb get <doc_id> # 按 ID 获取文档
```
---
## 开发
```bash
uv sync --dev
# 跑全量测试（集成测试需要 Ollama 在线）
PYTHONPATH=. uv run pytest tests/ -q
# 仅跑单元测试（无需 Ollama）
PYTHONPATH=. uv run pytest tests/ -q -m "not integration"
---
## 许可证
MIT © [SHI JIE HOU](https://github.com/chjien1917) — 详见 [LICENSE](LICENSE)
