@dikolab/kbdb

一个基于文件的知识库，支持按相关性排序的关键词搜索与语义（混合）搜索——先学习你的文档，再召回相关的内容。无需外部服务器。可作为 CLI 与 MCP 服务器运行。

📖 文档 · MCP 配置 · CLI 参考

GitLab | NPM | JSR | 许可证：AGPL-3.0

运行于 Node.js 20+ 或 Deno 2.6+ 上。无需数据库服务器、无需云账户——只需要磁盘上的文件。

kbdb 是什么？

kbdb 为 AI 智能体提供一个持久化、可搜索的第二大脑。把这些 .md 文档发给它，它就会构建一个基于文件的知识库——然后智能体（或你自己）即可通过按相关性排序的关键词搜索和语义搜索，而不是精确关键词匹配，来回想起最相关的记录。它是一个 活跃的 存储：智能体可以跨会话学习新事实、更新已有事实，再召回这些事实。

无需安装外部服务器，无需云账户——只需要磁盘上的文件。它可以运行在任何支持 Node.js 或 Deno 的地方，并以 MCP 服务器的形式运作，因此 Clode 这样的智能体就可以把它当作记忆工具接入。

What does the search do? kbdb 默认使用 关键词搜索——语义文件扩展、词项按相关性排序，且在计分中标题权重为 ×2。当精确查询找不到结果时，kbdb 会自动放宽匹配条件，以保证你仍然获得可用的最优结果。

想要更智能的结果？使用 --algo hybrid 将关键词匹配与相似性搜索结合——即使是同义词描述同一概念，也能找到结果。默认 TF-IDF 嵌入提供者离线即可工作，零配置。需要更丰富的语义嵌入时，可在 worker.toml 中第三方提供者（本地 ONIX 模型或远程API）。

知识保持常新： 重新学习单个文件，kbdb 就会自动替换旧版本。近重复检测会在你学习自己已经有了的内容时给出警告——它基于嵌入相似度，因此能发现同一事实被改写后的版本 —— 即只改掉了相同的字节。kbdb contradictions 会报告覆盖到同一下的主题，以便你同时阅读这些内容。完整性检查会校验校验和以及或孤立引用。置信度分数以帮助智能体区分强相信和弱相信。

Related MCP server: Librarian

快速上手

前置要求

在以下中选择一个（使用你已经有的那个）：

• Node.js 20 或更高版本 —— 下载

• Deno 2.6 或更高版本—— 下载 （2.6 是下限：存储引擎通过 source-phase imports 加载其 WebAssembly，这样在 deno install 一次即可离线运行。旧版 Deno 会失败抛出"模块未找到" 的误导性错误，指向一个实际的 .was 文件必须存在。）

就是这样。不需要数据库服务，不需要额外工具。

安装

使用 Node.js：

CLI 构建版本托管在 NPM 上，就可以用了。

npm install -g @dikolab/kbdb

使用 Deno：

CLI 构建版本托管在 JSR 上。

deno install -Agf jsr:@dikolab/kbdb/cli

请参见 CLI 安装指南 了解前置与验证步骤。

试一试

1. 创建一个知识库

kbdb db init --db ./my-kb

这会创建一个 .kbdb 文件夹，保存你的所有数据。

2. 喂入你的文档

kbdb learn ./docs

指向包含 Markdown 文件的文件夹。kbdb 会读取这些文件，拆分成小节，并构建搜索索引。可加上 --tags design,v2 给小节打标签以便限定范围，加上 --replace 更新相同来源的已有节，或 --level 2 设置层次深度（1 = 最宽泛，6 = 最具体）。如果要学习一个目录，层级会根据文件夹深度自动检测。

3. 搜索

kbdb search "how does auth work"

结果按相关性排序，并显示片段提示你的词在哪些位置命中。输出默认即 --format out（recfile 输出：每行 field: value），就能直接 grep。

其他说格式的格式：json（机器可读）、text（编号列表）、和 mcp（JSON-RPC 2.0 信封）。用 --offset paging. 可以对大结果集分页。

要试混合搜索（关键词 + AI 相似度）：

kbdb search "how does auth work" --algo hybrid

