基于MCP协议构建AI知识库：解决会话失忆，实现知识持久化

1. 项目概述让AI拥有自己的“亚历山大图书馆”如果你和我一样长期与Claude Code、Cursor这类AI编程助手打交道一定会遇到一个核心痛点会话失忆。每次开启一个新对话AI助手就像一张白纸它对你项目的历史、架构决策、踩过的坑一无所知。你不得不反复粘贴上下文或者手动翻阅之前的聊天记录效率大打折扣。更麻烦的是那些在对话中产生的宝贵知识——比如解决某个诡异Bug的步骤、对某个第三方库的深度评测、临时编写的工具函数——往往散落在各个会话里难以沉淀和复用。Alexandria这个项目就是为了解决这个问题而生的。它的名字灵感来源于古埃及的亚历山大图书馆旨在为你的AI助手建造一个私人的、可搜索、可维护、可跨会话复用的知识库。简单说它是一套“基础设施”让你的AI助手Agent能够自己阅读、更新、整理和扩展一个属于它的维基Wiki。这不仅仅是静态的文件存储而是一个活跃的、由AI参与治理的知识生态系统。项目的核心设计非常巧妙它基于MCPModel Context Protocol协议构建。MCP你可以理解为AI世界的“USB标准”它定义了一套工具Tools和资源Resources的暴露方式让不同的AI客户端如Claude Desktop、Cursor都能以统一的方式调用后端能力。Alexandria就是一个MCP服务器它提供了一系列操作知识库的工具。同时它还配套了便携式的SKILL.md工作流这些工作流像是给AI助手的“操作手册”告诉它“在什么情况下应该使用Alexandria的哪个工具”。所以Alexandria的完整价值链条是便携技能SKILL.md引导AI助手 - AI助手通过MCP协议调用 - Alexandria服务器执行具体文件操作 - 更新并维护一个结构化的知识库 - 知识库在下一次会话中通过MCP指令或文件直接被AI助手读取。这个闭环让AI从被动的信息接收者变成了知识的主动管理者和利用者。2. 核心架构与设计哲学2.1 MCP工具与SKILL.md的职责分离这是Alexandria设计中最精妙的一点它清晰地划分了“做什么”和“何时做”。MCP工具src/tools/是“做什么”的具体实现。它们是纯粹的能力提供者与宿主Host即Claude Desktop等客户端无关。例如search.ts: 在知识库中执行搜索。index_build.ts: 重建搜索索引。scaffold.ts: 初始化一个新的知识库。这些工具通过MCP服务器暴露为标准的API任何兼容MCP的客户端都能调用。它们只关心文件系统的增删改查和算法逻辑不包含任何业务逻辑或决策。SKILL.md工作流.agents/skills/则是“何时做”和“如何做”的决策指南。它们是一份份用自然语言主要是Markdown写给AI助手看的“任务清单”或“触发器描述”。例如wiki-ingest/SKILL.md里可能会写“当用户提到‘把刚才讨论的解决方案保存下来’或会话即将结束时你应该调用extract_session工具来获取归档提示然后根据提示更新wiki。”这种分离带来了巨大的灵活性可移植性SKILL.md是纯文本文件你可以轻松地将它们复制或链接到任何AI助手支持的技能目录中如~/.agents/skills/无需安装插件。宿主无关性无论你使用Codex、Claude Desktop还是其他支持MCP和技能系统的客户端只要它能读取SKILL.md并调用MCP工具Alexandria就能工作。易于定制你可以像编辑文档一样修改SKILL.md调整AI助手的行为而不需要改动任何TypeScript代码。2.2 知识库的标准化结构Alexandria对知识库的目录结构有明确的约定这保证了工具行为的可预测性和知识的一致性。一个初始化后的知识库根目录如下my-project-wiki/ ├── .alexandria.json # 配置文件记录wiki元数据 ├── index.md # 人类可读的目录主页 ├── log.md # 按时间顺序的记录用于追溯知识演变过程 ├── CLAUDE.md # 给Claude的专用上下文提示可适配其他AI ├── AGENTS.md # 项目级的Agent指引文件 ├── raw/ # 原始材料暂存区 │ └── assets/ # 图片等二进制资源 ├── wiki/ # 核心知识存放区按主题分文件夹 │ ├── backend/ │ ├── frontend/ │ └── deployment/ └── search-index.json # 供搜索工具使用的预计算索引非人工编辑这个结构体现了“收-纳-用”的流程raw/是收件箱存放尚未整理的对话片段、代码块、错误信息。wiki/是归档库经过整理的结构化知识按主题存放。index.md和search-index.json是检索入口帮助AI和人类快速定位知识。log.md是审计日志记录每一次重要的知识增删改方便回溯。实操心得目录结构的必要性很多开发者一开始会觉得这种固定结构有点死板。但实际用下来会发现正是这种一致性让AI助手能可靠地执行“把X内容存到Y主题下”这样的操作。它消除了歧义。你可以把wiki/下的子目录设计成对你项目最有意义的分类比如按模块、按技术栈、按“常见问题”分类。2.3 搜索索引的混合设计一个知识库如果只能手动翻阅价值就减半了。Alexandria内置的搜索功能是其“活性”的关键。它采用的是一种混合搜索策略兼顾了内容相关性和页面重要性。其核心数据存储在search-index.json中包含三部分页面数据 (pages)缓存了每个wiki页面的标题、标题、首段、正文、更新时间、出链指向其他页面的链接等信息。避免每次搜索都重新读取和解析Markdown文件。倒排索引 (termIndex)一个经典的搜索数据结构。记录了每个关键词经过分词处理出现在哪些页面以及出现的频率。这是实现快速全文检索的基础。页面排名 (pageRank)借鉴自Google的算法通过分析页面之间的链接关系[[内部链接]]来计算每个页面的“重要性”。一个被很多其他页面引用的页面通常更权威。当执行搜索时排名分数是这样计算的最终分数 BM25(查询词 页面内容) * (1 α * PageRank(页面))其中BM25是一个信息检索领域的经典相关性评分算法它根据查询词在文档中的频率、文档长度等因素计算基础相关性。α是一个可调参数默认可能为0.5用于控制PageRank对最终结果的权重。结构权重加成为了提升搜索结果的质量不同部分的匹配被赋予了不同权重。例如在标题中匹配到的关键词其贡献度可能是在正文中匹配到的10倍。这符合我们的直觉——标题匹配的结果通常更相关。这种设计的好处是当你搜索“如何配置数据库”时不仅会找到内容中包含该短语的页面还会优先展示那些在项目知识网络中处于中心位置被频繁引用的、标题中就有“数据库配置”的页面结果质量远胜简单的字符串匹配。3. 从零开始部署与配置Alexandria3.1 环境准备与依赖安装Alexandria使用TypeScript编写运行环境依赖于Bun一个现代的JavaScript运行时。选择Bun而非Node.js主要是因为其更快的启动速度和内置的打包、测试等工具链这对于一个需要快速响应的MCP服务器来说很合适。步骤1安装Bun如果你的系统尚未安装Bun请先安装。在终端执行# 使用官方安装脚本macOS/Linux curl -fsSL https://bun.sh/install | bash # 对于Windows建议通过WSL2使用Linux环境或从GitHub Releases下载安装包。步骤2克隆项目并安装依赖# 克隆Alexandria仓库到本地 git clone https://github.com/graypirate/Alexandria.git cd Alexandria # 使用Bun安装项目依赖package.json中定义的 bun install这个过程会下载modelcontextprotocol/sdk等必要的MCP SDK包。如果网络不畅可以考虑配置Bun使用国内镜像源。3.2 注册MCP服务器到你的AI客户端MCP服务器需要被你的AI客户端宿主发现并连接。这里以Claude Desktop和Cursor为例因为它们是目前对MCP支持较好且流行的选择。方案A在Claude Desktop中配置Claude Desktop通常通过一个配置文件来管理MCP服务器。配置文件位置通常在macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json你需要编辑这个文件在mcpServers部分添加Alexandria的配置。为了安全建议先备份原文件。{ mcpServers: { alexandria: { command: bun, args: [/ABSOLUTE/PATH/TO/Alexandria/src/index.ts], env: { // 可以在这里传递环境变量比如指定知识库路径 // ALEXANDRIA_WIKI_ROOT: /path/to/your/wiki } } // ... 你其他的MCP服务器配置 } }关键点args中的路径必须是绝对路径。修改保存后完全重启Claude Desktop应用新的MCP服务器才会被加载。你可以在Claude的输入框旁看到工具图标如果配置成功Alexandria的工具如search应该会出现在可用工具列表中。方案B在Cursor中配置Cursor对MCP的支持可能还在演进中。一种常见的方式是通过Cursor的设置界面或配置文件来添加。请查阅Cursor的最新文档。另一种更通用的方式是确保Alexandria的MCP服务器进程在后台运行然后Cursor在启动时可能会自动发现本地MCP服务器。测试连接 配置完成后你可以在AI助手的对话中尝试调用工具。例如输入“请使用Alexandria的search工具帮我找一下关于‘错误处理’的文档。” 观察AI助手是否能正确识别并调用该工具。3.3 安装便携式技能SKILL.md技能文件是告诉AI“何时使用工具”的关键。Alexandria的技能文件位于项目内的.agents/skills/目录下。你需要将它们“安装”到你的AI客户端能读取的位置。通用方法创建符号链接大多数支持技能系统的客户端会扫描~/.agents/skills目录。我们可以创建符号链接这样当Alexandria项目更新时技能也会自动更新。# 确保用户主目录下的技能目录存在 mkdir -p ~/.agents/skills # 为每个技能创建符号链接 ln -sf /ABSOLUTE/PATH/TO/Alexandria/.agents/skills/wiki ~/.agents/skills/wiki ln -sf /ABSOLUTE/PATH/TO/Alexandria/.agents/skills/wiki-init ~/.agents/skills/wiki-init ln -sf /ABSOLUTE/PATH/TO/Alexandria/.agents/skills/wiki-ingest ~/.agents/skills/wiki-ingest ln -sf /ABSOLUTE/PATH/TO/Alexandria/.agents/skills/wiki-lint ~/.agents/skills/wiki-lint使用-sf参数强制创建软链接可以覆盖已存在的链接。客户端特定路径 有些客户端可能有自定义的技能路径。例如某些AI工具可能要求技能放在~/.config/agent/skills/下。你需要查阅你所使用客户端的文档并将技能文件复制或链接到正确的位置。注意事项技能的内容打开一个SKILL.md文件看看你会发现它其实就是一段Markdown文本描述了技能的触发条件、预期行为和可用工具。例如wiki-ingest/SKILL.md可能会包含“当用户要求保存会话内容或对话主题涉及需要持久化的知识时使用extract_session工具获取归档指南然后遵循指南更新wiki页面。” AI助手在会话开始时会加载这些技能描述从而获得调用Alexandria工具的能力和上下文。3.4 初始化你的第一个知识库现在MCP服务器和技能都已就位可以创建你的知识库了。知识库可以放在任何地方通常建议放在你的项目根目录下或者一个集中的笔记目录里。方法1通过AI助手触发这是最符合设计哲学的方式。在你的AI客户端对话中你可以直接说“请初始化一个Alexandria知识库路径在/my/project/docs/wiki。” AI助手应该会识别并调用wiki-init技能该技能进而调用scaffold工具来创建目录和文件。方法2手动调用工具调试用如果你在调试也可以直接通过MCP调用假设你有可以发送MCP请求的工具或脚本# 这是一种概念性演示实际调用取决于你的MCP客户端 # 工具名: scaffold, 参数: rootPath但更常见的是通过AI助手这个“中介”来操作。初始化完成后你会看到目标目录下生成了之前提到的标准结构。接下来最重要的两步是编辑CLAUDE.md和AGENTS.md这两个文件是AI助手的“入职手册”。CLAUDE.md可以包含项目特定的指令、代码风格约定、常用命令等。AGENTS.md则更侧重于告诉AI如何使用这个知识库例如“所有新知识请先记录在raw/目录下每周五进行整理归档”。你应该根据你的项目需求仔细编写这两个文件。将知识库路径告知MCP服务器为了让Alexandria的MCP服务器知道操作哪个知识库你需要通过环境变量或配置来指定。通常可以在启动命令的env里设置或者修改Alexandria项目本身的配置。查看src/index.ts或README看它如何读取ALEXANDRIA_WIKI_ROOT环境变量。4. 核心工作流实战知识的摄入、整理与检索4.1 会话知识提取Manual Session Extraction这是Alexandria最常用的功能之一把一次有价值的对话内容沉淀到知识库中。项目作者移除了自动化的会话结束钩子改为更可控的手动触发我认为这是一个明智的设计因为完全自动化归档可能会产生大量低质量内容。触发时机一次深度技术问题讨论结束后。编写了一个有用的脚本或解决方案。总结了某个复杂库的使用经验。任何你觉得“下次遇到同样问题我不想再解释一遍”的时刻。操作流程在对话中你告诉AI助手“请将我们刚才关于‘解决Redis连接池泄漏’的讨论保存到知识库。”AI助手识别到这个意图调用wiki-ingest技能。该技能指示它去调用extract_sessionMCP工具。extract_session工具并不直接保存内容而是返回一个结构化的归档提示Filing Prompt。这个提示可能长这样请根据以下会话摘要更新知识库 主题Redis连接池泄漏排查与修复 关键点 - 症状服务运行一段时间后出现ERR max number of clients reached。 - 根本原因未在finally块中释放连接。 - 解决方案修改getConnection函数确保使用try-catch-finally。 - 相关文件src/db/redisClient.js 操作建议 1. 在wiki/backend/database.md的“故障排查”章节新增一节。 2. 或将此内容新建为wiki/backend/redis-connection-pool-leak.md。 3. 在log.md中追加记录。 请开始执行。AI助手接收到这个提示它会根据提示中的建议像一名技术写手一样去编辑或创建对应的wiki页面将零散的对话转化为结构化的文档。文档更新后AI助手需要调用index_build工具来重建搜索索引确保新内容能被搜到。实操心得引导AI写出好文档extract_session工具生成的提示质量取决于项目prompts/session-end.md模板的设计。你可以修改这个模板让它更符合你的文档风格。例如要求AI“使用倒金字塔结构先写结论再写步骤”、“代码示例需包含必要的导入语句和错误处理”。好的提示模板能极大提升归档内容的质量。4.2 知识库的日常维护与巡检Linting知识库不是“只写不读”的坟墓它需要维护。Alexandria的lint_structural工具就像一个自动化的图书管理员能帮你发现知识库中的“问题”。运行该工具通常通过wiki-lint技能触发它会扫描整个wiki/目录检查孤儿页面没有任何其他页面通过[[内部链接]]引用它的页面。这可能意味着该页面内容未被整合到知识网络中或者它不重要。损坏链接指向不存在的wiki页面的内部链接。陈旧页面长时间未更新的页面依据文件mtime判断。可能需要复审其内容是否过时。索引缺口搜索索引search-index.json中记录的文件与实际文件系统不匹配例如文件被重命名或删除后索引未更新。处理建议对于孤儿页面考虑将其内容合并到相关主题页面或在index.md和其他页面中添加对其的引用。对于损坏链接要么修复链接指向正确的页面要么删除无效链接。对于陈旧页面安排时间进行内容复审和更新。定期如每周运行一次lint然后调用index_build是保持知识库健康的好习惯。4.3 高效检索让AI成为你的知识管家当知识库积累到一定规模后强大的搜索能力就是核心。Alexandria的search工具是AI助手与你知识库交互的主要窗口。搜索语法与策略 虽然search工具可能支持简单的查询但通过AI助手你可以进行更“语义化”的搜索。例如模糊搜索“帮我找找所有和‘性能优化’相关的笔记。”组合搜索“查找同时提到‘Docker’和‘内存限制’的页面。”排除搜索“找一下‘身份认证’的文档但不要OAuth相关的。”AI助手在背后会将你的自然语言查询转化为对search工具的调用并利用BM25PageRank的混合排名将最相关的结果呈现给你。更重要的是AI可以理解搜索结果。它不只是返回一个文件列表而是可以读取这些文件的内容并综合起来回答你的问题。典型场景 你问“我们项目当初为什么选择MongoDB而不是PostgreSQL” AI助手会调用search工具查询“MongoDB PostgreSQL 选型”。得到排名最高的几个页面比如wiki/arch/decision-log.md和wiki/db/mongodb-intro.md。读取这些页面的内容。综合这些内容生成一个结构化的回答“根据决策日志记录主要基于以下三点1. 我们需要处理大量非结构化的设备日志数据MongoDB的文档模型更合适2. 初期开发迭代快模式变更频繁MongoDB无需预定义模式3. 当时团队对MongoDB更熟悉。详细论证过程见wiki/arch/decision-log.md#2023-05-01。”这样知识库就从被动的存储变成了一个能主动提供答案的“团队记忆体”。5. 高级配置、问题排查与生态整合5.1 配置详解与性能调优Alexandria的核心配置主要通过环境变量和alexandria.json文件管理。环境变量ALEXANDRIA_WIKI_ROOT最重要的变量指定知识库的根目录绝对路径。必须在启动MCP服务器时设置。ALEXANDRIA_LOG_LEVEL设置日志级别如debug,info,warn,error调试问题时设为debug很有用。ALEXANDRIA_SEARCH_ALPHA调整PageRank在搜索排名中的权重因子α。默认值可能为0.5。如果你发现链接多的页面总是排名太高可以适当调低此值如0.2如果希望更强调页面权威性可以调高如0.8。.alexandria.json 这个文件位于每个知识库的根目录用于存储该知识库的特定配置。{ indexRefreshThreshold: 3600, // 搜索索引自动刷新的时间阈值秒默认1小时 ignorePatterns: [temp/*, drafts/*], // 构建索引时忽略的文件/目录模式 pageRankDampingFactor: 0.85, // PageRank算法的阻尼系数通常不需要改 titleBoost: 10, // 标题匹配权重加成 headingBoost: 5, // 标题匹配权重加成 firstParagraphBoost: 3 // 首段匹配权重加成 }你可以根据知识库的特点调整这些参数。例如如果你的wiki有很多临时草稿可以把drafts/加入ignorePatterns。5.2 常见问题与排查技巧问题1AI助手无法识别或调用Alexandria的工具。检查MCP服务器状态首先确认Alexandria的MCP服务器进程正在运行。可以在终端执行ps aux | grep bun查看。检查客户端配置确认Claude Desktop或Cursor的MCP配置文件中Alexandria的command和args路径完全正确特别是绝对路径。查看客户端日志Claude Desktop通常有日志文件位置因系统而异查看其中是否有MCP连接错误信息。重启客户端修改MCP配置后必须完全退出并重启客户端配置才会生效。问题2搜索返回结果为空或不准。索引是否最新在写入wiki内容后是否运行了index_build可以手动触发一次重建。检查search-index.json文件查看该文件是否损坏或为空。可以尝试删除它然后触发一次搜索工具会尝试懒构建。搜索词问题搜索工具可能对英文词干化stemming支持更好。尝试使用更基础的关键词。同时确保你的查询语言与知识库内容的主要语言一致。问题3技能SKILL.md没有被AI助手加载。检查技能路径确认符号链接或文件复制到了正确的目录并且AI客户端配置的技能搜索路径包含该目录。检查技能文件格式确保SKILL.md是有效的Markdown文件并且内容清晰描述了触发条件和工具使用方式。可以对比Alexandria项目自带的原版文件。查看AI助手的技能列表有些客户端提供命令来列出已加载的技能例如在Claude中可能输入/skills。检查你的技能是否在其中。问题4extract_session工具返回的归档提示太笼统。定制prompts/session-end.md这是控制提示生成质量的模板。你可以修改它加入更具体的指令比如“请用三个要点总结核心解决方案”、“必须包含代码片段和对应的文件路径”、“将新内容归类到以下主题之一前端、后端、运维”。在对话中提供更明确的指令当你要求保存会话时可以更具体例如“请将我们讨论的‘用户登录流程的时序图’保存到wiki/design/auth-sequence.md文件中并更新index.md中的设计部分。”5.3 与现有工作流和工具的整合Alexandria不是一个孤岛它可以很好地融入你现有的开发和工作流。与版本控制系统Git集成 你的知识库目录本身就是一个普通的文件夹。强烈建议将其纳入Git管理。这样知识的每一次变更都有历史记录可以回滚也方便团队协作。你可以在AGENTS.md中告诉AI“所有对wiki/目录的修改在提交前需要经过人工复审。”或者设置Git钩子在提交时自动运行lint_structural进行检查。与文档生成器集成 如果你的wiki/是结构化的Markdown你可以使用像MkDocs、Docusaurus或VuePress这样的静态站点生成器将知识库发布为内部技术网站。只需将生成器的源目录指向你的wiki/根目录即可。Alexandria维护的index.md可以成为网站的首页。扩展到团队使用Alexandria目前设计为单用户、单知识库。但在团队中可以有以下模式共享知识库将知识库放在团队共享的Git仓库中。每个成员配置自己的Alexandria实例指向这个共享目录。需要注意文件写入冲突可以通过Git工作流拉取、合并、解决冲突来管理。个人知识库 聚合索引每个成员维护自己的个人知识库。可以编写一个脚本定期将所有人的search-index.json合并成一个大的索引从而实现跨个人知识库的搜索。这更复杂但隔离性更好。自定义工具扩展Alexandria的MCP工具集是开放的。如果你有特殊需求可以仿照src/tools/下的模式开发自己的工具。例如添加一个generate_diagram工具根据wiki中的文本描述调用Graphviz生成架构图并保存到raw/assets/。然后在相应的SKILL.md中描述何时使用这个新工具。这让你能不断扩展AI助手管理知识的能力边界。通过以上这些实战步骤和深度解析你应该能够将Alexandria这套系统有效地部署和集成到你的日常开发与学习流程中。它的核心价值在于将AI从一次性的对话伙伴升级为你的长期知识合伙人共同构建和维护一个不断生长、随时可查的“第二大脑”。开始可能觉得多了一些步骤但习惯之后你会发现为知识付出的这些“维护成本”会在未来遇到问题时以极高的效率回报给你。