换一个 AI 就失忆?让四个 Agent 共用一份知识库
一句话读懂:换一个 AI 工具就要把背景和规范重讲一遍?根源是每个工具的记忆都是私有的。本文把记忆抽成三层:git 仓库存 Markdown 事实、两百行 C# 手写 stdio MCP 服务负责读写、一段全局协议约束调用时机,并给出四个工具的具体配置位置(含豆包工作的自定义连接器与仅本地模式限制)、WorkBuddy 信任开关、验证步骤、实测数据(169 条目单次检索 90 毫秒)与七个真踩过的坑,附可直接运行的示例仓库。
😩 01 换一个 AI,我就得从头讲一遍
我平时同时在用四个 AI 工具:TRAE 写前端和桌面端,Qoder 看后端仓库,WorkBuddy 处理零散脚本,豆包工作做跨工具的统筹——写文章、出图、跑本地连接器都在它上面。用久了发现一个很浪费的现象——同一件事,我要说四遍。
同一个代码规范,四个工具各讲一遍;上周在 A 工具里踩过的坑,这周在 B 工具里原样再踩一次;我刚跟 A 说清楚「这个项目的分页参数叫 page/pageSize」,切到 B,它照样给我写成 current/size。
原因不复杂:每个工具的记忆都是私有的。TRAE 写自己的项目记忆和会话流水,Qoder 写 MEMORY.md,WorkBuddy 又是另一套格式,豆包工作则把记忆绑在账号侧,彼此不可见。切换工具的那一刻,上一份上下文就断了。
于是我决定把「记忆」从工具里抽出来:不再指望每个 AI 自己记事,而是让它们读写同一份外部知识库。
🏗️ 02 结论先行:三层,缺一层就退化
这套东西最终落成了三层结构。

