kbdb

@dikolab/kbdb

一个基于文件的知识库，支持排序关键词搜索和 语义（混合）搜索——学习您的文档， 然后检索相关知识。无需外部 服务。可作为 CLI 和 MCP 服务运行。

📖 文档 · MCP 配置 · CLI 参考

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

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

---

什么是 kbdb？

kbdb 为 AI Agent 提供持久、可搜索的 第二大脑。将它指向您的 Markdown 文档，它会 把文档索引到一个基于文件的知识库中—— 然后 Agent（以及您）便可通过排序关键词和语义搜索， 而非精确键查找，检索最相关的 知识。这是一个持续演进的存储库：Agent 可以学习新事实、更新事实，并在不同会话间检索这些内容。

无需安装外部服务，无需云账户—— 只需磁盘上的文件。它可以在任何能运行 Node.js 或 Deno 的环境中运行， 并可作为 MCP 服务使用，因此 Claude 等 Agent 可以将其接入为 记忆工具。

搜索原理： kbdb 默认使用关键词搜索—— 扩展同义词、按相关性对词项排序，并在 评分时为标题赋予 2× 权重。当精确查询没有结果时，kbdb 会自动放宽匹配条件，让您仍能获得 最佳可用结果。

想要更智能的结果？使用 --algo hybrid 将 关键词匹配与相似度搜索结合起来——即使不同的词语描述的是同一 概念，也能找到结果。默认的 TF-IDF 嵌入提供方 无需设置即可离线运行。需要更丰富的 嵌入时，可在 worker.toml 中将其替换为 第三方提供方（本地 ONNX 模型或远程 API）。

让知识保持最新： 重新学习某个文件时，kbdb 会自动替换旧版本。 近似重复检测会在您学习已有内容时发出提醒—— 它通过嵌入相似度进行检测，因此能发现措辞不同但事实相同的内容，而不只是 字节完全相同的内容。kbdb contradictions 会报告 涉及相同主题的章节，方便您放在一起阅读。完整性检查会验证校验和、 孤立项及引用。置信度分数可帮助 Agent 区分强匹配和弱匹配。

---

入门

所需条件

任选其一（选择您已有的即可）：

• Node.js 版本 20 或更高—— 下载
• Deno 版本 2.6 或更高—— 下载 （2.6 是最低版本：存储引擎通过源阶段导入加载 WebAssembly，因此在执行一次 deno install 后即可离线运行。较旧版本的 Deno 会报错， 并给出误导性的 Module not found 提示，指出一个实际存在的 .wasm 文件。）

就这些。无需数据库服务，也无需额外工具。

安装

使用 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 rec（recfile：每 行一个 field: value），便于使用 grep 搜索。其他格式包括：json （机器可读）、text（编号列表）和 mcp（JSON-RPC 2.0 封装）。使用 --offset 可 分页浏览大量搜索结果。

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

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

提示：CLI 中的 --db 为可选参数。 kbdb 会从当前工作目录向上查找最近的 .kbdb 文件夹， 因此在项目内的任何位置都可以直接运行命令。使用 --db <dir> 指定 特定知识库（.kbdb 的父目录）， 或设置 KBDB_DB_DIR。只有 mcp 服务 需要显式指定 --db——它绝不会搜索 当前工作目录。

跨知识库搜索： 使用 --other-db <dir>（可重复指定）从其他数据库中添加 只读知识，以丰富搜索结果；也可以添加 --cascade 以从父目录中的 .kbdb 文件夹中提取内容：

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

每条搜索结果都包含一个 source_db 字段——即结果 来源的数据库根目录——可直接复制并粘贴到 --db 或 --other-db 中。

脚本编写： 添加 --format json 可获取 结构化 JSON 输出以供解析。在 CI 流水线中使用 --non-interactive 或设置 KBDB_NON_INTERACTIVE=1，可禁止显示提示。

4. 回溯上下文

kbdb recall <kbid> --depth 1

从搜索结果的 kbid 开始，逐步展开上下文：深度 0 返回章节 内容，深度 1 添加父文档和 反向引用，深度 2 添加同级章节和正向 引用，深度 3 则包含被引用章节的 完整文本。

---

知识库

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

• 导入 Markdown 和纯文本文件，并添加 标签和来源跟踪
• 智能更新 -- 重新学习文件时会取代 旧版本，而不是重复添加
• 历史记录 -- 被取代的章节会归档，而非 删除：kbdb history 可从任一端遍历链条， 旧的 kb-id 仍可解析
• 搜索 提供三种算法：关键词 （默认）、AI 相似度或混合（两者兼用）
• 自动回退 -- 如果精确查询没有结果， kbdb 会自动放宽匹配条件
• 召回 章节时提供渐进式上下文 -- 从快速摘要到完整的相关内容， 或在 --max-tokens 预算允许的范围内尽可能深入
• 衡量 检索效果是否理想 -- kbdb eval 会根据 你自己的数据集计算 Recall@k、MRR 和 nDCG@k，并在排名因变更而变差时以非零状态退出
• 邻域 -- kbdb neighbourhood 会说明某个章节 与哪些内容相关，以及如何相关：八种带类型的边， 其中七种是记录的事实，一种是推断得出的
• 整合 -- kbdb consolidate 会提出可合并为一体的 章节组。它只会提出建议； 由你编写合并内容并自行应用
• 导出 -- 为知识库创建快照 以便备份
• 验证 数据库完整性并清理 过时数据
• 重建 索引（出现问题时使用）

