CodeMem：基于MCP为AI编程工具构建持久化项目记忆系统

1. 项目概述为你的AI编程伙伴装上“持久记忆”如果你和我一样每天在Cursor、Claude Code或者Windsurf里和AI结对编程那你肯定遇到过这个烦人的问题每次新开一个会话AI就像得了健忘症完全不记得我们之前讨论过的项目架构、技术选型或者那些你反复强调的代码风格偏好。你不得不一遍又一遍地重复“我们用的是TypeScript”、“这个项目的状态管理是Zustand”、“API层统一用Zod做校验”……这种重复劳动不仅打断心流更让AI助手本应带来的效率提升大打折扣。CodeMem就是为了解决这个问题而生的。简单来说它是一个基于模型上下文协议MCP构建的“长期结对程序员”。它不直接生成代码而是作为一个持久化的记忆后端默默地运行在你的AI编程工具背后。当你和AI讨论技术决策、制定代码规范时CodeMem会自动将这些碎片化的“记忆”——比如“本项目使用Prisma ORM”、“所有错误处理需遵循Try-Catch模式”、“/api路由下的控制器需进行输入验证”——提取出来存储到一个云端同步的“记忆库”中。关键在于当下一次AI需要编写相关代码时它会自动查询这个记忆库把项目特有的上下文“回忆”起来再结合LLM的通用知识生成代码。这意味着你的AI助手终于能记住项目的“灵魂”实现真正的上下文感知编程。无论你是在Cursor里修复一个bug还是在Claude Code中开发新功能只要它们都连接了同一个CodeMem服务器就能共享同一份项目记忆实现无缝的“接力”编程。2. 核心设计思路如何让AI记住“项目灵魂”要让AI拥有长期记忆听起来很酷但实现起来需要一套严谨的设计。CodeMem的设计哲学可以概括为三点自动化、结构化、可演进。它不是简单地做一个聊天记录存档而是构建一个专为软件开发场景优化的记忆系统。2.1 记忆的自动捕获与无感集成最理想的状态是“无感记忆”。你不需要刻意去“保存”什么记忆应该在对话和编码过程中自然沉淀。CodeMem通过MCP协议与你的AI IDE深度集成。当你对AI说“我们决定在这个项目里用Tailwind CSS来统一样式”AI在理解这句话的同时会通过MCP调用CodeMem的save_project_decision工具将这条决策连同时间戳、会话ID一起保存。整个过程是隐形的你只需要像平常一样对话。为了实现这一点CodeMem内置了强大的上下文自动检测能力。它会自动识别你是谁User ID优先读取你的Git配置git config user.name这通常就是你的GitHub用户名。如果你是公司内部用户也可以通过设置GITHUB_TOKEN环境变量让它通过GitHub API来获取准确身份。你在哪个项目Project ID自动获取你当前Git仓库的根目录名作为项目标识。你在用什么工具Platform通过环境变量或父进程名自动检测你使用的是Cursor、Windsurf还是Claude Code。当前会话Session ID每次启动MCP服务器都会生成一个唯一的会话ID如20250315-143022-abc123用于区分不同时间段的编码活动。这套自动检测机制意味着在绝大多数情况下你无需任何手动配置。克隆项目、安装依赖、启动服务器CodeMem就能开始工作自动将记忆归类到正确的用户和项目下。2.2 结构化记忆超越纯文本的“空间锚点”如果记忆只是大段的文本描述那么检索效率会很低尤其是当项目庞大、文件众多时。CodeMem引入了空间记忆Spatial Memory的概念。每一条记忆都可以被“锚定”到具体的文件路径和架构层级上。举个例子当你保存一条决策“在src/api/auth/目录下用户认证使用JWT令牌有效期设置为7天”你可以同时指定affected_files: [‘src/api/auth/controller.ts’ ‘src/api/auth/middleware.ts’]和component_layer: ‘auth’。CodeMem在存储时会在记忆内容前自动添加一个结构化的前缀[files:src/api/auth/controller.tssrc/api/auth/middleware.ts | layer:auth | branch:main | commit:a1b2c3d]这个前缀是纯文本的但它为后续的关键词检索提供了精确的坐标。当你后来在修改src/api/auth/controller.ts文件时AI可以发起一个文件过滤搜索search_project_memory(query“authentication” file_filter“src/api/auth/controller.ts”)。CodeMem会快速返回所有锚定在该文件上的相关记忆过滤掉其他无关的决策极大地提升了上下文检索的精准度和效率。2.3 记忆的生命周期演进、合并与保鲜项目的技术决策不是一成不变的。今天决定用RESTful API明天可能就换成了GraphQL。CodeMem为记忆设计了完整的生命周期管理确保记忆库与项目代码同步演进。1. 决策的迭代与取代Supersession当你改变一个旧决策时比如从MongoDB迁移到PostgreSQL你可以在保存新决策时指定supersedes_ids[“mem_old_mongo_id”]。新记忆会标记为取代了旧记忆。此后在进行搜索时CodeMem会自动过滤掉已被取代的旧记忆确保AI看到的永远是最新、最有效的决策。2. 碎片的合并与提纯Consolidation在项目初期关于“错误处理”的决策可能是分散的一条说“API层要用Try-Catch”另一条说“日志要记录错误堆栈”第三条说“客户端要显示友好错误信息”。时间一长记忆变得碎片化。CodeMem提供了consolidate_memories工具。AI可以先将这些碎片记忆搜索出来进行推理和总结生成一条规范的、完整的“错误处理规范”记忆然后调用合并工具。合并后新的规范记忆被保存而原来的三条碎片记忆会被安全删除。这模拟了人类从具体经验中抽象出通用原则的过程。3. 记忆的保鲜与检测Staleness Detection代码在变记忆可能过时。CodeMem的scan_stale_memories工具能与Git历史联动。你可以让它检查最近N次提交中修改了哪些文件然后扫描所有锚定了这些文件的记忆。它会返回一个列表提示你“这些记忆所关联的文件已被修改相关决策可能需要重新审视。” 这形成了一个“记忆 - 推理 - 行动”的闭环AI检测到记忆可能过时 - 你或AI评估当前代码 - 更新或取代旧记忆让记忆库始终保持鲜活。3. 核心工具详解从保存到检索的全套“记忆手术刀”CodeMem通过13个MCP工具向你的AI助手暴露了完整的内存操作能力。理解每个工具的用途和适用场景能让你和AI的协作如虎添翼。这些工具大致可分为三类写入、检索和管理。3.1 写入类工具如何“种下”一颗记忆的种子写入是记忆的起点。CodeMem将记忆分为几种类型针对性地提供写入工具确保信息以最合适的结构被保存。save_project_decision保存架构决策这是最核心的工具。它采用“双重写入”机制不仅保存你描述决策的原始叙述文本便于人类阅读还会自动提取并保存一个原子化的事实陈述便于AI检索和推理。例如你输入“我们决定使用Prisma作为ORM因为它有良好的类型安全和迁移管理”系统可能会生成原子事实“技术栈数据库ORM使用Prisma”。注意强烈建议在保存决策时尽可能填写affected_files和component_layer参数。这为后续的空间检索奠定了基础。即使当时不确定事后也可以通过更新对话元数据来补充。add_developer_preference记录开发者偏好这用于保存那些个性化的、非项目强制性的编码风格。比如“我偏好使用箭头函数而非function关键字”、“React组件命名使用PascalCase”。这些偏好可以锚定到全局也可以只针对特定文件例如只在*.test.js文件中使用某种断言风格。AI在编写代码时会优先参考这些偏好让生成的代码更符合你的个人口味。add_foresight_todo记录待办与技术债用于记录未来计划、技术债务或改进点。例如“TODO: 在用户服务模块添加缓存层”、“技术债:utils/date.js中的日期处理函数需要重构以支持时区”。为这些条目锚定文件和架构层能让你在后续修改相关代码时自然地回忆起这些待办事项。consolidate_memories合并记忆碎片如前所述这是用于提纯记忆的工具。操作时需谨慎因为它会删除源记忆。一个实用的技巧是在合并前先使用get_memory_details获取源记忆的完整内容确认无误后再执行合并操作。3.2 检索类工具如何在需要时“唤醒”记忆检索是记忆价值的体现。CodeMem提供了多种检索策略以适应不同的查询需求。search_project_memory通用语义搜索这是最常用的检索工具。它接受一个查询字符串并支持三个关键参数scope: 控制搜索范围。session仅当前会话、repo默认本项目所有会话、all当前用户所有项目。在开始一个独立的新功能分支时使用session范围可以避免被旧分支的决策干扰。file_filter: 空间记忆检索的核心。传入文件路径只返回锚定在该文件上的记忆。在编辑单个文件时极其高效。memory_types: 可以指定只搜索某类记忆如[‘decision’ ‘preference’]。search_project_memory_index轻量索引视图当你只需要快速浏览记忆的概览如ID、相关性分数、大概内容而不需要加载完整内容时使用。它消耗的Token更少响应更快适合在对话开始时快速建立上下文。get_memory_timeline与get_memory_details深度查看前者获取某个记忆ID前后相关的记忆用于理解决策的上下文和演变过程。后者获取记忆的完整元数据和内容用于深度分析或合并前的确认。list_recent_memories按时间线浏览以分页的方式列出最近保存的记忆按类型筛选。这有点像浏览项目的“动态墙”适合在项目复盘或新人加入时快速了解项目历史。scan_stale_memories记忆保鲜扫描定期运行此工具例如在完成一个功能分支合并后是保持记忆库健康的好习惯。我通常会设置commits_back10扫描最近10次提交的变更文件然后逐一审查提示为“可能过时”的记忆决定是更新、取代还是保留。3.3 管理类工具维护你的记忆花园记忆库也需要打理好的管理工具让维护工作变得轻松安全。delete_memory删除记忆支持按ID删除单条记忆也支持按类型批量删除如删除所有类型为event_log的测试记忆。关键的安全设计批量删除必须显式传递confirmtrue参数。这防止了AI因误解指令而误删大量重要记忆。get_conversation_meta与update_conversation_meta调整记忆引擎这两个工具用于读取和更新EverMemOS用于记忆提取和检索的元数据。例如你可以更新tags来为当前会话打上“refactoring”或“bug-fix”的标签这会影响记忆提取的侧重点。对于高级用户还可以调整llm_settings来微调记忆总结和检索的LLM行为。大多数时候CodeMem的自动检测和标签如根据affected_files自动识别component_layer已经足够好用。4. 实战配置与连接指南理论说再多不如动手配置一遍。下面我将以最常用的Cursor和Claude Code为例带你完成从零开始的完整配置过程。我的环境是macOSWindows和Linux用户只需注意路径格式的差异。4.1 环境准备与服务器构建首先你需要准备两样东西Node.js环境建议v18以上和一个EverMemOS的API密钥。第一步获取API密钥访问 EverMemOS Cloud 的API页面通常注册后可在控制台找到。创建一个新的API Key权限选择默认的读写权限即可。复制好这串密钥。第二步克隆并构建CodeMem打开终端执行以下命令# 克隆仓库 git clone https://github.com/zhangshi0512/CodeMem.git cd CodeMem # 安装依赖国内用户可考虑使用npm镜像源如 npm config set registry https://registry.npmmirror.com npm install # 构建TypeScript项目生成dist目录 npm run build构建成功后项目根目录下会生成一个dist文件夹里面包含运行所需的index.js文件。第三步配置环境变量在CodeMem项目的根目录下创建一个名为.env的文件。这是最关键的配置步骤。# 必需你的EverMemOS API密钥 EVERMEM_API_KEYemk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 可选GitHub Token仅在企业邮箱与GitHub用户名不一致时需要 # GITHUB_TOKENghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 可选默认记忆检索范围。session repo all。 建议先用默认的repo # MEMORY_SCOPErepo # 可选显式指定平台通常自动检测即可 # PLATFORMcursor # 警告除非有特殊需求否则不要设置USER_ID和GROUP_ID # 留空它们让CodeMem自动从git配置和仓库名中读取这是最准确无感的。 # USER_ID # GROUP_ID重要提示.env文件包含敏感信息务必将其添加到你的.gitignore文件中避免意外提交。4.2 连接至Cursor IDECursor是目前对MCP支持最友好、集成最深的IDE之一。连接过程非常直观。打开Cursor设置在Cursor中使用快捷键Cmd Mac或Ctrl Windows/Linux打开设置。导航到MCP设置在设置面板左侧找到“Features”选项点击展开后选择“MCP Servers”。添加新服务器点击右侧的“ Add new MCP server”按钮。填写服务器配置Name: 起一个容易识别的名字比如codemem。Type: 选择Command。Command: 填写node。Args: 这里需要填写绝对路径。你需要找到之前构建生成的dist/index.js文件的完整路径。例如/Users/yourname/Projects/CodeMem/dist/index.js。小技巧在终端中进入CodeMem的dist目录输入pwd命令然后复制输出的路径再拼接上/index.js。可选环境变量如果你没有在项目根目录创建.env文件或者想覆盖某些设置可以在这里添加。点击“Env”字段下的“Add”按钮输入键值对例如EVERMEM_API_KEY和你的密钥。但更推荐使用.env文件管理更集中。保存并验证点击“Save”。如果配置正确Cursor通常不会有明显提示但当你下次新建一个Chat并输入“我们用什么数据库”时AI应该能调用CodeMem进行搜索。你也可以在Chat中输入“/”查看可用工具列表如果能看到search_project_memory等工具说明连接成功。4.3 连接至Claude Code (CLI)Claude Code作为Anthropic官方的命令行工具其MCP支持是原生且强大的。连接方式是通过命令行添加。打开终端确保你位于任何目录下不需要在CodeMem项目内执行以下命令claude mcp add codemem node /absolute/path/to/CodeMem/dist/index.js -e EVERMEM_API_KEYyour_api_key_here请将/absolute/path/to/替换为你的实际路径将your_api_key_here替换为你的EverMemOS API密钥。连接成功验证 执行命令后会输出类似Added MCP server codemem的提示。之后启动Claude Code开始一个新会话claude在对话中你可以直接测试“搜索一下我们项目中关于身份认证的决策。” 如果AI回复中提及了从CodeMem检索到的信息或者你看到它调用了相关工具即表示配置成功。4.4 连接至WindsurfWindsurf的配置需要通过修改其全局MCP配置文件来完成。找到配置文件macOS/Linux:~/.codeium/windsurf/mcp_config.jsonWindows:%USERPROFILE%\.codeium\windsurf\mcp_config.json如果文件或目录不存在可以手动创建。编辑配置文件用文本编辑器打开该JSON文件添加CodeMem服务器的配置。文件内容应该类似这样{ mcpServers: { codemem: { command: node, args: [/absolute/path/to/CodeMem/dist/index.js], env: { EVERMEM_API_KEY: your_api_key_here } } // ... 你可以在这里配置其他MCP服务器 } }同样请替换路径和API密钥。 3.重启Windsurf保存配置文件后完全关闭并重新启动Windsurf以使配置生效。5. 高效使用模式与避坑指南配置好了工具也连上了怎么用才能发挥最大威力下面分享几种我从日常使用中总结出的高效模式以及一些常见的“坑”和解决方案。5.1 “自动巡航”模式使用MCP提示词最省心的方式是利用CodeMem内置的MCP提示词Prompts。这些是预定义的指令模板告诉AI在何时自动保存和检索记忆。codemem-auto提示词告诉AI在完成一个任务比如实现一个函数、修复一个bug后自动总结并保存相关的决策或待办事项。你不需要说“请保存这个决定”。codemem-context提示词告诉AI在开始编写新代码前先自动搜索相关记忆。比如在你让它“写一个用户登录API”之前它会先去记忆库搜索“auth”、“login”、“api”相关的已有决策。codemem-full提示词以上两者的结合完全体的自动巡航模式。使用方法以Cursor为例 在Cursor的Chat输入框中直接输入“请使用 codemem-full 模式进行本次会话。”发送后AI会确认启用该模式。之后整个会话中它就会自动在编码前后进行记忆的检索和保存实现真正的“无感”上下文延续。实操心得对于全新的项目我建议先不使用自动模式而是手动保存一些核心决策技术栈、目录结构、编码规范。等项目有了一定基础记忆后再开启codemem-full模式体验会流畅得多。5.2 手动精控像管理知识库一样管理记忆自动模式虽好但有时你需要更精细的控制。以下是一些常见的手动操作场景及“说人话”的指令示例场景一制定项目基础规范“我们这是一个Next.js 14项目使用App Router状态管理用ZustandUI库是Shadcn/uiORM用Prisma连接PostgreSQL。请将这些作为项目的基础架构决策保存下来并标记影响文件为根目录的package.json和next.config.js架构层为config。”场景二记录针对特定文件的复杂决策“在src/lib/auth.ts文件中我们决定使用next-authv5进行身份验证配置了Credential Provider和Google OAuth会话策略采用jwt。请保存这个决策并锚定到该文件架构层为auth。”场景三更新过时的决策“我们刚刚把状态管理从Redux Toolkit迁移到了Zustand。请保存这个新决策‘全局状态管理使用Zustand’并且让它取代之前那条关于Redux的记忆ID是mem_xyz789。”场景四在修改文件前快速回顾上下文“我接下来要修改src/components/ui/button.tsx这个文件。请搜索所有与这个文件相关的记忆包括决策、待办事项和我的个人偏好。”场景五定期清理与技术债梳理“列出最近一个月保存的所有类型为foresight_todo的记忆。然后扫描一下最近20次提交看看有没有哪些记忆锚定的文件已经被大幅修改导致记忆可能过时了。”5.3 常见问题与排查技巧在实际使用中你可能会遇到一些小问题。这里记录了我踩过的一些坑和解决方法。问题1AI不调用CodeMem工具或者提示“工具不可用”。检查连接首先确认MCP服务器配置是否正确。在Cursor中可以尝试在设置里暂时禁用再启用codemem服务器。在Claude Code中可以运行claude mcp list查看已注册的服务器状态。检查环境变量确保.env文件中的EVERMEM_API_KEY正确无误且位于CodeMem项目根目录。可以尝试在终端中进入CodeMem目录运行node dist/index.js看是否有明显的错误输出如API密钥无效。检查项目路径确保MCP配置中指向的dist/index.js是绝对路径并且该文件确实存在。问题2记忆检索不到或者返回的结果不相关。确认搜索范围Scope你是否在个人项目A中保存了记忆但当前在团队项目B中搜索默认的repo范围只会搜索当前项目的记忆。如果你需要跨项目搜索个人偏好可以使用scope‘all’。检查文件锚定如果你用file_filter参数进行过滤却搜不到请确认当初保存记忆时是否正确设置了affected_files。可以通过list_recent_memories工具查看最近记忆的原始内容检查其前缀中的文件路径。关键词优化尝试使用更具体、更可能出现在记忆原文中的关键词进行搜索。例如搜索“数据库”可能不如搜索“PostgreSQL”或“Prisma”精准。问题3自动保存的内容质量不高过于琐碎。调整对话元数据尝试使用update_conversation_meta工具为当前会话增加一些标签比如tags: [“architectural” “refactoring”]这可能会影响AI提取记忆时的侧重点使其更关注架构性决策而非琐碎细节。手动干预引导在自动模式下如果AI保存了一条你认为不重要的记忆你可以直接说“这条记忆不太重要请删除它。” AI会调用删除工具。反过来如果AI漏掉了重要决策你可以手动补充“请将我们刚才关于使用React Query做服务端状态缓存的讨论保存为项目决策。”问题4记忆库变得杂乱包含大量测试或无效内容。定期使用scan_stale_memories将其作为每周或每轮迭代结束后的例行操作清理过时的记忆。善用consolidate_memories对于同一个主题的多个碎片化记忆主动进行合并提升记忆库的“信噪比”。严格使用delete_memory对于明确无效的记忆及时删除。批量删除时务必三思并使用confirmtrue。问题5团队协作时记忆会混淆吗CodeMem的记忆是基于USER_ID和GROUP_ID项目ID进行隔离的。默认情况下它使用每个开发者的本地Git配置用户名作为USER_ID。这意味着你和你的队友在同一个项目相同的GROUP_ID中但你们的USER_ID不同因此保存的记忆是彼此独立的。你看不到他的他也看不到你的。这是一种保护隐私和避免冲突的设计。如果团队希望共享一部分核心架构决策目前需要手动同步例如将核心决策保存在项目文档中或由一位成员保存后其他成员通过“学习”这些决策来建立自己的记忆。未来或许可以通过共享USER_ID或团队特性来实现共享记忆但目前版本更侧重于个人长期记忆辅助。