1. 项目概述当你的AI助手患上“失忆症”如果你是一名开发者并且深度使用过 Claude、GitHub Copilot 或 Cursor 这类 AI 编程助手下面这个场景你一定不陌生周一你花了二十分钟向 Claude 详细解释了你们项目的认证系统架构——从 JWT 与刷新令牌的配合到使用 httpOnly Cookie 的安全性考量再到src/auth/目录下的中间件实现细节甚至包括上周团队从 Session 迁移到 Token 的决策原因。周二当你准备基于昨天的讨论继续推进时你发现 Claude 对你昨天讲的一切一无所知仿佛那场对话从未发生。你不得不重新开始“嘿 Claude还记得我们的认证系统吗……不记得了好吧让我再解释一遍。”这并非模型能力的问题。无论是 GPT-4、Claude 还是 Gemini在单次会话的上下文窗口内它们都表现出了惊人的理解和记忆能力。问题的核心在于会话之间。当前的 AI 助手缺乏一种机制将一次对话中获得的知识、决策和上下文持久化地保存下来供未来的会话调用。每一次对话都像是一次重启上一次的“工作记忆”被完全清空。这严重限制了 AI 作为长期、连贯的协作伙伴的潜力迫使开发者陷入重复解释的低效循环。幸运的是随着 Anthropic 在 2024 年底发布Model Context Protocol这一困境迎来了转机。MCP 本质上是一个开放标准它允许 AI 客户端如 Claude Desktop去发现和使用外部工具就像为 AI 能力扩展提供了一个通用的“USB 接口”。基于 MCP我们可以构建一个专为 AI 设计的“记忆外挂”让任何兼容 MCP 的客户端都能获得持久化、可搜索的记忆能力。这就是Wyrm项目的由来——一个开源的、本地的、功能全面的 AI 记忆 MCP 服务器。Wyrm 的核心价值在于它将 AI 助手从一个“健忘的临时工”转变为一个“有连续记忆的资深同事”。它允许你将项目结构、技术决策、会话历史、待办任务乃至任意结构化数据存储在一个本地的 SQLite 数据库中。AI 助手可以通过 Wyrm 提供的工具集随时写入新的记忆或搜索过往的一切记录。所有数据都留在你的本地机器上无需担心隐私和云端延迟。接下来我将深入拆解 Wyrm 的设计思路、技术实现细节、实操部署步骤并分享在构建和使用过程中积累的宝贵经验。2. 核心架构与设计哲学2.1 为什么选择 MCP 作为基石在 Wyrm 之前为 AI 添加记忆功能通常有几种路径一是等待 AI 客户端厂商如 Anthropic、Microsoft自行开发并集成该功能但这受制于他们的产品路线图和优先级二是针对某个特定客户端如 VS Code 插件开发私有扩展但这意味着你的记忆被锁定在一个生态内。MCP 的出现提供了一种更优雅、更开放的解决方案。它定义了一套标准的通信协议基于 JSON-RPC over stdio使得任何实现了 MCP 服务端的应用都能被任何实现了 MCP 客户端的 AI 工具所调用。这带来了几个关键优势生态无关性只要你的 AI 工具支持 MCP如 Claude Desktop、新版 GitHub Copilot Chat、Cursor它就能立即使用 Wyrm 的记忆功能无需为每个工具单独适配。关注点分离AI 客户端专注于提供优秀的对话和代码生成体验而记忆、文件操作、数据库查询等“外部能力”则由独立的 MCP 服务器提供。这种架构更清晰也更容易维护和扩展。本地化与隐私MCP 服务器运行在本地所有数据流转不经过第三方服务器。这对于存储代码、架构决策等敏感信息至关重要。因此构建 Wyrm 作为 MCP 服务器是赋予 AI 持久记忆能力最通用、最可持续的技术路径。它不是一个临时补丁而是面向未来 AI 工具生态的基础设施。2.2 整体数据流与组件交互Wyrm 的架构非常清晰遵循了经典的客户端-服务器模式但客户端是 AI服务器是记忆引擎。用户 - AI 客户端 (Claude Desktop/Copilot/Cursor) - [MCP 协议] - Wyrm MCP 服务器 - SQLite 数据库用户发起请求用户在 AI 客户端的聊天界面中提出一个需要记忆或回忆上下文的需求例如“把我们项目的 API 限流规则记下来。”AI 客户端决策AI 模型理解用户意图后发现需要调用外部工具来完成“记忆”这个动作。它会检查已注册的 MCP 服务器列表找到 Wyrm 提供的工具。MCP 协议调用AI 客户端通过 stdio标准输入输出向 Wyrm 服务器发送一个结构化的 JSON-RPC 请求指定要调用的工具如wyrm_data_insert和参数。Wyrm 服务器处理Wyrm 接收到请求解析参数执行对应的业务逻辑——在这个例子中就是将 API 限流规则写入数据库的特定“命名空间”。数据持久化业务逻辑操作最终会落实到对本地 SQLite 数据库的增删改查。结果返回Wyrm 将操作结果成功或失败附带相关信息封装成 JSON-RPC 响应通过 stdio 返回给 AI 客户端。AI 回复用户AI 客户端收到 Wyrm 的响应后将其内容整合到对话中告知用户“已成功存储 API 限流规则。免费层 100次/小时专业层 1000次/小时企业层不限。”这个流程对于用户和 AI 而言几乎是透明的。用户感觉像是在和一個记忆力超群的 AI 对话而背后是 Wyrm 在高效、可靠地管理着所有记忆数据。2.3 为什么是 SQLite技术选型的深度考量为 Wyrm 选择存储方案时我们考虑了多种可能性纯文件存储JSON、Markdown、嵌入式键值库LevelDB、RocksDB、乃至轻量级服务SQLite。最终SQLite脱颖而出原因如下零运维与极致便携SQLite 是一个库而非一个需要独立安装、配置、守护进程的“服务器”。它以一个*.db文件的形式存在。对于 Wyrm 这样的开发者工具npm install之后立即可用是巨大的优势。用户无需启动 PostgreSQL 或 MySQL 服务没有端口冲突没有权限管理复制和备份就是一个文件的事。强大的并发与可靠性很多人对 SQLite 有“不支持高并发”的误解。实际上在启用WALWrite-Ahead Logging模式后SQLite 可以很好地支持“多读单写”或“多读多写通过忙时重试”的场景。对于 Wyrm 的使用场景——可能同时有 Claude Desktop 和 VS Code Copilot 两个客户端连接——WAL 模式完全能够胜任且保证了数据的一致性和崩溃恢复能力。内置全文搜索 (FTS5)记忆的核心能力之一是“回忆”即搜索。SQLite 内置的FTS5全文搜索扩展提供了强大、高效的文本搜索能力支持分词、排名、片段提取。这意味着我们无需引入 Elasticsearch 或 MeiliSearch 这样的外部搜索服务在一个单一的、轻量的wyrm.db文件中就同时实现了结构化存储和全文索引极大地简化了架构和部署。关系型数据模型Wyrm 需要管理多种类型的实体项目、会话、任务、数据点它们之间存在关联例如一个任务属于一个项目一个会话会产生多个数据点。SQLite 的关系模型和强大的 SQL 查询能力使得建模和复杂查询变得非常自然和高效。实操心得WAL 模式配置在初始化 Wyrm 数据库时务必在连接数据库后立即执行PRAGMA journal_mode WAL;。这不仅能提升并发性能还能防止在长时间写入时锁定整个数据库文件导致其他读取操作被阻塞。这是保证 Wyrm 在多客户端环境下流畅运行的关键一步。2.4 记忆的维度Wyrm 的四大核心实体Wyrm 并非简单地将聊天记录扔进数据库。它设计了一套结构化的数据模型将记忆分为四个维度使记忆更加有序、可检索、可操作。2.4.1 项目项目是记忆的最高层级组织单元。Wyrm 可以自动扫描你的工作目录如~/projects发现 Git 仓库并将其注册为一个项目。项目记忆包括仓库路径、最近活跃时间、以及关联的所有会话、任务和数据。这相当于为 AI 建立了一个“工作空间”地图。2.4.2 会话会话代表一次有明确目标的协作周期比如“重构支付 API”或“调试登录页面的 CSS 问题”。每次你开始一个新的重要话题都可以让 AI 开启一个新会话。会话会记录目标、过程中的关键决策、达成的结论以及最终状态。下次你回到同一项目时AI 可以通过查看历史会话快速理解之前的上下文和决策脉络避免“从头再来”。2.4.3 任务Wyrm 将其称为“Quests”比普通的 Todo 更具叙事性。任务是与项目绑定的待办事项可以设置标题、描述、优先级和状态。你可以直接对 AI 说“为当前项目添加一个高优先级任务将 Stripe Webhook 处理器升级到 v2 API。” AI 会调用wyrm_quest_add工具将其记录在案。之后你可以随时询问“我这个项目还有哪些待办任务” AI 会从 Wyrm 中查询并列出。2.4.4 数据湖这是最灵活的记忆单元。你可以用它存储任何结构化的信息以键值对的形式组织在不同的“命名空间”下。例如命名空间api-config键rate-limits值{“free”: 100, “pro”: 1000, “enterprise”: “unlimited”}命名空间team-members键backend-lead值{“name”: “Alice”, “slack”: “alice_dev”}命名空间decisions键2024-03-20-auth值“决定采用 JWT httpOnly Cookie 而非 localStorage 存储 token以防范 XSS 攻击。”数据湖的设计哲学是“万物皆可存”为 AI 提供了一个可随意读写的长期记忆黑板。3. 从零开始部署与深度配置3.1 环境准备与源码获取Wyrm 是一个 TypeScript 项目运行它需要 Node.js 环境建议版本 18。首先我们从 GitHub 获取源代码。# 克隆仓库 git clone https://github.com/ghosts-lk/Wyrm.git cd Wyrm/packages/mcp-server # 安装依赖并构建 npm install npm run buildnpm run build命令会执行 TypeScript 编译将src/下的源代码编译成dist/目录下的 JavaScript 可执行文件。构建完成后为了方便全局调用我们可以使用npm link命令。# 将 wyrm-mcp 命令链接到全局环境 npm link执行成功后你就可以在终端任何位置直接运行wyrm-mcp命令来启动 Wyrm 服务器了。你可以通过wyrm-mcp --help验证是否安装成功。注意事项依赖隔离如果你使用 nvm 等 Node 版本管理工具请确保在正确的 Node 版本环境下执行npm link。有时全局链接可能会因为路径问题失效。如果遇到“命令未找到”的错误可以尝试直接使用绝对路径运行node /path/to/Wyrm/packages/mcp-server/dist/index.js。在配置 AI 客户端时这个绝对路径可以作为command的值。3.2 配置 AI 客户端连接Wyrm 本身只是一个服务器需要 AI 客户端主动连接它。下面以 Claude Desktop 和 VS Code GitHub Copilot Chat 为例演示配置方法。3.2.1 连接 Claude DesktopClaude Desktop 的 MCP 服务器配置位于一个 JSON 文件中。文件路径因操作系统而异macOS/Linux:~/.config/claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json你需要创建或编辑这个文件添加mcpServers配置节。{ mcpServers: { wyrm: { command: wyrm-mcp, args: [] } } }说明command字段的值“wyrm-mcp”就是我们之前通过npm link注册的全局命令。如果链接失败这里需要替换为编译后入口文件的绝对路径例如“node”和“args”: [“/Users/yourname/Wyrm/packages/mcp-server/dist/index.js”]。保存文件后必须完全重启 Claude Desktop 应用不仅仅是关闭窗口最好从任务管理器或活动监视器中彻底退出再启动。重启后在 Claude 的聊天界面你应该能看到一个微小的变化通常是在输入框附近出现一个服务器连接图标或提示表明 MCP 服务器已加载。你可以尝试问 Claude“你现在有哪些可用的工具” 它应该会列出 Wyrm 提供的数十个工具如wyrm_search,wyrm_project_list等。3.2.2 连接 VS Code GitHub Copilot Chat新版 VS Code 的 GitHub Copilot Chat 也支持 MCP。配置是通过项目级或用户级的settings.json文件完成的。最常用的方式是在你的项目根目录下创建或编辑.vscode/settings.json文件。这样做的好处是配置仅对当前项目生效便于不同项目使用不同的 MCP 服务器。{ mcp: { servers: { wyrm: { command: wyrm-mcp, args: [] } } } }同样如果wyrm-mcp命令不可用需使用“node” 绝对路径的args组合。保存后重启 VS Code 或重新加载窗口。打开 Copilot Chat 面板你可以直接询问“你能用 Wyrm 帮我记忆一些事情吗” 或者查看它能调用的工具列表。避坑指南配置不生效的常见原因路径错误这是最常见的问题。确保command和args指向的路径是真实存在的、可执行的文件。在终端中手动执行一下这个命令看是否能启动 Wyrm 服务器。客户端未重启修改 MCP 配置后必须彻底重启 AI 客户端。很多客户端只在启动时读取一次配置。权限问题确保 Node 脚本有可执行权限。在 Unix 系统上有时需要对dist/index.js文件执行chmod x dist/index.js。端口或进程冲突虽然 MCP 多用 stdio但确保没有其他进程占用了可能需要的资源。如果启动失败查看客户端的错误日志通常可以在其设置或关于页面中找到日志路径是定位问题的关键。3.3 初始化与首次使用配置完成并重启客户端后Wyrm 服务器会在 AI 客户端第一次尝试调用其工具时自动启动。你可以通过一个简单的指令开始体验。直接对你的 AI 助手说“扫描我的项目目录比如 ~/Code 或 ~/projects看看有哪些 Git 仓库并把它们注册到 Wyrm 里。”AI 助手会理解你的意图并调用wyrm_scan_projects工具。该工具需要你提供一个directory参数即要扫描的路径。AI 可能会向你确认这个路径。确认后它会执行扫描发现所有 Git 仓库并将它们作为“项目”注册到 Wyrm 的数据库中。这个过程完成后Wyrm 的记忆体系就有了根基。之后所有关于这些项目的会话、任务和数据都会自动与对应的项目关联。4. 核心功能实操与高级用法4.1 会话管理让对话拥有连续性会话是 Wyrm 中最能体现“记忆”价值的功能。它的使用非常直观。开启一个会话当你开始一项新的、持续性的工作时告诉 AI“为‘用户仪表盘性能优化’开一个新的会话。” AI 会调用wyrm_session_start传入项目 ID通常来自当前工作目录关联的项目和会话标题。Wyrm 会创建一个新的会话记录并返回一个唯一的会话 ID。此后在这个对话上下文中AI 会自动将这个会话 ID 用于后续相关的记忆操作。在会话中工作在会话进行中你可以随时让 AI 记录关键信息。例如“把刚才我们决定的‘使用虚拟滚动替代分页加载’这个架构决策记下来。”“记录一下我们排查出的性能瓶颈主要是由于未索引的 userId 查询。” AI 会调用wyrm_data_insert或wyrm_note_add等工具将这些信息与当前会话关联起来。结束与回顾会话工作完成后告诉 AI“结束当前会话状态标记为‘已完成’总结为‘成功实现了列表渲染性能提升 200%’。” AI 调用wyrm_session_update来关闭会话并添加总结。一周后当你重新打开这个项目可以问 AI“这个项目之前做过关于性能优化的工作吗” AI 会调用wyrm_session_list或wyrm_search找到相关的历史会话并为你呈现完整的决策脉络无需你重新解释。实操心得会话命名的艺术会话标题应尽量具体、包含关键词。避免使用“开会讨论”或“修复bug”这样模糊的标题。好的标题如“重构支付服务以支持多币种”、“调查并修复登录 API 在高峰期的超时问题”。这样在未来搜索时例如搜索“支付”、“超时”相关会话能更容易被检索到极大提升了记忆的可用性。4.2 任务追踪将待办事项融入工作流Wyrm 的任务Quests系统让你能在与 AI 协作的自然对话中管理待办事项。添加任务在讨论中任何衍生出的行动项都可以立即转化为任务。你“这个缓存策略听起来不错但我们还需要评估一下对现有数据一致性的影响。”AI“好的。需要我把‘评估新缓存策略对数据一致性的影响’作为一个待办任务添加进来吗你可以指定优先级。”你“是的添加为高优先级任务。” AI 便会调用wyrm_quest_add创建一条任务记录。查询与更新任务你可以随时询问“我这个项目还有哪些未完成的高优先级任务” AI 会调用wyrm_quest_list进行过滤和查询。完成任务后告诉 AI“把‘评估缓存策略’这个任务标记为已完成。” AI 使用wyrm_quest_update来更新状态。任务与上下文的结合这是 Wyrm 的强大之处。当 AI 为你处理一个任务时例如编写一个函数它可以先调用wyrm_quest_get获取该任务的详细描述和历史记录再调用wyrm_search查找项目中相关的代码片段或设计决策例如之前记录的“数据一致性模式”然后生成更贴合项目上下文的代码。这使得 AI 的工作不再是孤立的片段而是建立在项目整体记忆之上的连贯创作。4.3 数据湖你的项目知识库数据湖是 Wyrm 的“瑞士军刀”用于存储一切你需要 AI 记住的零散但重要的信息。存储结构化配置这是最直接的用途。例如向 AI 描述你的项目配置“记住我们后端的运行端口是 3001数据库连接池大小是 20日志级别在生产环境是 ‘warn’。” AI 会将其分解并存储到类似infra-config的命名空间下。记录架构决策这是避免“历史重演”的关键。每次技术讨论做出重要决定后立即让 AI 记录。例如“记录架构决策 ADR-003选择 RabbitMQ 而非 Kafka 作为消息队列原因是项目初期复杂度低RabbitMQ 的运维更简单且当前流量规模完全足够。决策日期 2024-03-15。” AI 会将其存入architecture-decisions命名空间。几个月后当有人质疑为何不用 Kafka 时一搜便知。保存代码片段模式你可以让 AI 记住一些优秀的、可复用的代码模式。例如“这是一个我们项目中处理数据库事务的通用 helper 函数模式把它存下来。” 然后粘贴代码。AI 会将其存入code-patterns命名空间。下次需要写类似事务代码时AI 可以优先参考这个模式。搜索数据湖当需要回忆时使用自然语言搜索即可。“我们之前关于消息队列的决策是什么” 或 “找一下处理数据库事务的代码模式。” AI 会利用 Wyrm 的全文搜索能力在数据湖中快速找到相关信息。4.4 双向 Markdown 同步记忆的“人可读”备份Wyrm 一个非常巧妙的设计是双向 Markdown 同步。它在每个被跟踪的项目的根目录下维护一个.wyrm/隐藏文件夹里面包含几个 Markdown 文件hoard.md: 存储该项目所有的“数据湖”条目即零散的知识点。chronicles.md: 存储该项目所有的会话历史。quests.md: 存储该项目所有的任务列表。protocol.md: 存储给 AI 的特定项目指南或指令可选。为什么需要这个功能可读性与可维护性数据库里的内容对机器友好但对人不可读。Markdown 文件让开发者可以直接浏览、编辑项目的“记忆”无需通过 AI 界面。你可以用任何文本编辑器打开chronicles.md查看项目完整的发展历史。版本控制集成Markdown 文件可以被 Git 跟踪。这意味着你的项目记忆成为了代码库的一部分团队成员可以通过git pull获取最新的项目上下文通过git commit和git push来贡献或更新记忆。这为团队协作使用 AI 记忆提供了天然的基础设施。备份与迁移你的记忆不再被锁死在单个数据库文件中。.wyrm/文件夹可以随项目复制、备份。即使 Wyrm 数据库损坏你也可以从这些 Markdown 文件中重建记忆Wyrm 提供了相应的导入工具。同步机制Wyrm 会定期或在关键操作后自动将数据库中的更新同步到对应的 Markdown 文件反之亦然。你也可以手动触发同步。这保证了“机器记忆”和“人类文档”之间的一致性。注意事项.gitignore 的配置由于.wyrm/目录下的文件可能包含项目特定的敏感信息如内部决策、未公开的配置在将其纳入 Git 版本控制前请务必仔细审查内容。一个常见的做法是将.wyrm/目录加入.gitignore而只选择性地将不敏感的文件如protocol.md中的公共协作指南提交到仓库。或者建立团队规范规定哪些类型的记忆可以共享。Wyrm 的灵活性把选择权交给了你和你的团队。5. 高级特性与底层原理剖析5.1 全文搜索的实现FTS5 与触发器的精妙配合Wyrm 的“搜索一切”能力是其核心体验的保障。实现上它依赖于 SQLite 的 FTS5 虚拟表。但如何保证每当有新的项目、会话、任务或数据被创建或更新时其内容都能自动进入全文索引呢手动维护索引是繁琐且易错的。Wyrm 的解决方案是使用数据库触发器。它为每个需要被搜索的实体表projects,sessions,quests,data_points创建了AFTER INSERT和AFTER UPDATE触发器。例如对于data_points表CREATE TRIGGER IF NOT EXISTS data_points_ai AFTER INSERT ON data_points BEGIN INSERT INTO wyrm_fts (entity_type, entity_id, content) VALUES (data_point, NEW.id, NEW.key || || NEW.value); END; CREATE TRIGGER IF NOT EXISTS data_points_au AFTER UPDATE ON data_points BEGIN UPDATE wyrm_fts SET content NEW.key || || NEW.value WHERE entity_type data_point AND entity_id NEW.id; END;当一条新的data_point被插入时data_points_ai触发器会自动将其key和value字段拼接后插入到名为wyrm_fts的 FTS5 虚拟表中。更新操作同理。这样无论数据通过何种方式AI 调用、手动同步进入数据库索引都能保持实时更新。搜索时只需对wyrm_fts表执行一个简单的MATCH查询就能返回所有相关的结果并附带结果类型和原始 ID便于后续获取详细信息。5.2 可选加密为敏感记忆上锁并非所有记忆都需要加密。项目路径、公开的会话标题可能无需保护。但对于存储了 API 密钥模式、内部系统架构图、未公开的商业逻辑决策等敏感信息的“数据湖”条目加密是必要的。Wyrm 采用了AES-256-GCM加密算法。这是一种认证加密模式既能保证机密性无法解密则无法读取又能保证完整性数据被篡改会被检测到。加密流程如下密钥管理Wyrm 在首次运行时会在用户配置目录如~/.wyrm/生成一个加密密钥。该密钥由系统随机生成并永远只存储在本地。Wyrm 不会将其发送到任何远程服务器。选择性加密在创建data_point时可以通过参数指定是否需要加密。只有标记为加密的条目其value字段才会被加密处理。透明解密当 AI 通过wyrm_data_get或搜索功能请求数据时Wyrm 会自动识别条目是否加密。如果是加密条目则使用本地密钥解密后再返回给 AI。这种设计在安全性和便利性之间取得了平衡。用户可以为最敏感的信息启用加密而其他大部分记忆则保持明文享受更快的检索速度。加密开关完全由用户控制。5.3 工具描述与 AI 调用的可靠性MCP 服务器通过向客户端声明一系列“工具”来暴露其能力。每个工具都有详细的模式定义包括工具名称、描述、输入参数模式JSON Schema。AI 模型正是依靠这些描述来决定在什么情境下调用哪个工具。Wyrm 的 31 个工具都配备了清晰、准确的描述。例如wyrm_search工具的描述可能是“在全站范围内搜索记忆内容包括项目、会话、任务和数据点。返回与查询词最相关的结果列表。” 输入参数模式会定义query字段为字符串类型且必需。现代大语言模型在工具调用Function Calling方面已经相当成熟。只要工具描述清晰、职责单一AI 就能在合适的时机准确地调用它。在开发 Wyrm 的过程中我发现 Claude 3.5 Sonnet 和 GPT-4 在理解“现在需要记住这个”、“帮我找一下之前关于X的讨论”这类意图并映射到wyrm_data_insert或wyrm_search工具上准确率非常高。这减少了用户需要记忆具体工具名的认知负担实现了自然语言到工具调用的无缝衔接。6. 常见问题与故障排查实录在实际部署和使用 Wyrm 的过程中你可能会遇到一些典型问题。以下是我在开发和测试中积累的排查经验。问题一AI 客户端无法连接 Wyrm提示“无法启动服务器”或“连接失败”。可能原因 1命令路径错误。排查在终端中手动执行配置文件中command和args指定的完整命令看是否能正常启动并打印日志通常 Wyrm 启动会打印一行服务器已启动的信息。解决如果手动执行失败检查 Node.js 环境、依赖是否安装完整node_modules存在。如果手动执行成功但客户端不行可能是客户端的环境变量 PATH 与终端不同。尝试在配置中使用node的绝对路径和脚本的绝对路径。可能原因 2端口或权限冲突。排查MCP 通常使用 stdio但检查是否有其他错误。查看 AI 客户端的错误日志在 Claude Desktop 的设置中可找到日志文件位置。解决根据日志错误信息调整。确保运行 Wyrm 的用户对数据库文件路径~/.wyrm/有读写权限。可能原因 3配置文件格式错误。排查使用 JSON 验证工具检查你的claude_desktop_config.json或.vscode/settings.json文件确保没有多余的逗号、括号不匹配等问题。解决修正 JSON 格式错误。问题二AI 可以连接但调用工具时失败返回“Tool not found”或内部错误。可能原因 1工具名称不匹配。排查让 AI 列出所有可用工具例如问“你现在有哪些工具”核对 Wyrm 的工具是否在列表中。如果不在说明服务器连接可能未完全成功。解决彻底重启 AI 客户端。可能原因 2数据库文件损坏或权限问题。排查查看 Wyrm 服务器的输出日志如果客户端能捕获的话或者尝试以调试模式启动 Wyrm 服务器例如在命令后加--verbose如果支持看是否有 SQLite 错误。解决检查~/.wyrm/wyrm.db文件是否存在且可读写。在极端情况下可以尝试备份后删除该文件Wyrm 会在下次启动时重新创建空数据库注意这会丢失所有记忆。可能原因 3输入参数不符合模式。排查AI 有时可能生成错误的参数格式。虽然不常见但可以查看错误信息。解决尝试用更简单、明确的指令引导 AI。例如不说“记住端口是3000”而说“请使用 wyrm_data_insert 工具在 ‘project-config’ 命名空间下存储一个 key 为 ‘backend-port’value 为 ‘3000’ 的数据。”问题三搜索功能找不到明明已经存储的内容。可能原因 1搜索词与存储内容差异太大。排查FTS5 默认使用简单的分词器。搜索“数据库迁移”可能匹配不到“迁移数据库方案”。解决尝试使用更核心的关键词搜索或用多个词。也可以让 AI 查看原始存储的数据确认存储的文本内容。可能原因 2数据未成功同步到 FTS 索引。排查这是一个低级错误但触发器如果因故未创建会导致索引不更新。解决可以检查数据库 schema确认wyrm_fts表和相关的触发器是否存在。Wyrm 在初始化时应已创建。如果怀疑索引问题可以尝试重启 Wyrm 服务器有时重建连接会触发检查。问题四团队协作时如何共享 Wyrm 记忆现状Wyrm 的数据库是本地文件默认不支持多用户同时读写。建议方案利用 Markdown 同步与 Git这是目前最可行的方式。团队成员约定将.wyrm/目录下的protocol.md项目指南和部分不敏感的hoard.md知识库纳入版本控制。每个人本地的 Wyrm 会读取这些文件从而获得共享的基础记忆。个人的会话和任务则保留在本地。网络共享数据库高级理论上可以将wyrm.db文件放在网络共享存储上但 SQLite 在网络文件系统上的并发性能和可靠性需要仔细测试不推荐用于生产级协作。未来可能性Wyrm 作为开源项目未来可能会开发客户端-服务器模式提供一个中心化的记忆服务供团队使用。目前专注于个人和基于 Git 的轻量级协作是更稳定的选择。问题五数据库文件越来越大如何清理或优化自动清理Wyrm 目前没有内置的自动清理机制。所有记忆都会被永久保存。手动管理你可以直接使用 SQLite 客户端如sqlite3命令行工具或 DB Browser for SQLite打开~/.wyrm/wyrm.db手动删除不再需要的记录。操作前务必备份数据库可以定期将旧的、已完成的会话和任务导出到 Markdown 文件进行归档然后从数据库中删除。SQLite 数据库在删除大量数据后文件大小可能不会自动缩小。可以使用VACUUM;命令来重建数据库释放空间。同样操作前请备份。7. 开发实践与项目贡献Wyrm 是一个 TypeScript 项目结构清晰依赖极少核心只有better-sqlite3和modelcontextprotocol/sdk这使其成为学习和贡献 MCP 服务器开发的优秀范例。项目结构概览Wyrm/packages/mcp-server/ ├── src/ │ ├── index.ts # 服务器主入口MCP 服务器初始化 │ ├── database/ # 数据库连接、初始化、Schema 定义 │ ├── tools/ # 所有 31 个工具的实现如 search.ts, project.ts │ ├── sync/ # Markdown 双向同步逻辑 │ └── utils/ # 加密、路径处理等工具函数 ├── tests/ # 单元测试和集成测试 ├── package.json └── tsconfig.json如果你想为其添加新功能例如增加一个“代码片段收藏夹”工具大致流程如下在src/tools/目录下创建新文件例如snippet.ts。实现工具逻辑包括参数验证、数据库操作需要在database/层添加对应的数据表定义。在src/index.ts中导入并注册这个新工具到 MCP 服务器。编写相应的测试。提交 Pull Request。项目的测试覆盖率较高79 个测试在贡献代码前运行npm test确保现有功能不被破坏是很好的习惯。我个人在深度使用 Wyrm 几周后的体会是它带来的最大改变并非某个具体功能的提升而是与 AI 协作的“关系模式”的转变。我不再需要反复进行“背景介绍-解释问题-等待解答”的循环。AI 变成了一个真正有“项目经验”的伙伴。我可以直接说“基于我们上周关于认证系统的讨论现在用户反馈登录慢你有什么排查思路” AI 能立刻调出相关的会话记录、架构决策、甚至当时记录的潜在风险点提供极具上下文相关性的建议。这种连续性极大地提升了思维流动的效率让 AI 从“聪明的打字员”变成了“有记忆的协作者”。虽然 MCP 协议和 Wyrm 都还处于早期阶段但它们所指出的方向——开放、可组合、本地优先的 AI 工具生态——无疑是未来开发者提效的关键。