| 层 | 负责什么 | 具体是什么 |
|---|---|---|
| 数据层 | 事实存在哪 | 一个 git 仓库,全部 Markdown + front-matter |
| 接入层 | 怎么读写 | 一个 stdio MCP 服务,提供 5 个工具 |
| 规则层 | 什么时候读写 | 各工具全局规则里的一段协议 |
一句话分工:数据层管「是什么」,接入层管「怎么读写」,规则层管「什么时候读写」。
三者缺一个就会退化。只有数据层,AI 不知道它存在;只有接入层,AI 会乱写;只有规则层,AI 会说「好的我记住了」,然后记在它自己的私有记忆里。
📁 03 数据层:为什么必须是 Markdown + git
选 Markdown 不是为了好看,是三个实际需求叠加的结果:
- 人和 AI 都要能改。出问题时我能直接打开文件看、直接改,不需要先写代码解析。
- 要能当 Obsidian vault。把 AI 知识库当个人笔记库用,人和 AI 共用同一份文件,这是最省事的方案。
- 要能回滚。AI 改坏一条结论的风险是真实存在的,
git diff和git checkout是最便宜的保险。
目录按「知识的使用范围」切,不按技术栈切:
kb/
├── INDEX.md 唯一入口,≤200 行,只放 id + 摘要 + 标签
├── profile/ 跨项目画像:身份、代码规范、本机环境
├── domain/ 跨项目领域知识:一个主题一个 md
├── projects/<slug>/ 一个项目一个文件夹,主文件 project.md
├── rules/ 全局协议的单一真源,各工具同步这同一段文本
└── archive/<YYYY-MM>/ 每日流水,复用 2 次以上再晋升
每个条目自带 front-matter:
---
id: projects/demo-app/project
title: demo-app 项目长期约定
tags: [Vue3, .NET, 接口约定]
scope: project
updated: 2026-11-17
source: TRAE-CN
---
关键在于 INDEX.md 是唯一入口且限死 200 行。AI 开工先读它,判断有没有相关条目,再按 id 读正文。这一步决定了 token 成本和准确率——如果允许「整库加载」,库越大越慢、越容易被无关内容带偏。
🔌 04 接入层:两百行 C# 手写一个 MCP 服务
有人会问:既然是普通文件,为什么不让 AI 直接读写文件夹?
可以,但会丢三样东西:统一的写入格式(front-matter 靠 AI 手写迟早写歪)、统一的检索逻辑、以及「写完自动提交」。用 MCP 是因为它是宿主应用都认的标准协议,一次实现,四个工具都能接。
服务本身很薄:stdio 收 JSON-RPC,分发到 5 个工具。主循环不到 20 行:
string? line;
while ((line = stdin.ReadLine()) is not null)
{
if (string.IsNullOrWhiteSpace(line)) continue;
var response = HandleRequest(line, store);
if (response is null) continue; // 通知类请求不回包
stdout.WriteLine(response.ToJsonString(ResponseOptions));
stdout.Flush();
}
检索没有上向量库,就是逐文件扫描加加权计分——标题命中权重最高,其次标签,最后正文:
// 分项计分:标题权重最高,其次标签,正文最低
var score = 0;
foreach (var token in tokens)
{
var titleHits = CountHits(title, token);
var tagHits = tags.Any(x => x.Contains(token, StringComparison.OrdinalIgnoreCase)) ? 1 : 0;
var bodyHits = CountHits(body, token);
if (titleHits + tagHits + bodyHits == 0) continue;
score += Math.Min(titleHits, 3) * 5 + tagHits * 3 + Math.Min(bodyHits, 5);
}
五个工具覆盖了完整闭环:
| 工具 | 用途 |
|---|---|
kb_index |
读索引,开工前先判断有没有现成结论 |
kb_search |
关键词检索,返回 id、得分和命中片段 |
kb_get |
按 id 读全文 |
kb_upsert |
写入条目,自动补 front-matter、登记索引、git commit |
kb_log |
追加当日流水 |
真正省事的不是检索,是 kb_upsert 里这两行:
RegisterInIndex(id, title, tags, updated); // 索引与内容不脱节
KbGit.Commit(_root, [path, indexPath], $"kb: upsert {id}");
写知识这件事,最怕的不是写错,是索引和内容慢慢对不上——条目加了但索引没加,三个月后没人知道库里有什么。自动登记把它变成不可能发生的错误。
一次任务的读写时序大致是这样:

📜 05 规则层:协议写多细,AI 才会真的用
服务装好之后,你会发现 AI 根本不主动用——它不知道这个工具该在什么时候调用。所以每个工具的全局规则里都要贴同一段协议:
知识库协议
1. 唯一真源:E:\KnowledgeBase\kb(git 仓库),INDEX.md 是入口且 ≤200 行
2. 开工前先读 INDEX.md,按标签定位条目再读正文,禁止整库加载
3. 涉及历史决策/约定/踩坑时调用 kb_search,不凭记忆猜
4. 收工前用 kb_upsert 写回稳定结论,过程性结论用 kb_log
5. 各工具自带 memory 仅作本地缓存,事实以知识库为准
但协议文本本身别写成四份。我把它落在 rules/global-protocol.md 里,各工具的全局规则只同步这同一段:改一处、逐端覆盖。否则改了一处忘了另一处,某端会按旧规范悄悄执行,而且不会自报——这种错误你不会收到任何报错信号。
三个细节决定它有没有用:
- 必须写绝对路径。写「知识库目录」等于没写,AI 会自己猜。
- 必须写明时机。「可用工具」和「什么时候用」是两件事,前者 MCP 已经解决,后者只能靠规则。
- 必须写冲突规则。否则 AI 会拿私有记忆跟知识库打架,你永远不知道它这次信的是哪份。
⏱️ 06 实测:169 个条目,单次检索 90 毫秒
有人会担心「逐文件扫描」的性能。本机实测(Windows、.NET 10、169 个 Markdown 条目、取前 5 条):
| 指标 | 数值 |
|---|---|
| 首次调用(含进程冷启动) | 152 ms |
| 稳定后单次耗时 | 82 ~ 89 ms |
| 10 次平均 | 90.3 ms |