**提示：CLI 下 --db 可选。**kbdb 会从你的工作目录向上直到最近的 .kbdb 文件夹为止，所以在一个项目内任意路径执行命令都可用。用 --db <目录>（即 .kbdb 的父目录）指向具体数据分，或设置 KBDB_DB_DIR 变量。只有 mcp服务器需要明确的--db`——它从不在工作目录中搜索。

跨库搜索： 通过 --other-ab <dir>（可重复）从其他库来补充只读的知识从而增强结果，或者再加上 --cascade 同时也回向上级 .kbdb 文件夹提取：

kbdb search "how does auth work" \
   --other-db ~/shared-kb --cascade

每个结果都会携带 source_db 字段——说明是哪个库根目录。可以直接把该字段粘贴回 --db 或 --other-db 中。

脚本化： 增加 --format json 后，输出结构化可解析内容。流水线里可以用 --non--interactive 或设 KBDB_NON_INTERACTIVE=1 来抑制提示。

4. 召回上下文

kbdb recall <kbid> --depth 1

从一个搜索结果的 kbid 开始，展开渐进上下文：级别 0 返回小节内容，级别 1 加入父文档目录与反引用，级别 2 添加同分支及正向引用，级别 3` 包含所有被引用小节的完整文本。**

知识库

构建你的知识和搜索及维护。

• 导入 Markdown 及纯文本，支持标签和路径跟踪。

• 智能更新 —— 重新学习文件会替换旧版本而不是产生新副本。

• 历史 —— 替代签名并被改的命令位置 kbdb history 可以看到完整历史链（从任何一端），而且旧 kbid 依然解析。

• 搜索 使用选择适合的算法：关键词（默认）、AI 语义或混合（混合两者）。

• 自动回退 —— 如果精确查询没结果，kbdb 会自动放宽条件。

• 召回 支持渐进式上下文——从单条摘要直到完整相关内容，也可以限制在 --max-max 预算内。

• 评判 系统测量是否真的有用——kbdb eval 基于自己的数据评分 Recall@k、MRR 和 nDCG@k；若效果变化使排序更差则会退出非零。

• 邻接 —— kbdb neighbourhood 显示“什么与某小节相关”以及相关强度：它有 8 类边：其中 6 个是记录的关系，7 个是从侧攻击的关联，还有 7 个是推理得出。

• 合并 —— kbdB consolidate 会建议可以将哪几个某个小节并为合并称量。它只提出建议，合并需要你自己去撰写并应用。

• 导出 —— 把知识库快照你所取，用于备份。

• 验证 基础库完整性以及清理过时数据。

• 重建 —— 在出现问题时重建索引。

如需完整的导向性说明（包括导出与备份），请参阅 知识库指南。

智能体工具

把 kbdb 与 AI 智能体，CSDNX - 以及工具类集成。

**MCP 快速入门：**Quode CLI(可能未来了) —— 快速 也就是说。

claude mcp add kbdb -- \
   npx @dikolab/kbdb mcp --db /path/to/project

安装说明请查看 MCP 安装指南，其中包含用于 Clode Code、VS Code 或 Claude Desktop 的配置模板和故障排查。

• MCP server 提供的 30 30 个工具——搜索、召回、学习、修订、发现缺口、矛盾内容检测、导出、技能/智能体搜索，等等。

• Skills —— 存储可复用模板，和填充参快速 Create（空位参数）。

• Agents **—— 创建 AI 智能体 profile（教授写法），结合 persona 与 技能组合。

• Capture 策略——服务器要求智能体使用该功能：MCP 握手时以合适的“它”节即可。它必须能约束：其实字符串是十句可以设置的：role + 因此，六条条款中有两条是“不要”存什么：聊天摘要、猜测、密钥以及代码中已经包含的信息。kbdb 提供这份存储；就只将不会让所有智能遵守。

• 自动捕获——可以请求主机方模型挑选值得保存的内容。需要 MCP sampling 能力，而且 Clode Code 并不宣告该能力，因此这里自动捕获被锁止。其他功能不受影响——见 主机支持。

• Daemon 弹性——可配置请求超时，并且守护进程在漂移自动重试与重启。

• Worker 守护进程管理 — 停止并重启后台进程。

• 更细粒度的 Deno 权限——守护进程将以配置的权限运行，禁止 --allow-all。

• 限制路径 ——守护进程除了解嵌套 .. 之类的路径遍历，例如导出或导入请求。

