内容
kb-graph
**一种自我维护的记忆，适用于容易遗AI智能体。**
kb您运行的智能体——ClaudeCodex、GeminiMCP的智能提供一个共享的大大脑可以不断积累知识记忆系统不同的是，kb-graph通过一个循环来实现智能体的会话记录晚自动收获**成教训和决策；流的**被整理，以便于查询；**每周的综合**矛盾；并且任何内容之前，部分推送到每个**中。 您任何内容，您的也不需要记住搜索。
-graph 最初是-base-server](https://illynikes2/knowledge-base-server)的一个 Shawn Daniel 创建——[Memstalker](https://mem.com) 的引擎后在会话记录流状态笔记和方面进行了大幅重建 快速入门
``` clone https://github.com/uttambharadb-graph.git
cd
npm install
/kb.js setup
```
设置会将MCP您的智能体中Claude Code钩子（在会话开始时进行知识库简介，在每个提示上提供知识提示），安排夜间收获/重新索引/每周综合作业，安装捆绑的 `/debrief` 和 `kb-workflow` 技能，并在您没有的情况下创建 `~/kb-vault` 的markdown保险Obsidian 是一个可选器——保险库markdown。
打开一个新的Cl：您应该会第一个 **知识库。
如果您正在为进行培训？请发送到 [docs/ING.md](docsBOARDING.md)。
---
AI智能体状态的。每个会话都从零开始：重新解释重新发现上个月您三个小时的陷阱，观看第二个智能体重复第一个智能体的错误。
大多数记忆系统通过纪律来解决这个问题——*记住保存笔记，记住搜索它们*。纪律在截止日期前无法生存。kb-graph 建立在相反的假设上：**循环必须在没有人记得运行时运行**。捕获是由调度作业读取您已经生成的会话记录。检索是一个钩子，在您的提示得到回答之前触发。人类唯一的任务是偶尔阅读系统编写的内容。
## 循环
### 1. 推送，而不是拉取
两个Claude Code钩子（由 `` 安装）意味着您的智能体永远不会从冷：
- **会话开始 - 简介。**新会话都以知识库简介开始：活动工作流（带有指向其状态笔记的指针），最近捕获的知识，以及一个健康心跳，以便您知道幕后循环实际上正在运行。
- **每个提示 - 提示。** `UserPromptSubmit` 钩子将您的提示与知识库匹配，并注入提示行：
```
知识库提示：知识库中有与此提示相关的条目：
#412 "Pydantic 设置拒绝来自 .env 的额外环境变量"（经验教训）；
#367 "为什么我们将身份验证移到每个请求的令牌"（决策）。
在从头开始探索之前，请使用 kb_read(id) 检查它们。
```
智能体会读取两条简短的笔记，而不是从代码库中重新推导出上下文。
拉取仍然有效 - `kb_search`（BM25），`kb_search_smart`（混合关键词 + 语义），`kb_context`（高效简介）- 当排名丢失时，保险库是磁盘上的纯markdown：直接grep它。
### 2. 不依赖于自律的捕获
- **夜间收获（03:30）。** 调度作业读取智能体的会话记录，并提取持久的部分 - 事实，经验教训，决策，修复 - 作为结构化笔记，在知识库已经知道的内容中重复数据删除（`kb_check_duplicate` 在每次写入之前运行）。您在凌晨2点调试了一些复杂的问题，并没有告诉任何人？收获已经捕获了它。
- **刻意捕捉 - `/debrief`.** 在一个重要的会话结束时，运行捆绑的 `/debrief` 技能（由设置安装到 `~/.claude/skills/`）：它扫描对话中的经验教训，决策，工作流程和状态变化，将每个与知识库已经知道的内容进行比较，并为您批准列表后写入幸存者。刻意捕捉质量更高 - 更好的标题，更丰富的上下文，立即可用；夜间收获是您没有刻意捕捉的所有内容的备份。配套的 `kb-workflow` 技能教导智能体在会话中间使用检索-然后-捕捉模式，`kb_capture_session` / `kb_capture_fix` / `kb_write` 是两个底层工具。
- **实体事实。** 除了散文笔记之外，一个轻量级事实存储器跟踪带有有效性窗口的 `(subject, predicate, object)` 三元组：`kb_fact_add`，`kb_fact_query`，`kb_fact_timeline`（“我们的身份验证方法如何演变？”），`kb_fact_invalidate`（更新而不删除历史）。
### 3. 状态笔记，而不是过时的会话
会话笔记会堆积起来；关于工作流的真相会分散在二十个会话中。每天晚上，整合过程 **将最近的会话笔记折叠成每个工作流的一个可变状态笔记**，并将吸收的会话重新归类为 `archive`（仍然可搜索，但不再冒充当前）。询问“身份验证工作会读取一个截至的当前笔记 - 而不是一个考古挖掘。
### 4. 每周综合（星期日 04:00）
一个综合作业读取一周的知识，并编写一个好的技术负责人会注意到的内容：重复出现的主题，**矛盾**（两个笔记对同一个系统声称不同的内容），和合并候选者（值得合并的近似重复集群）。知识库不仅仅是积累 - 它会与自己争论，并标记出它不同意的地方。它还会列出本周最强的 **跨领域隧道**（参见 [隧道](#tunnels)）。
## 使用 kb-graph 的一天
- **9:00** - 您打开Claude Code。简介列出了您活跃的工作流，昨晚的收获运行正常。
- **9:05** - 您询问一个登录错误。知识库提示指向一个三周前的经验教训：这个确切的故障是一个过时的凭证缓存。节省了20分钟。
- **11:30** - 您的智能体修复了一些微妙的问题，并在退出时使用 `kb_capture_fix` 捕获了它。
- **03:30** - 收获读取了今天的会话记录，提取了两个经验教训和一个决策，您没有明确保存它们，今天的会话被折叠成工作流的状态笔记。
- **星期日 04:00** - 综合发现，星期二的笔记与您在三月份做出的关于重试行为的决策相矛盾。您用一行解决了它。
您运行的每个智能体都共享所有这些内容。凌晨2点学到的内容，Codex在上午9点就知道了。
## 隧道
上述所有内容都按领域归档。隧道在领域之间行走。询问 `kb_tunnels` 关于一个标签，它会根据 **提升**（共同出现的加权与其单独出现的频率）对相邻的领域进行排名，这样一个万能标签就不会因为无处不在而浮到顶部。询问两个标签，它会返回带有 **两个** 标签的笔记 +存储实体 **在 领域中被提及 - 共享服务，人们和系统，悄悄地连接您以为是独立工作领域。标签首先规范化 - 小写每次写入时重复数据删除，并使用 ` <aliascanonical>` 将同 `auth` 和` 合并到 - 因此图拼写碎片周综合列出了最强的隧道；`kb 报告原始并建议添加值得添加的别名。
## 设计原则
- **文件优先。** 每个笔记都是带有前置信息的纯markdown，存储在您拥有的目录中。Obsidian可以漂亮地渲染它，但它是可选的。当搜索排名失败时，`grep` 是备用方案 - 智能体可以始终检查原始存储。
- **读取路径中没有LLM。** 检索是SQLite FTS5（BM25）（allLM-L6-v2，在您的机器查询时融合。LLM调用在花费 - 分类，提取，综合 - 在那里造成伤害。
- **自我维护，并且对此诚实 嵌入，收获，整合和综合都按。简介带有健康心跳；如果循环停止会在下一个会话开始时看到 ⚠，而不是几个月后发现无声的腐烂。
- **没有外部服务。** SQLite，本地嵌入，您的文件系统。除非您自己暴露REST API，否则没有任何内容离开您的## 架构
```
+----------------------------+
AI 智能体 |
| Claude Code | Codex |
| Gemini 任意MCP/HTTP|
+-------------+-------------- 钩子：简介 + 提示 | stdio/HTTP）· REST /api/v1/
+-------------+--------------+
| 知识库服务器 |
| Express :3838 |
+-------------+--------------+
|
+-----------------------+----------------------+
| | |
+--------+--------+ +---------+---------+ +--------+--------+
| SQLite + FTS5 | | 本地嵌入 | | Markdown 保险库 |
| 文档/事实 | | all-MiniLM-L6-v2 | | （Obsidian- |
| 文档链接 | | 混合排名 | | 兼容） |
+-----------------+ +-------------------+ +-----------------+
调度作业（由 kb setup 安装）：
收获 夜间 03:30 — 会话记录提取 + 状态笔记折叠
重新索引 每 5 分钟 — 保险库 → 索引 + 嵌入
综合 星期日 04:00 — 主题，矛盾，合并候选者
```
数据目录：`~/.knowledge-base/`（`kb.db`，已摄入的文件副本，配置）。
---
## 详细设置
### 先决条件
- Node.js >= 18.0.0
- 就这样。无需外部数据库，无需Docker，无需云依赖。
### 安装
```bash
git clone https://github.com/uttambharadwaj/kb-graph.git
cd kb-graph
npm install
npm link # 可选：使 `kb` 在 PATH 上可用
```
### 首次运行（交互式向导）
```bash
kb setup
```
向导检测您的环境，询问您使用的AI智能体，编写 `.env`，注册MCP，安装钩子和调度作业，并创建您的保险库。大约 60 秒。
代理驱动的安装（无提示）：
```bash
kb setup --auto --password=yourpass --vault=~/kb-vault --agents=claude,codex
```
重新运行设置是安全的：现有的机密（密码，身份验证机密，API密钥）将被保留，并且钩子不会重复。注意，`.env` 是从其模板重写的 - 如果您手动添加了自定义变量，请先备份它们。
### 手动部分
```bash
KB_PASSWORD=yourpassword kb start # 仪表盘 + REST API 在 :3838
kb register # 仅MCP注册
kb ingest ~/kb-vault # 摄入目录
kb search "docker networking" # 从终端搜索
kb status # 统计和服务器状态
```
---
## MCP 工具
所有 24 个核心工具都可以通过stdio和HTTP提供：
| 工具 | 描述 |
|------|-------------|
| `kb_search` | 全文搜索，BM25排名，突出显示片段 |
| `kb_search_smart` | 混合关键词 + 语义搜索，用于概念查询 |
| `kb_context` | 高效简介 - 仅限摘要；在使用 `kb_read` 之前使用 |
| `kb_read` | 按ID读取文档（返回 `related:` 邻域） |
| `kb_list` | 按类型或标签列出文档 |
| `kb_tunnels` | 跨领域桥梁：一个标签的相邻领域，或两个标签之间的共享笔记 + 实体 |
| `kb_write` | 向保险库写入笔记 |
| `kb_ingest` | 摄入原始文本 |
| `kb_check_duplicate` | 写入前的相似性检查 - 防止近似重复的笔记 |
| `kb_classify` | 自动分类未处理的笔记（类型，标签，摘要） |
| `kb_extract` | 从原始文本或会话记录中提取结构化事实/经验教训 |
| `kb_promote` | 将原始来源提升为结构化知识 |
| `kb_synthesize` | 最近知识的跨源综合 |
| `kb_fact_add` | 添加实体事实（主题/谓词/对象 + 有效性） |
| `kb_fact_query` | 查询关于实体的事实 |
| `kb_fact_timeline` | 实体事实如何随时间演变 |
| `kb_fact_invalidate` | 更新事实，保留历史 |
| `kb_capture_session` | 记录编码/调试会话 |
| `kb_capture_fix` | 记录错误修复：症状，原因，解决方法 |
| `kb_capture_web` | 捕获网页文章 |
| `kb_capture_youtube` | 捕获YouTube会话记录 |
| `kb_wakeup` | 会话简介（会话启动钩子调用） |
| `kb_vault_status` | 保险库索引统计 |
| `kb_safety_check` | 审查对KB历史的破坏性操作 |
随附的本地消息总线用于跨代理协调（`bus_send`，`bus_read`，`bus_status`等）- 参见 [docs/message-bus.md](docs/message-bus.md)。
## CLI 命令
```
kb setup 设置向导（--auto 适用于代理模式）
kb start / stop 仪表盘 + REST API 服务器（默认 :3838）
kb mcp MCP stdio 服务器（您的代理连接到的）
kb register 将MCP注册到Claude Code / Codex / Gemini
kb harvest 现在运行会话记录收获（通常是夜间）
kb consolidate-state 将会话笔记折叠到工作流状态笔记中
kb vault reindex 重新索引保险库（包括嵌入）
kb ingest <path> 摄入文件或目录
kb search <query> 从终端搜索
kb classify 自动分类未处理的保险库笔记
kb summarize 为未总结的笔记生成摘要
kb entity-merge 合并事实存储中的两个实体别名
kb tags 标签报告；'tags alias <a> <b>' / 'tags aliases' 管理别名
kb status 统计和服务器状态
```
---
## 多智能体设置
### Claude Code, Codex, Gemini (MCP)
```bash
kb register # 写入 ~/.claude.json, ~/.codex/mcp.json, ~/.gemini/mcp.json
```
其他MCP客户端 - 将其指向stdio传输：
```json
{
"mcpServers": {
"knowledge-base": {
"command": "node",
"args": ["/path/to/kb-graph/bin/kb.js", "mcp"]
}
}
}
```
### ChatGPT 和远程智能体（REST）
1. 从服务器的 `/openapi.json` 导入OpenAPI规范
2. 使用 `X-API-Key` 头进行身份验证（密钥存储在 `.env` 中）
端点在 `/api/v1/` 下：`search`，`search/smart`，`context`，`documents`，`ingest`，`capture/session`，`capture/fix`，`capture/web`。
所有智能体共享一个大脑：一个智能体在会话中学习的内容，其他智能体会。
---
##
| 变量需 | 默认值 |
|----------|-------------|
| `` | 是（） | —仪表盘登录密码 `KB_PORT` | 否 | | HTTP服务器端口 `OBSIDAULT_PATH` | — | 路径（任意） |
|UDE_PATH` |claude` 在PATH上 | Claude文件，用于收获/| `CLASS` | 否 | claude-haiku-4-202510 写入时模型 |
| `_KEY_CLA / `_OPENAI `_GEMINI 否 | — | 远程REST访问的API密钥 |
| `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` | 否 | — | 远程访问的OAuth |
| `KB_TICKET_REGEX` | 否 | `pf-(\d+)` | 工作流自动绑定：识别目录/分支名称中的票证ID。完整匹配（小写）成为名称 |
服务运行
`` 会自动作业（macOSd，Linux用户计时将仪表盘作为Linux使用 `kb` 或中选择“systemd”。日志： -u kbf`（journalctl -- kb-har 或 `/tmp-*.logOS上（。
## 工作流模板
`docs/workflow包含使用此系统构建的操作合同 - `CLAUDE.md.template`，`AGENTS.md.template` 和 `SELF.md`（完整方法论）。将您的项目中并自定义：它们告诉体何时搜索知识库，何时捕获的工作原理。
---
## 血统谢
存储引擎、仪表盘、REST和设置向导来自 [knowledge-basehttps://github.com/willynikes2/-server) 由 [Shawn Daniel](.com/willynikes2) 运行托管的 [Memstalker](memstalker.com同一基础 -一个托管那里看看。这个会话记录状态整合、实体线、每周推送-检索等方面重建层，并且是由它体构建的。
*"你必须个应用进行100照，才能对进行修改10次。* — Shawn Daniel
线图
- [ ] 检索排名（事实存储实体作为- [ ] 双时间事实跟踪“何时停止为真时得知”
- [颖性门控写入：LL前的嵌入预过滤
## 许可
MIT - 参见 [LICENSE](LICENSE)。版权归 Shawn Daniel 和 Uttam Bharadwaj 所有。