这个量级对「一次对话调用两三次」的场景完全够用。刻意没上向量检索,原因是规模不匹配:几百到几千条时,关键词加权的效果不比向量差,但可解释性好得多——得分怎么来的我能算清楚,召回错了也能直接调权重。
升级路径也想好了,但不提前做:条目过千换 SQLite FTS5(trigram 分词),再往后才考虑本地 embedding。一步跳到向量是把简单问题复杂化。
🕳️ 07 七个真踩过的坑

1. stdout 被日志污染。 MCP 的 stdout 只能输出协议报文,任何一行 Console.WriteLine 调试都会让宿主解析失败,表现是「服务连上了但工具全挂」。所有诊断信息必须写文件或 stderr。
2. 中文返回被转义成 \uXXXX。 默认序列化会把整段中文变成转义码,报文体积翻几倍还难读。加上 JavaScriptEncoder.UnsafeRelaxedJsonEscaping 才是正常输出。
3. 通知类请求回了包。 notifications/* 不需要响应,回一个空结果也算协议违规。判断方法名以 notifications/ 开头直接 return null 即可。
4. id 越界写入。 kb_upsert 的 id 是相对路径,如果不校验,../ 能把文件写到知识库外面。解析完路径必须确认仍在根目录内。
5. 用目录 junction 合并各工具记忆。 想过偷懒:把四个工具的记忆目录链接到一起。结论是不可行——写入格式不同(jsonl 流水、MEMORY.md、话题 md),链接同一目录会互相覆盖。junction 只适合一次性导入存量。
6. 索引和内容脱节。 前面说过,靠自动登记解决。这条是使用三个月后最值钱的一条。
7. 豆包工作的连接器只认本地电脑模式。 它在设置里能正常添加、显示「连接器已安装」,但云端任务里调用一律失败——自定义连接器只支持本地电脑。更绕的是它跑在虚拟桌面里:Windows 账户没设密码时,虚拟桌面初始化直接失败(NO_SESSION),而且虚拟桌面的登录态与主桌面独立,要单独登录一次。三条叠在一起,现象很像「服务坏了」,其实服务一直好好的。
🧹 08 治理:让知识库半年后还能用
知识库最大的敌人不是写不进去,是变成垃圾场。我给自己定了六条:
- 单写通道:只经 MCP 写入,不手改,保证每次变更都有提交记录。
- 晋升机制:
archive/里的流水被复用 2 次以上,才提升到projects/或domain/。 - 索引预算:
INDEX.md不超过 200 行,超了按 scope 拆分。 - 过期降权:
updated超过 90 天的决策标 stale。 - 人工层共存:Obsidian 打开同一目录当 vault,人和 AI 共用一份文件。
- 敏感信息不入库:令牌、客户隐私写库前先扫描。
第 2 条是最反直觉也最有用的。如果每次对话都往库里塞一条,三个月后检索全是噪音;只有被反复复用的东西才值得晋升成正式条目。
🚧 09 这套东西不适合谁
说清楚边界,比只讲好处更有用:
- 只用一个大模型、一个工具的人:直接用工具自带的记忆就行,别折腾。
- 期待「AI 全自动维护知识库」的人:做不到。它仍然需要你在收工时明确说一句「把结论写回去」,协议只能降低遗忘率,不能消除。
- 需要团队协作的场景:这套是单人单机方案。多人要加权限、冲突合并和评审流程,成本是另一个量级。
还有一条必须承认:各工具自带的记忆不会消失,它们会继续写。我们能做的只是把它降级成「本地缓存」,用冲突规则让知识库当唯一事实源。
🛠️ 10 从零配起来:六步
整套东西我放成了可运行的最小示例,两个平台内容一致:
- GitHub:
https://github.com/lixiaoliyubo/kb-mcp-demo - Gitee:
https://gitee.com/lixiaoliyubo/kb-mcp-demo
第 1 步:编译服务
git clone https://gitee.com/lixiaoliyubo/kb-mcp-demo.git
cd kb-mcp-demo
dotnet build .\kb-server\KbMcp.csproj -c Release
产物是 kb-server\bin\Release\net10.0\KbMcp.dll。零第三方依赖,只需要 .NET 10 SDK(dotnet --version 能看到 10.x 就行)。
第 2 步:先确认两个路径
| 变量 | 指向 | 判断标准 |
|---|---|---|
| dll 路径 | ...\bin\Release\net10.0\KbMcp.dll |
文件真实存在 |
KB_ROOT |
知识库根目录 | 目录下直接有 INDEX.md |
以仓库里的示例为例:
dll D:\Projects\kb-mcp-demo\kb-server\bin\Release\net10.0\KbMcp.dll
KB_ROOT D:\Projects\kb-mcp-demo\kb-demo
两个路径都必须是绝对路径。别用 ~ 或相对路径——MCP 进程的工作目录由宿主应用决定,跟你想的不一样。这也是我见过最多的一类配置失败。
第 3 步:把服务加到各工具里
配置永远是三要素:命令、参数、环境变量。
{
"mcpServers": {
"kb": {
"command": "dotnet",
"args": ["D:\\Projects\\kb-mcp-demo\\kb-server\\bin\\Release\\net10.0\\KbMcp.dll"],
"env": { "KB_ROOT": "D:\\Projects\\kb-mcp-demo\\kb-demo" }
}
}
}
两个容易翻车的点:
- JSON 里反斜杠要写两个。
D:\Projects会被当成非法转义,必须写成D:\\Projects。 command找不到就换成绝对路径。一般装在C:\Program Files\dotnet\dotnet.exe;不确定先在终端跑where.exe dotnet。
「去设置里找找」是最容易卡住的一步,所以直接给位置:
| 工具 | 配置位置 |
|---|---|
| 豆包工作 | 左侧「插件 · 技能 · 伙伴」→ 插件页右上「+ 添加」→ 新建自定义连接器(stdio):命令填 KbMcp.exe 绝对路径、参数留空、环境变量 KB_ROOT。仅本地电脑模式生效,配置只存账号侧,本地没有配置文件 |
| WorkBuddy | C:\Users\<用户名>\.workbuddy\mcp.json,直接用文本编辑器改 |
| Qoder CN | C:\Users\<用户名>\.qoder-cn\settings.json;同目录的 mcp-router.json 是运行时文件,不要手改 |
| TRAE CN | 设置 → MCP → 添加自定义 MCP(stdio)。配置存在应用数据库 state.vscdb 里,只能走 UI,不要手工改库;command 必须写绝对路径 |
| Claude Desktop | %APPDATA%\Claude\claude_desktop_config.json |
| Cursor | %USERPROFILE%\.cursor\mcp.json |
改完保存,重启工具才会加载。核心原则:多个工具填的是同一份配置——同一个 dll、同一个 KB_ROOT,否则又退化成各存各的。
第 4 步:WorkBuddy 还要单独开「信任」
这一步是 WorkBuddy 特有的,也是我踩过的一个坑:它把「注册」和「授权」拆成了两个文件。
mcp.json负责注册服务;- 同目录的
mcp-approvals.json负责记录你允不允许它被调用,内容长这样:
{
"edea4489bb92ef30ff0e8fd85009886d71f644dce1ef8e2cf5f71a3d5d2f55cf::kb": 1794846510789
}
键是「配置哈希::服务名」,值是授权的时间戳。
只改 mcp.json 而不开信任,现象很有迷惑性:MCP 列表里能看到 kb,工具也能列出来,但一调用就被拒绝。看起来像服务有问题,其实是没授权。
处理办法:在 WorkBuddy 的 MCP 设置里对 kb 这一项点「信任 / 允许」,或者在首次调用时按弹窗确认,之后 mcp-approvals.json 会多出一条记录。
还有个后续影响:如果你改了 command、args 或 env,配置哈希会变,旧的信任记录可能对不上,需要重新确认一次。遇到「昨天还能用,今天突然调不动」,先回头看这个文件。
第 5 步:写全局规则
MCP 装好只代表「有能力」,还得告诉 AI「什么时候用」。把这段贴进每个工具的全局规则:
知识库协议
1. 唯一真源:D:\Projects\kb-mcp-demo\kb-demo(git 仓库),INDEX.md 是入口
2. 开工前先 kb_index 读索引,按标签定位条目再 kb_get 读正文,禁止整库加载
3. 涉及历史决策、约定、踩坑时先 kb_search,不凭记忆猜
4. 收工前用 kb_upsert 写回稳定结论,过程性结论用 kb_log
5. 各工具自带 memory 只当本地缓存,与知识库冲突时以知识库为准
规则放在哪也说清楚,不然它大概率躺在某个对话框里:
| 工具 | 全局规则位置 |
|---|---|
| TRAE CN | C:\Users\<用户名>\.trae-cn\user_rules\ 下的 md 文件 |
| WorkBuddy | C:\Users\<用户名>\.workbuddy\USER.md |
| 豆包工作 | 没有全局规则文件:用长期偏好(每次会话自动注入)承载「先读索引、以库为准、收工写回」,再用一个技能承载「怎么读、怎么执行」的细节 |
| 其他工具 | 设置里的「全局指令 / 自定义规则 / System Prompt」入口 |
第 2 条和第 4 条最容易被漏。只写「你可以使用知识库」,AI 大概率不用;写清「开工先读、收工写回」,它才会形成习惯。
第 6 步:验证,别只看「保存成功」
直接在对话框里说:
读一下知识库索引
预期返回 INDEX.md 全文,能看到 id、摘要、标签组成的表格。接着说:
在知识库里搜一下 MCP 的 stdio 约束
预期返回 1~5 条命中,带 id、得分和命中片段。两条都通,说明读取链路没问题。
再验写入:
把「对外接口统一返回 code/message/data」写进知识库,挂到 projects/demo-app 下
预期返回「已写入条目」,并且在 KB_ROOT 下执行 git log -1 能看到一条 kb: upsert ... 的提交。
配不通时先查这五项
| 现象 | 大概率原因 | 处理 |
|---|---|---|
| 工具列表里没有 kb | 配置没保存 / 没重启 | 重启宿主,确认改的是它真正加载的那个配置文件 |
| 工具可见但一调用就被拒 | WorkBuddy 没开信任 | 在 MCP 设置里点「信任」,确认 mcp-approvals.json 有对应记录 |
| 报「知识库根目录不存在」 | KB_ROOT 没设或写错 |
确认该目录下直接有 INDEX.md |
| 报「未找到 INDEX.md」 | KB_ROOT 指到了 dll 目录 |
改成知识库根目录,不是 bin |
| 返回乱码 / 宿主提示解析失败 | 改代码时往 stdout 打了日志 | 调试输出一律改走日志文件 |
写入成功但 git log 没记录 |
KB_ROOT 不是 git 仓库根目录 |
在 KB_ROOT 里 git init 并做一次初始提交 |
最后一条不算故障:KB_ROOT 不是 git 仓库也能正常读写,只是丢了版本记录——不致命,但等于放弃了回滚能力。
✅ 11 最后
最后说一句我的实际感受:这套东西带来的最大变化不是「AI 更聪明了」,而是我不用再维护三份口径。省下来的不是打字时间,是每次切换工具那几分钟的重新进入状态。

浙公网安备 33010602011771号