请参阅 知识库指南， 了解完整操作流程，包括导出和备份。

---

Agent 工具

将 kbdb 集成到 AI Agent 和自定义工具中。

MCP 快速入门（Claude CLI）：

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

请参阅 MCP 安装指南， 了解 Claude Code、VS Code 和 Claude Desktop 的 配置文件，以及故障排除方法。

• MCP 服务，包含 20 个工具——搜索、回忆、 学习、修订、缺口、矛盾、导出、 技能／Agent 搜索等
• 技能——存储可重复使用的提示词模板， 并支持填空式参数
• Agent——创建 AI Agent 配置， 将角色与技能组合起来
• 捕获策略——服务会在 MCP 握手期间告知 Agent 应存储哪些内容，因此无需针对每个宿主进行配置。 六项条款中有两项说明了不应存储哪些内容：聊天 摘要、猜测、机密，以及代码中已有的任何内容。kbdb 会提供策略，但无法强制 Agent 遵循策略
• 自动捕获——可以请求宿主自带的模型 挑选值得存储的知识。它需要 MCP sampling 能力，而 Claude Code 不会声明该能力， 因此自动捕获在其中不起作用。本列表中的 其他所有功能均不受影响——请参阅宿主支持
• 守护进程韧性——可配置请求 超时，并在守护进程重新生成后自动重试
• 工作进程守护进程生命周期管理—— 停止并重启后台进程
• 精细的 Deno 权限——守护进程 使用范围受限的权限运行，而非使用 --allow-all
• 路径限制——守护进程会拒绝 导出／导入中的路径遍历（..）

服务会告知 Agent 的内容。 initialize 响应中包含一个 instructions 字符串——这是每个合规的 MCP 宿主 无需任何设置即可接收的唯一通道。kbdb 用它来传达捕获策略：回答前先搜索；将 unanswered 判定视为需要调查的缺口，而不是猜测；存储需要付出实际努力才能找到的决策和更正；不要存储代码中已有的内容。相同的句子也会原样引用在 learn、revise 和 search 工具 描述中，而非改写，因此它们都有同一个 来源。

请参阅 Agent 工具指南， 了解 MCP 设置、技能、Agent 和库 API；请参阅 捕获策略， 了解六项条款的完整内容，以及为何只编写一次。

---

面向开发者

库 API

在 Node.js 或 Deno 项目中以编程方式使用 kbdb：

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。

开发环境设置

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

Docker

两个 Dockerfile，不能互换使用。

仓库根目录下的 Dockerfile 用于构建 MCP 服务——MCP 目录会构建这个文件；如果你想在容器中运行 kbdb，也应使用这个文件。请参阅 安装 MCP 服务， 了解宿主配置，以及为何需要使用命名卷而非绑定挂载。

Dockerfile.tooling 用于构建开发工具链 （Node.js 和 Deno），所有 make 目标都通过 docker-compose.yaml 使用该工具链：

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

运行 make benchmark，测量大规模场景下的搜索和重建延迟——结果会自动写入 docs/benchmark/benchmark.md。

请参阅 Makefile， 了解所有可用的构建目标。

贡献

1. Fork 仓库
2. 创建功能分支
3. 进行更改并添加测试
4. 运行 npm test 和 npm run lint
5. 提交合并请求

---

文档

• 使用 Claude Code 构建第二大脑 -- 权威设置指南：工作区布局、 正确的命令、MCP 连接配置
• CLI 安装指南 -- 前置条件、npm/JSR 安装、验证
• 知识库指南 -- 导入、搜索、回忆、导出
• Agent 工具指南 -- MCP、技能、Agent、库 API
• CLI 参考 -- 完整命令 列表及示例
• MCP 安装指南 -- Claude CLI、Claude Code、VS Code、Claude Desktop
• MCP 服务指南 -- 设置、工具、环境配置，以及服务在 initialize 时告知 Agent 的内容
• 宿主支持 -- 哪些 MCP 宿主会提供捕获策略并声明支持采样； 结论基于实际测量，而非假设
• 捕获策略 -- kbdb 告诉 Agent 应存储什么，以及为何 只声明一次
• 搜索与排序 -- 搜索的底层工作原理
• 存储架构 -- 文件格式、目录布局，以及保留历史记录的成本
• Deno 权限 -- kbdb 所需的权限标志及其原因
• 基准测试结果 -- 大规模场景下的搜索和重建延迟
• 了解扩展性 -- learn 的成本如何随语料库大小增长
• 矛盾信号 -- 基于 1128 对已标注样本校准近重复和矛盾 阈值
• 发行说明
• 架构概览

搜索引擎

存储、索引和排序由 @dikolab/vdb 提供；这是同一作者开发的 kbdb 关联项目。其文档深入介绍了 检索方面的内容：

• vdb 概览 -- 存储模型、分区、BM25F、向量搜索和混合搜索
• vdb 示例 -- 查询示例和排序行为

---

支持

kbdb 是免费的 AGPL 许可软件。如果它在你的 工作流中发挥了作用，你可以通过 PayPal 支持持续开发。

许可

本项目采用双重许可：

• 开源，遵循 GNU Affero 通用公共许可证第 3.0 版 (AGPL-3.0-only)
• 商业许可证，适用于闭源 或 SaaS 使用

<= 0.5.0 的版本仍采用 ISC 许可证。

详情和联系信息请参阅 LICENSING.md。

---