1. 项目概述为AI编程助手装上“持久化记忆”如果你和我一样日常开发重度依赖Claude Code、Cursor这类AI编程助手那你一定也遇到过这个让人头疼的问题每次新开一个会话AI助手就像得了“健忘症”完全不记得你上一个会话做了什么、项目背景是什么、甚至你刚刚才告诉它的代码规范。这种割裂感让AI助手更像是一个个独立的“一次性工具”而不是一个能伴随你项目成长的智能伙伴。Agent Recall这个开源项目就是为了彻底解决这个问题而生的。简单来说它就是一个运行在你本地的轻量级后台服务专门为AI编程助手提供跨工具、跨会话、跨项目的持久化记忆。它能在Claude Code、Cursor、Codex CLI、Gemini CLI和OpenCode等多个AI编程工具之间建立一份共享的“记忆库”。无论你在哪个工具里和AI助手交互它都能记住你是谁、你的项目在做什么、以及你之前的工作习惯和决策。这个项目的核心价值在于它让AI助手从一个“健忘的临时工”变成了一个“有连续记忆的长期合作伙伴”。想象一下你昨天在Claude Code里花了一下午调试一个复杂的认证模块今天在Cursor里继续开发时AI助手能自动回忆起昨天的调试过程、遇到的坑以及最终的解决方案并以此为基础给你提供建议。这种体验上的提升是颠覆性的。2. 核心设计思路如何为AI构建记忆系统2.1 记忆系统的核心挑战在设计一个AI助手的记忆系统时我们面临几个核心挑战。首先记忆的粒度需要仔细权衡。如果事无巨细都记录不仅存储成本高而且会让AI在回忆时被大量无关信息淹没如果记录得太少关键上下文又会丢失。其次记忆的关联性至关重要。一个修改了config.js的操作可能需要关联到之前对authMiddleware.ts的讨论系统需要能理解这种语义关联。最后跨平台的记忆同步是个工程难题不同AI工具如Claude Code和Cursor有着完全不同的插件架构和上下文注入机制。Agent Recall的解决方案非常巧妙它没有试图去“劫持”或“破解”各个AI工具的内部机制而是采用了基于生命周期钩子Lifecycle Hooks的轻量级适配器模式。这个设计决策是项目成功的关键。2.2 基于钩子的无侵入式捕获所谓“钩子”就是AI工具在执行某些关键操作如开始会话、调用工具、结束会话时暴露给外部系统的一个回调接口。Agent Recall为每个支持的平台Claude Code, Cursor等编写了一个薄薄的适配层通常只有80行左右的TypeScript代码。这个适配层的工作就是“监听”AI工具的生命周期事件。例如当你在Claude Code中执行一个git commit命令时Claude Code的插件系统会触发一个tool_call事件。Agent Recall的Claude Code适配器捕获到这个事件提取关键信息如命令内容、所在项目路径、时间戳等然后通过一个统一的HTTP API运行在localhost:37777发送给核心的记忆服务。这个过程对用户和AI工具本身都是完全透明的没有任何侵入性修改。注意这种钩子机制的成功很大程度上依赖于目标AI工具是否提供了良好的扩展性。幸运的是目前主流的AI编程工具尤其是基于MCP即Model Context Protocol的都在这方面做了不少工作为Agent Recall这类工具的出现铺平了道路。2.3 记忆的分层与结构化捕获到原始事件只是第一步。如果直接把一堆杂乱的git commit、npm install、文件编辑日志扔给AI效果会很差。Agent Recall的核心智慧在于它的AI驱动的记忆压缩与结构化。记忆服务在收到原始观察数据后不会直接存入数据库。它会调用一个配置好的AI模型默认是Claude Haiku因为它快速且便宜让AI对这段观察进行“理解”和“摘要”。例如原始记录可能是“用户执行了npm install express mongoose bcryptjs然后编辑了server.js添加了JWT验证中间件。”经过AI压缩后可能会生成这样的结构化摘要{ action: 初始化后端服务依赖并添加用户认证基础, technologies: [Node.js, Express, Mongoose, JWT], files_affected: [package.json, server.js], intent: 搭建用户登录注册API的后端基础 }这种结构化的记忆不仅体积更小而且语义更清晰在后续需要“回忆”时能更精准地被检索和注入到新会话的上下文中。更重要的是Agent Recall引入了记忆分层的概念全局记忆与你个人工作习惯、常用技术栈、通用编程规范相关的记忆。例如你总是喜欢用Prettier格式化代码、或者你习惯为React组件写TypeScript接口。这些记忆在所有项目中都有效。项目记忆特定于某个代码仓库的记忆。例如项目A使用GraphQL而项目B使用RESTful API项目A的数据库配置在.env.local里而项目B用的是config.yaml。这些记忆只在对应的项目内生效。当开启一个新会话时Agent Recall会合并全局记忆和当前项目的记忆并将合并后的、结构化的上下文信息“悄悄地”注入到AI助手的系统提示词System Prompt或附加上下文Additional Context中。这样AI助手在回应你的第一句话时就已经“知道”了很多背景信息。3. 实战部署与配置详解3.1 环境准备与项目克隆Agent Recall是一个TypeScript项目运行它需要Node.js环境建议v18或以上或者Bun运行时。我个人更推荐使用Bun因为它在启动速度和与TypeScript的集成上表现更好而且项目本身也使用Bun进行测试。首先我们把项目代码拿到本地# 克隆仓库 git clone https://github.com/d-wwei/agent-recall.git cd agent-recall # 安装依赖使用npm或bun均可 npm install # 或者 bun install # 构建项目 npm run build # 或者 bun run build构建过程会使用esbuild将TypeScript代码编译成优化后的JavaScript输出到dist目录。3.2 一键安装与平台适配项目提供了一个非常方便的安装脚本能自动检测你系统里安装了哪些AI编程工具并为其配置相应的钩子。# 运行自动安装脚本 bash scripts/install.sh这个install.sh脚本会做以下几件事检查环境扫描你的系统寻找Claude Code、Cursor、Codex CLI等工具的安装路径和配置文件。配置钩子根据找到的工具将对应的适配器插件或配置文件复制到正确的位置。例如对于Claude Code它会配置MCPModel Context Protocol服务器对于Cursor它会在你的用户目录下创建或修改.cursor/rules/下的规则文件。启动记忆服务尝试启动运行在localhost:37777的Agent Recall核心服务。验证安装对每个检测到的工具进行简单的连通性测试确保钩子配置成功。如果你只想为某个特定工具安装也可以使用单独的脚本# 仅为Claude Code安装通过其插件市场同步 npm run sync-marketplace # 仅为Cursor安装 npm run cursor:install # 为其他CLI工具安装 bash scripts/codex-install.sh # 针对Codex CLI bash scripts/gemini-install.sh # 针对Gemini CLI bash scripts/opencode-install.sh # 针对OpenCode实操心得在运行一键安装脚本前我强烈建议你先关闭所有AI编程工具。因为安装过程会修改它们的配置文件如果工具正在运行可能会导致配置写入失败或需要重启才能生效。安装完成后再重新打开这些工具。3.3 核心服务配置详解安装完成后Agent Recall的核心服务会以后台进程的形式运行并通过HTTP API提供服务。所有配置都集中存储在~/.agent-recall/目录下。最重要的配置文件是~/.agent-recall/settings.json。如果它不存在会在服务首次启动时自动创建。一个典型的配置如下{ worker: { port: 37777, model: claude-3-haiku-20240307, apiKey: your-claude-api-key-here, maxTokens: 4096 }, database: { path: ~/.agent-recall/agent-recall.db, enableChroma: false }, bootstrap: { interviewCompleted: false }, platforms: { claudeCode: {enabled: true}, cursor: {enabled: true} } }worker配置记忆服务的核心参数。model指定用于压缩和总结记忆的AI模型默认的Haiku模型在速度和成本上取得了很好的平衡。apiKey需要你填入自己的Anthropic Claude API密钥。database配置存储。enableChroma控制是否启用Chroma向量数据库进行语义搜索。对于大多数用户保持false使用SQLite的FTS5全文搜索就足够了除非你的记忆库非常庞大且需要复杂的语义查询。bootstrap标识是否已完成初始的“面试”设置。platforms控制为哪些平台启用记忆捕获。注意事项关于API密钥的安全性。settings.json是明文存储的。虽然它在你自己的电脑上但如果你有共享电脑的环境或者担心安全可以考虑通过环境变量来设置API密钥。Agent Recall支持环境变量配置且优先级高于配置文件。例如你可以设置export AGENT_RECALL_WORKER_API_KEYyour-key这样配置文件中就可以留空。3.4 首次运行与引导式面试当你第一次启动一个配置了Agent Recall的AI工具比如打开Claude Code时神奇的事情就发生了。AI助手会“意识到”自己连接到了一个记忆系统并主动发起一个引导式面试。这个面试是双语的英文/中文共三轮旨在快速建立一个基础的“用户画像”和“AI人格”第一轮核心身份。AI会问你希望它如何称呼你你通常扮演什么开发角色全栈、前端、DevOps等以及你希望它以何种风格回应你简洁、详细、鼓励性等。第二轮工作方式。AI会了解你经常处理哪类任务比如调试、写新功能、代码重构、写文档以及你希望它更多扮演什么角色导师、协作者、代码生成器。第三轮AI人格。你可以为这个有记忆的AI助手起个名字定义你们之间的协作氛围如“严谨的伙伴”、“富有创造力的搭档”并确认它已知的运行环境如“通过Agent Recall连接拥有跨会话记忆”。这个过程大约需要3-5分钟。我强烈建议你认真完成这个面试因为它建立的“人格”会持续影响后续所有交互。例如如果你告诉它你是个喜欢详细解释的初学者那么它在后续会话中提供代码片段时就会附带更多的注释和原理说明。这些信息会被持久化到数据库中成为“全局记忆”的一部分。面试完成后记忆系统就正式激活了。你可以通过访问http://localhost:37777来打开Agent Recall的Web查看器这里会实时显示记忆的捕获、压缩和存储过程。4. 核心功能深度解析与使用技巧4.1 会话恢复永不丢失的工作上下文这是Agent Recall最实用的功能。假设你正在用Claude Code开发一个功能中途被会议打断你关闭了窗口。第二天你打开Cursor继续工作。传统模式下你需要向Cursor的AI重新描述一遍昨天的工作进度。而现在Cursor的AI会主动告诉你“早上好根据我们的记忆你昨天在feature/user-auth分支上工作主要完成了JWT令牌的生成与验证中间件。当前的任务是‘实现用户登录API’进度大约70%下一步计划是编写登录接口的单元测试。你是想继续这个任务还是切换到其他任务”这个“会话恢复”功能是如何实现的Agent Recall在后台维护了一个“活跃任务栈”。每当AI助手检测到你开始一项新工作例如你说了“我们来开发登录功能”它会通过钩子通知记忆服务创建一个新的“活跃任务”记录并附上开始时间和初始描述。随后所有与这个任务相关的工具调用、文件修改都会被关联到这个任务ID上。当你结束一个会话时如果任务没有明确标记为完成它会被放入“中断任务队列”。当你开启一个新会话无论是否跨工具记忆服务会检查这个队列并将最相关通常是最近中断的的任务上下文注入到新会话的提示词中。使用技巧为了让任务恢复更精准你可以有意识地使用一些“任务管理”语言。例如明确地说“我们现在开始做【用户个人资料页面】”或“这个【修复登录BUG】的任务完成了”。AI助手能识别这些模式更好地标记任务的开始与结束。4.2 记忆提升从项目经验到全局知识这是Agent Recall最能体现“智能”的一个功能。记忆提升Memory Promotion解决了这样一个问题你在项目A中摸索出的一个最佳实践比如“在本公司项目中使用axios时统一配置baseURL和错误拦截器”如何能自动应用到未来的项目B中Agent Recall的解决方案是基于策略的自动检测与提升。你可以在每个项目中设置不同的同步策略ask询问当检测到可能值得提升为全局知识的记忆时AI会询问你是否要提升。always总是自动将该项目中所有被标记为“决策”或“发现”的记忆提升到全局。never从不该项目记忆始终保持独立。那么系统如何判断一段记忆是否值得提升呢这依赖于AI的总结能力。当一段记忆被压缩时AI会判断其性质。例如“决定使用date-fns而不是moment.js来处理日期因为前者更轻量且支持Tree-shaking”会被标记为一个“技术决策”。而“发现useEffect的依赖数组漏掉了setState函数导致无限循环”则是一个“问题发现”。这些带有特定标签的记忆就是提升的候选者。实操心得对于个人项目我倾向于设置为always让自己所有的好习惯都能积累下来。对于公司团队项目我建议设置为ask并在提升前审视一下这个决策是否具有普适性避免将过于具体的项目配置污染了全局记忆。4.3 记忆检索如何找到“遗忘”的细节当你的记忆库积累了几周甚至几个月后里面可能存储了成千上万条观察记录。如何快速找到你需要的那条信息Agent Recall提供了两种强大的检索方式。1. 关键词检索基于SQLite FTS5这是默认开启的检索方式。FTS5是SQLite的全文搜索扩展模块它能对记忆的“结构化摘要”字段建立倒排索引。你可以在Web查看器的搜索框或者直接通过API进行关键词搜索。时间回溯搜索“昨天 下午 数据库”可以找到昨天下午所有和数据库相关的操作。主题回溯搜索“认证 JWT 中间件”可以找到所有关于认证和JWT的讨论和代码修改。 这种搜索速度快适合已知明确关键词的场景。2. 语义检索基于Chroma向量数据库这是需要手动开启的高级功能。你需要本地运行一个ChromaDB服务通常通过Docker。开启后每条记忆的摘要文本会被转换为向量embedding存储起来。场景当你不记得确切的关键词只能用自然语言描述时。例如你可以搜索“我之前是怎么解决那个用户上传文件大小限制的问题的”。即使你的记忆里没有“文件大小限制”这几个字但语义搜索能根据问题的语义找到你当时修改express.json()配置和multer限制的记录。配置在settings.json中设置enableChroma: true并确保Chroma服务运行在localhost:8000。这会给系统增加一些开销但对于深度用户来说检索体验的提升是显著的。4.4 多平台记忆同步的幕后原理Agent Recall宣称“一份记忆多平台共享”这背后的技术实现很优雅。所有平台适配器在捕获到事件后都通过HTTP请求发送到同一个本地服务localhost:37777。这个服务将所有数据写入同一个SQLite数据库文件~/.agent-recall/agent-recall.db。当一个新的会话在任何平台启动时该平台的适配器会向记忆服务请求上下文。服务执行以下逻辑识别当前项目路径从钩子事件中获取。从数据库中查询a) 全局记忆b) 该项目路径下的所有项目记忆。执行合并项目记忆优先级高于全局记忆。将合并后的记忆列表通过AI模型进行一次轻量的“会话前总结”生成一段连贯的背景描述。将这段描述通过各平台特定的方式注入上下文Claude Code作为additionalContext字段的JSON数据传入。Cursor写入项目目录下的.cursor/rules/agent_recall_context.md文件Cursor会自动读取该文件作为规则。Codex CLI / Gemini CLI整合到systemMessage或AGENTS.md文件中。OpenCode通过system.transform钩子注入。这样无论你从哪个平台访问AI看到的“背景知识”都是一致的真正实现了记忆的共享与同步。5. 常见问题排查与性能优化5.1 安装与启动问题问题1运行bash scripts/install.sh后提示某些平台未找到或配置失败。排查首先检查该工具是否已正确安装。例如对于Cursor检查其是否在应用程序目录或通过命令行which cursor可找到。其次检查是否有权限写入该工具的配置目录如~/.cursor。解决可以尝试手动安装。以Cursor为例手动安装步骤通常是将cursor-hooks/目录下的特定脚本复制到~/.cursor/init或~/.cursor/rules/目录并确保脚本有可执行权限。详细步骤请参考项目内的cursor-hooks/STANDALONE-SETUP.md文件。问题2服务启动失败端口37777被占用。排查运行lsof -i :37777Mac/Linux或netstat -ano | findstr :37777Windows查看哪个进程占用了端口。解决可以终止占用端口的进程或者修改Agent Recall的监听端口。修改~/.agent-recall/settings.json中的worker.port字段例如改为37778并记得重启Agent Recall服务同时也要更新所有平台适配器里配置的服务地址。问题3Web查看器localhost:37777无法打开或没有数据。排查首先确认服务是否在运行。可以检查进程或访问http://localhost:37777/api/health看是否有响应。其次检查浏览器控制台F12是否有网络错误。解决如果服务未运行尝试在项目根目录手动启动npm run start:worker。如果服务运行但无数据检查AI工具的钩子是否生效。在Claude Code中你可以尝试输入“/memory status”命令如果配置了MCP工具看是否能与记忆服务通信。5.2 记忆捕获与注入问题问题4AI助手似乎没有“记住”之前会话的内容。排查确认引导面试是否完成。未完成面试记忆系统不会激活。检查当前项目路径是否一致。记忆是项目作用域的如果你在~/project-a下工作然后切换到~/project-b那么project-a的记忆不会被注入。查看Web查看器是否有新的观察记录被捕获。如果没有说明钩子可能未生效。解决确保你在同一个项目目录下工作。重启你的AI编程工具有时钩子需要重启才能加载。在Claude Code中检查设置里的“MCP服务器”列表看agent-recall是否在列并已启用。问题5记忆注入导致AI的响应变慢或上下文长度超限。排查这是最常见的问题之一。如果积累了太多全局和项目记忆合并后的上下文可能会非常长超出AI模型的令牌限制或者导致AI处理速度变慢。解决定期归档在Web查看器中可以将已完成的、不常访问的会话手动归档。归档的记忆不会被默认注入到新会话但仍可通过搜索找回。调整压缩模型在settings.json中将worker.model换为更快的模型如claude-3-haiku-20240307默认它压缩速度快成本低。优化记忆策略不是所有操作都值得记录。Agent Recall本身会过滤掉ls,echo等简单命令。你可以在代码层面修改适配器逻辑进一步定义过滤规则只记录你认为重要的操作如文件编辑、测试运行、Git操作等。5.3 性能与资源优化问题6Agent Recall服务占用较多内存或CPU。排查这通常发生在启用Chroma向量搜索或者记忆库非常大且频繁进行AI压缩时。解决禁用Chroma除非你极度依赖语义搜索否则在settings.json中保持enableChroma: false。SQLite FTS5的关键词搜索对99%的用例已经足够且资源消耗极低。调整压缩频率默认情况下每次工具调用都会触发压缩。你可以修改核心逻辑改为批量压缩例如每10条观察记录压缩一次但这需要修改源代码。清理旧数据数据库文件agent-recall.db会随时间增长。你可以通过Web查看器删除很早以前的、不重要的会话记录或者直接使用SQLite工具手动清理。问题7遇到API速率限制错误。排查Agent Recall用于压缩记忆的AI模型如Claude Haiku与你的主AI工具如Claude Code共享同一个API密钥和速率限制。如果你同时进行大量编码和记忆压缩可能会触发限制。解决使用更便宜的模型坚持使用claude-3-haiku作为压缩模型它是Anthropic模型中最快、最便宜的。设置延迟压缩项目目前是实时压缩你可以考虑提交一个PR增加一个队列和延迟处理机制在系统空闲时再进行压缩。使用备用API提供商Agent Recall支持OpenRouter等聚合接口。你可以在配置中更换为其他更便宜或限制更少的模型但压缩质量可能会有所变化。5.4 高级调试技巧当遇到复杂问题时可以开启详细日志来帮助定位。在启动服务时设置环境变量DEBUGagent-recall:* npm run start:worker。这会输出非常详细的内部日志包括HTTP请求、数据库操作、AI调用等。直接检查SQLite数据库。使用sqlite3 ~/.agent-recall/agent-recall.db命令打开数据库查看核心表observations存储所有原始的及压缩后的观察记录。tasks存储活跃和已完成的任务。global_memories和project_memories存储提升后的记忆。 通过SQL查询你可以最直接地看到数据是否被正确存储和关联。6. 项目架构演进与自定义扩展Agent Recall的架构设计得非常清晰和模块化大约70-80%的核心代码记忆逻辑、数据库层、AI交互是平台无关的。这意味着为一个新的AI编程工具添加支持理论上只需要编写一个很薄的适配层。6.1 理解核心架构整个系统可以看作一个分层架构平台适配层每个平台一个目录如src/platforms/claude-code/里面包含监听该平台生命周期事件的钩子代码以及如何向该平台注入上下文的逻辑。这层通常只有80-100行代码。HTTP API层一个基于Express.js的HTTP服务器提供18个RESTful端点供所有适配层调用。这是前后端的桥梁。业务逻辑层实现所有核心功能如人格管理、引导面试、任务恢复、记忆压缩与提升等。数据持久层基于SQLite使用FTS5进行全文搜索可选集成Chroma进行向量搜索。6.2 如何为新的AI工具添加支持假设你想为另一个名为“DevMate”的AI编程工具添加支持可以遵循以下步骤研究DevMate的扩展机制它是否有插件系统是否支持MCP是否有配置文件或环境变量可以注入上下文创建适配器模块在src/platforms/下创建devmate/目录。编写一个hooks.ts实现捕获DevMate工具调用事件的方法。编写一个injector.ts实现将记忆上下文写入DevMate的方法可能是修改某个配置文件或调用某个API。编写一个installer.ts提供自动安装脚本将上述钩子部署到DevMate的正确位置。注册新平台在核心的服务注册表中将devmate适配器添加进去使其能够被一键安装脚本识别。测试编写测试用例确保事件捕获和上下文注入能正常工作。6.3 自定义记忆压缩逻辑默认的AI压缩可能不符合你的所有需求。例如你可能希望某些类型的操作如数据库迁移被记录得更详细而另一些如代码格式化则更简略。你可以修改src/core/compression/下的逻辑。核心的压缩函数接收原始的观察数据工具名、参数、输出等然后构造一个提示词Prompt发给AI模型要求其进行总结。你可以修改这个提示词来引导AI产出不同格式或侧重点的摘要。例如你可以要求AI在摘要中必须包含“潜在风险”或“相关文件依赖”字段。6.4 与现有工作流的集成Agent Recall不仅仅是一个被动的记忆工具它可以主动增强你的工作流。与任务管理工具集成你可以扩展API将“活跃任务”同步到你的Jira、Linear或Todoist中。当你在AI中开始一个新功能时一个对应的任务卡片也在你的项目管理工具中创建。生成项目日志/日报利用/api/timeline端点你可以获取某一天或某一周的所有记忆然后通过另一个AI调用将其整理成结构化的项目日报或周报自动发送到团队频道。代码审查助手将记忆系统与Git钩子结合。当提交代码时系统可以自动回顾本次提交相关功能的所有讨论和决策记忆生成一个初步的代码审查意见提醒你可能遗漏的边界情况或与之前决策不一致的地方。经过几周的深度使用Agent Recall已经从我的一个“实验性工具”变成了开发环境中不可或缺的基础设施。它带来的最大改变是消除了与AI协作中的那种“重启感”让对话得以延续让思考得以积累。虽然它目前还是alpha状态在稳定性和性能上还有提升空间但其设计理念和实现方式已经足够成熟为解决AI工具的“记忆失忆”问题提供了一个非常优雅且实用的范本。如果你也厌倦了向AI重复解释你的项目不妨花上半小时部署一下Agent Recall体验一下拥有一个“长期记忆”的AI编程伙伴是什么感觉。