服务器对智能体说了什么。initialize 响应带有一个 instructions 字符串——这是每个规定的 MCP 主机都能在该组件出生无需设置进货的渠道。kbdb 用于“脚手架”模式：搜索前先回答；unanswered 视为必须处理 的空缺、而不是猜测；查找需要实际付出代价才能得到的决策和更正，而不存储代码中已经指示的任何数据。同样的句子也引用在learn、revise 和已有的 查询工具描述里，基本不归因，保持单一来源。

如还想知道方面，请参阅智能体工具指南 学习 MCP 配置、技能、智能体以及库 API，以及Capture 策略的全文——

面向开发者

库 API

库方法： 以下在你的 Node.js 或 Deno 项目原有内部来调用库函数：

import { createWorkerClient } from '@dikolab/kbdb';

// Spawns a background worker if not already running
const client = await createWorkerClient({
   contextPath: '/path/to/.kbdb',
   requestTimeoutMs: 30_000,
});

const results = await client.search({
   query: 'authentication',
   limit: 10,
   offset: 0,
});

console.log(results.items);
client.disconnect();

传递 contextPath（.kbdb 目录）或 dbPath（父目录 — kbdb 会在在该路径中）时发现 .kbdb）。

完整的 API 请见 [库 API 参考](https://diko316.git/x...

开发环境设置

git clone https://gitlab.com/diko316/knowledge-base-db.git
cd knowledge-base-db
npm install
npm test

Docker

两种 Dockerfile 不可通用。

仓库根下的 Dockerfile 构建的是 MCP server——是 MCP 目录横移构建、如果你想容器里获得 kbdb 而应使用哪一个。配置文件和用 named volume 而不是 bind mount ，请看 安装 MCP 服务器。

Dockerfile.tooling 则构建开发工具链（Node.js 和 Deno），配合 docker-compose.yaml 供每一个 make 目标使用：

HOST_UMASK=$(umask) docker compose run --rm tool sh

运行 make benchmark 测量提交次数和实际转译延迟，结果会自动写 [来 docs/benchmark/benchmark.md](https://diko316./knowledge-base-db/build...。完成目标列表请看 Makefile。

贡献

1. Fork 本仓库

2. 创建分支创建一个 feature

3. 实施更改并添加测试

4. 运行 npm test 和 npm run lint

5. 提交合并请求 Merge Request

文档

• Second Brain with Claude Code -- 规范 set to Setup guide: https://diko316.gitlab.io/...\\\\-- 请稍候。 -- 规范的设置指南、工作区布局， 正确的命令、MCP 连接

• CLI Installation Guide -- 前置条件、npm/JS R install、验证

• Knowledge Base Guide -- 导入、搜索、召回、导出

• Agent Tooling Guide -- MCP、技能、智能体、库 API

• CLI Reference -- 完整命令 列表与示例

• MCP Installation Guide -- Claude CLI、Claude Code、VS Code、Claude Desktop

• MCP Server Guide -- 设置、工具、环境配置，以及服务器 在 initialize 时告诉智能体的内容

• Host Support -- 哪些 MCP 主机提供捕获策略并 通告采样，基于实测而非假设

• Capture Policy\ -- kbdb 告诉智能体要存储什么，以及为什么 只需说明一次

• Search and Ranking\ -- 搜索在底层如何工作

• Storage Architecture\ -- 文件格式、目录布局，以及保留 历史记录成本

• Deno Permissions\ -- kbdb 需要的权限标志，以及原因

• Benchmark\ -- 大规模下的搜索与重建延迟

• Lean scaling\ -- 学习成本如何随语料库总规模增长

• Contradiction signals\ -- 在 1128 个标注的样本对上校准近似重复和矛盾阈值

• Reelase Notes

• Architecture Overview

搜索引擎

Storage、索引与排序来自 @dikolab/vdb, 作者的兄弟项目。其 文档深入介绍检索端：

• vdb Overview -- 存储模型、分区、BM25F、向量与混合

• vdb Examples
  -- 实际查询与排序行为

支持

kbdb 是免费软件，采用 AGPL 许可证。如果它值得 你在工作流，你可以通过 PayPal 支持它的预计开发。

License

本项目为双许可：

• 开源许可 基于 GNU Affero General Public License v3.0 (AGPL-3.0-only)

• 商业许可 可用于闭源或 SaaS 使用

版本 <= 0.5.0 继续使用 ISC 许可证。

详见 LICENSING.md 了解细节和联系方式。