1. 项目概述为AI编程助手装上“持久记忆”如果你和我一样日常重度依赖Claude Code、Cursor这类AI编程助手来写代码、调试、重构那你一定也遇到过这个让人头疼的问题每次新开一个会话AI助手就像得了“健忘症”完全不记得你上一个会话做了什么。你不得不花时间重新描述项目背景、解释当前的文件结构、复述刚刚遇到的错误。这种上下文断裂不仅打断了工作流更浪费了大量宝贵时间。Agent Recall这个开源项目就是为了彻底解决这个问题而生的。你可以把它理解为一个运行在你本地的“记忆中枢”它能在后台默默记录你和AI助手Agent之间的所有交互包括执行的命令、修改的文件、讨论的技术决策然后在下一次会话开始时自动将这些关键上下文“喂”给AI。这样一来你的AI助手就拥有了跨会话、跨项目的“持久记忆”能够真正地“接着上次的活儿继续干”。它的核心价值在于“连续性”。想象一下你下午用Claude Code调试一个复杂的API认证问题晚上换到Cursor里想继续优化Cursor里的AI助手能立刻知道“哦用户正在处理/auth路由的JWT令牌刷新逻辑下午我们刚修复了expiresIn参数解析的时区问题。” 这种无缝衔接的体验才是智能助手应有的样子。Agent Recall目前已经支持了主流的AI编程环境包括Claude Code、Cursor、Codex CLI、Gemini CLI和OpenCode并且让它们共享同一份记忆数据库实现了真正的生态互通。2. 核心设计思路与架构解析2.1 设计哲学从“失忆的临时工”到“有记忆的长期伙伴”传统AI编程助手的工作模式本质上是一个无状态的“临时工”。每次会话都是一次全新的雇佣它没有关于你、关于这个项目、关于过往工作的任何记忆。Agent Recall的设计目标就是通过引入一个持久化的记忆层将这个“临时工”转变为一个“长期伙伴”。这个转变背后有几个关键的设计考量状态外置AI模型本身无法持久化存储信息那么就把状态存储在模型外部。Agent Recall选择使用本地的SQLite数据库作为记忆仓库完全由用户掌控无需担心隐私和数据泄露。观察而非记录它并不录制屏幕或记录所有击键而是通过各平台提供的“钩子”Hooks系统智能地捕获有意义的“观察结果”Observations。比如当AI助手执行了一个git commit -m fix: auth token validation命令或修改了src/auth.js文件这些会被捕获。而像ls、pwd这样的简单命令则会被过滤掉避免记忆被无用信息污染。结构化摘要原始的操作记录是冗长且杂乱的。Agent Recall会利用一个轻量级的AI模型默认是Claude Haiku对捕获的原始观察进行实时压缩和总结生成结构化的摘要。例如将一系列“创建文件A、修改文件B、运行测试C”的操作总结为“实现了用户登录模块的初始框架并进行了冒烟测试”。这极大地提升了记忆的“信息密度”使得在后续会话中注入的上下文更加精炼有效。2.2 系统架构分层与适配Agent Recall的架构清晰且模块化大约70-80%的核心业务逻辑是平台无关的这保证了其良好的可扩展性和维护性。应用层平台适配器 ├── Claude Code 插件 ├── Cursor Shell Hooks ├── Codex CLI Hooks ├── Gemini CLI Hooks └── OpenCode 插件 ↓ (通过HTTP API通信) 服务层Worker HTTP API运行于 localhost:37777 ├── 用户/Agent人格管理 ├── 记忆的捕获、压缩、存储 ├── 会话恢复与任务管理 ├── 记忆的检索与提升 └── 归档与搜索接口 ↓ (操作核心数据) 数据层SQLite 向量数据库 ├── 结构化观察摘要表 ├── 项目与全局记忆分层表 ├── 会话归档与全文搜索索引FTS5 └── 可选ChromaDB向量索引用于语义搜索各层详解平台适配器层这是与各个AI编程工具交互的“薄层”。每个适配器通常只有80行左右的代码其唯一职责就是监听该工具的生命周期事件如会话开始、工具调用结束并将事件发送到中心服务Worker API或者从中心服务获取记忆上下文并按照该工具要求的格式注入。这种设计使得支持一个新平台变得非常快速。Worker服务层这是项目的大脑一个常驻后台的HTTP服务使用Express.js构建。它提供了约18个RESTful端点处理所有核心业务POST /api/observations接收来自各平台的原始观察数据。POST /api/compress调用AI模型对观察进行压缩摘要。GET /api/context根据当前项目查询并组装需要注入的上下文。此外还负责人格引导、任务恢复、记忆提升等高级功能的逻辑。数据持久层以SQLite为核心所有数据存储在~/.agent-recall/agent-recall.db单一文件中。使用FTS5扩展提供对归档会话的快速关键词搜索。同时项目集成了可选的ChromaDB用于实现基于向量相似度的语义搜索例如“查找关于用户认证的工作”即使记忆里没有“认证”这个词也能找到相关的会话。提示这种中心化服务多前端适配的架构是典型的“微内核”模式。它的最大优势是核心功能稳定统一前端适配灵活轻便。当你自己在设计类似的多平台工具时可以借鉴此思路将核心逻辑与UI/交互层彻底解耦。2.3 关键技术选型背后的思考为什么用SQLite而不是其他数据库对于Agent Recall这类桌面端、单用户优先的工具SQLite几乎是完美选择。它无需安装和配置独立的数据库服务器一个文件就是整个数据库备份、迁移极其方便。其FTS5扩展提供了开箱即用的全文搜索能力性能对于个人使用场景绰绰有余。选择SQLite体现了“工具应该适应环境而非让环境适应工具”的务实哲学。为什么默认使用Claude Haiku进行摘要压缩压缩观察是一个高频、低延迟的操作。Haiku模型在速度、成本和效果上取得了最佳平衡。它能在毫秒级内完成摘要且API调用成本极低确保了记忆捕获的实时性不会拖慢主AI助手的工作流。这是一个经典的“合适即最好”的选型案例。采用HTTP API进行内部通信的优势虽然进程间通信IPC方式很多但HTTP API提供了最大的灵活性和可调试性。你可以直接用curl命令测试任何一个端点也可以用任何语言编写脚本与记忆服务交互。这为未来的功能扩展比如开发独立的桌面GUI或第三方集成打开了大门。3. 核心功能深度剖析与实操指南3.1 人格引导系统让AI助手真正“认识你”这是Agent Recall最让我惊艳的功能之一。它不仅仅记忆“事”更试图定义“人”——包括用户你和AI助手它自己。引导式面试流程详解安装并首次启动服务后访问http://localhost:37777你会被引导开始一个三回合的对话式面试第一轮定义用户核心身份问题示例“你希望我怎么称呼你你的主要技术角色是什么例如全栈工程师、数据科学家、学生”你的回答示例“叫我Alex。我是一名专注于Node.js和React的全栈开发目前在做一个SaaS项目。”幕后原理这轮信息会被构造成一个基础的用户画像User Profile存储在数据库中。之后AI助手在生成回复时可以带上“为Alex一位全栈工程师”这样的认知使其回答更具针对性。第二轮明确工作风格与偏好问题示例“你通常希望我在协作中扮演什么角色是严格的代码审查者、富有创造力的搭档还是高效的执行者”你的回答示例“我希望你是一个注重细节的审查者能主动指出潜在的bug和性能问题同时也能提供替代方案。”幕后原理这定义了AI助手的行为基调Agent Persona。这个“人格”会被编码成一段系统提示词System Prompt在每次会话开始时注入。例如提示词中会包含“你是一个注重细节的代码审查者擅长发现潜在问题...”。第三轮为AI助手命名与赋予个性问题示例“你希望给这位有记忆的助手起什么名字你希望我们的协作氛围是怎样的”你的回答示例“就叫它‘CodeMate’吧。协作氛围希望是专业但轻松的像一位靠谱的同事。”幕后原理这完成了AI助手自我意识的构建。它现在有了名字CodeMate和基本的交互风格。这极大地增强了交互的沉浸感和连续性。实操心得这个引导过程至关重要不要草率填写。你定义的“人格”会直接影响后续所有AI助手的输出风格。我建议花点时间思考答案尽量具体。例如与其说“帮我写代码”不如说“我经常需要重构遗留代码请优先考虑可读性和向后兼容性”。3.2 记忆的分层与继承全局记忆 vs. 项目记忆Agent Recall没有采用扁平的记忆池而是设计了一个精巧的两层记忆结构这非常符合软件开发的实际场景。全局记忆存储在所有项目中都通用的知识、偏好和决策。例子“Alex不喜欢使用var声明变量总是偏好const和let。” “Alex在配置ESLint时总是会加上prettier插件。”存储位置数据库中的global_observations表。项目记忆只与特定项目相关的上下文。例子在“电商后端项目”中“我们决定使用Stripe作为支付网关并且已经完成了/api/payment/webhook端点的初步实现。”存储位置数据库中的project_observations表并通过project_id与项目关联。继承与覆盖规则当为一个特定项目查询记忆时Agent Recall会同时拉取全局记忆和该项目下的记忆。如果两者存在冲突比如全局记忆说“喜欢用双引号”但本项目早期决定“使用单引号”则项目记忆优先于全局记忆。这个策略保证了项目特定约定的权威性。如何设置项目Agent Recall会自动根据你当前工作目录的路径来识别项目。通常它会把一个Git仓库的根目录视为一个项目。你也可以在项目的.agent-recall目录下放置一个config.json文件来显式定义项目名称和设置。// 项目根目录/.agent-recall/config.json { projectName: my-awesome-saas-backend, memorySyncPolicy: ask // 记忆提升策略ask, always, never }3.3 记忆提升从项目经验到全局知识这是将记忆系统从“记录仪”升级为“学习系统”的关键功能。当你在一个项目中解决了一个具有普适性的问题时你可以选择将其“提升”到全局记忆。工作流程检测Agent Recall会分析项目记忆尝试识别出可能具有通用价值的模式或决策例如引入了一个新的、高效的错误处理中间件。提示根据你在项目配置中设置的memorySyncPolicy它会采取不同行动ask默认弹出提示询问你是否将某个发现提升为全局知识。always自动提升。never不提升。记录如果你同意提升这条记忆会被复制到全局记忆表并标记其来源项目。之后你在开启任何新项目时都可能从这条全局知识中受益。注意事项自动提升always需谨慎使用。我建议初期使用ask模式手动审核每一次提升。因为有些决策在特定项目上下文里是合理的但可能不适用于其他项目比如在一个小型原型项目中决定不使用TypeScript这就不应提升为全局偏好。3.4 会话恢复与任务管理这是解决“工作被打断”痛点的直接功能。当你关闭AI编程工具或结束一个会话时Agent Recall会将当前正在进行的“活跃任务”标记为暂停。恢复场景示例假设你正在用Claude Code调试一个登录失败的问题任务描述是“排查用户登录时返回500错误的原因”。中途你关掉了Claude Code去开会。 一小时后你打开Cursor开始同一个项目。Cursor的AI助手通过Agent Recall的上下文注入在开场白中就会说“欢迎回来Alex。我们之前正在处理‘排查用户登录时返回500错误的原因’。最新的进展是我们检查了auth.service.js发现validatePassword函数在比较哈希值时存在异步问题。接下来是否需要继续深入这个函数还是想先查看相关的日志”背后的实现任务跟踪Agent Recall会从对话和操作中自动提取或由用户手动指定一个“活跃任务”。状态保存任务名称、最后一条相关观察进度、时间戳被保存在active_tasks表中。上下文组装当新会话在同一项目中被检测到时服务会查询该项目的活跃任务并将任务信息连同最近的相关观察摘要一起打包进注入的上下文里。手动管理任务你也可以通过查看器UI或API主动管理任务POST /api/recovery/active-task手动设置或更新当前任务。POST /api/recovery/complete-task标记任务为完成并将其归档。4. 详细安装、配置与平台集成实战4.1 基础环境准备与项目部署假设你的系统已经安装了Node.js (18) 和 Git。# 1. 克隆仓库 git clone https://github.com/d-wwei/agent-recall.git cd agent-recall # 2. 安装依赖并构建 npm install npm run build # 这会编译TypeScript代码生成dist目录。 # 3. 启动记忆服务Worker npm run worker # 保持这个终端窗口运行服务将在 localhost:37777 启动。 # 首次运行会自动创建 ~/.agent-recall/ 目录和数据库。此时打开浏览器访问http://localhost:37777你应该能看到Agent Recall的Web查看器界面并可能自动开始引导面试流程。4.2 平台集成详解以Claude Code和Cursor为例Claude Code 集成Claude Code 通过其插件市场安装“Claude Mem”插件Agent Recall的前身/基础。Agent Recall的安装脚本会自动处理与这个插件的集成。# 在agent-recall项目根目录下执行 npm run sync-marketplace这个命令会做两件事将编译好的Agent Recall核心模块链接到Claude Code的插件目录。配置Claude Code的additionalContext功能使其在每次会话开始时向localhost:37777的API请求记忆上下文。实操要点确保Claude Code应用已经关闭再运行此命令。安装完成后重启Claude Code。你可以在Claude Code的设置中搜索“memory”或“context”来确认插件已启用。Cursor 集成Cursor的集成方式略有不同它通过Shell Hooks实现。# 在agent-recall项目根目录下执行 npm run cursor:install这个脚本会在你的~/.cursor目录下创建或修改规则文件并设置一个Shell钩子。当Cursor启动时这个钩子会执行一个脚本该脚本会获取当前项目的记忆上下文并将其写入Cursor能读取的一个特定位置通常是.cursor/rules/下的一个文件。验证集成是否成功分别打开Claude Code和Cursor进入同一个Git项目目录。在Claude Code中通过对话或操作让Agent Recall记录一些内容例如让AI助手创建一个文件并解释。关闭Claude Code打开Cursor。在Cursor的AI聊天框中问一个类似“我们之前在这个项目里做过什么”的问题。如果集成成功Cursor的AI应该能提及刚才在Claude Code中记录的内容。4.3 核心配置文件解析Agent Recall的主要配置位于~/.agent-recall/settings.json。首次运行服务后会自动生成。{ workerPort: 37777, databasePath: /Users/yourname/.agent-recall/agent-recall.db, aiModel: { compression: claude-haiku-4-5-20251001, summarization: claude-sonnet-3-5-20241022 }, chroma: { enabled: false, host: localhost, port: 8000 }, platforms: { claudeCode: { enabled: true, contextInjectionMode: automatic }, cursor: { enabled: true } } }aiModel.compression用于压缩观察的模型。Haiku是默认且推荐的速度快、成本低。aiModel.summarization用于生成更复杂摘要或分析的模型某些高级功能使用。Sonnet能力更强但更慢更贵。chroma.enabled是否启用ChromaDB向量搜索。除非你有特定需求否则保持false。SQLite的FTS5关键词搜索对于代码和日志检索已经非常高效。你可以在这里手动启用或禁用某个平台的集成。4.4 Web查看器的使用技巧http://localhost:37777不仅是设置入口更是强大的记忆管理仪表盘。时间线视图按时间顺序展示所有观察记录颜色区分不同项目。点击任何一条记录可以展开看详情和AI生成的摘要。搜索框支持关键词搜索。输入“auth”、“error”、“refactor”可以快速找到相关会话。项目筛选器在侧边栏可以选择只看某一个项目的记忆。任务面板显示当前所有项目的活跃任务和中断的任务队列。设置可以在这里重新运行引导面试、查看系统状态、清理旧数据。一个实用场景当你隔了很久回到一个项目可以先打开查看器在搜索框里输入项目名或关键词快速“重温”上次的工作上下文然后再打开IDE和AI助手效率倍增。5. 常见问题排查与进阶技巧5.1 安装与启动问题问题1运行npm run sync-marketplace或npm run cursor:install时报错“权限被拒绝”或“路径未找到”。原因脚本需要访问IDE的安装目录或配置文件目录可能因权限或自定义安装路径导致。解决手动查找路径找到你的Claude Code或Cursor的用户配置目录。通常位于macOS:~/Library/Application Support/ClaudeCode/或~/.cursor/Linux:~/.config/ClaudeCode/或~/.cursor/Windows:%APPDATA%\ClaudeCode\或%USERPROFILE%\.cursor\手动链接将Agent Recall的dist目录或cursor-hooks目录中的必要文件复制或软链接到上述目录的对应位置。具体需要复制的文件请参考项目scripts/目录下的安装脚本内容。问题2服务启动成功但AI助手无法获取记忆无上下文注入。排查步骤检查服务状态访问http://localhost:37777确保页面能打开查看器有内容。检查IDE插件/钩子在Claude Code设置中确认“Claude Mem”插件已启用。在Cursor中检查~/.cursor/rules/目录下是否存在与agent_recall相关的规则文件。查看日志在运行npm run worker的终端里查看输出或者查看~/.agent-recall/下的日志文件看是否有来自IDE的请求错误。测试API打开终端运行curl http://localhost:37777/api/persona。如果返回你的个人信息JSON则服务正常。再运行curl http://localhost:37777/api/context?projectPath/your/project/path看是否能返回项目上下文。5.2 记忆捕获不完整或不准问题AI助手执行了很多操作但查看器里记录很少。原因Agent Recall有内置的过滤器会跳过它认为“无价值”的简单工具调用如ls,pwd,echo只捕获可能产生持久影响的“观察”如文件编辑、Git操作、测试运行、包安装等。调整目前过滤逻辑是硬编码的旨在平衡记忆价值和噪音。如果你认为重要操作被遗漏可以查阅项目源码中关于“工具调用过滤”的部分但修改需要一定的开发能力。对于绝大多数开发场景默认的过滤策略是合理的。问题AI生成的摘要太笼统或不准。原因摘要质量依赖于压缩模型默认Haiku的理解能力。对于非常复杂或模糊的操作序列摘要可能不够精确。解决在查看器中你可以手动编辑某条观察的摘要使其更准确。考虑在settings.json中将aiModel.compression临时换为更强大的模型如claude-sonnet-...但这会增加延迟和成本。更适合用于事后批量重摘要关键会话。5.3 性能与资源管理问题Agent Recall服务会拖慢我的系统或IDE吗解答Worker服务本身非常轻量内存占用通常在几十MB。主要的性能影响可能来自AI压缩调用每次捕获观察后的实时压缩会调用Claude API。使用Haiku模型且网络正常时延迟极低1秒且发生在后台不影响前台操作。数据库增长长期使用后SQLite数据库文件会变大。如果发现搜索变慢可以定期通过查看器UI的“设置”进行旧数据归档或清理。建议对于性能敏感的机器可以调整settings.json增加压缩的延迟批次处理或者更激进地过滤观察类型。但普通开发环境无需担心。5.4 进阶使用技巧技巧1利用项目配置实现环境隔离如果你同时开发多个技术栈迥异的项目比如一个Go微服务和一个React前端可以为它们创建不同的.agent-recall/config.json文件指定不同的memorySyncPolicy如never防止两个项目的技术决策互相污染全局记忆。技巧2手动创建高质量“种子记忆”在开始一个新项目时不要完全依赖自动捕获。你可以主动通过查看器的“添加观察”功能或直接向/api/observations发送API请求手动插入一些关键的“种子记忆”。例如插入一条观察“本项目决定使用pnpm作为包管理器并采用Monorepo结构所有包位于packages/目录下。” 这能让AI助手从一开始就建立在正确的认知基础上。技巧3结合脚本实现自动化由于所有功能都暴露为HTTP API你可以编写Shell脚本或使用工具如curl、httpie来与记忆服务交互。示例在每天下班前运行一个脚本自动将当前活跃任务标记为“暂停”并生成一份今日工作摘要。# 假设你的项目路径是 /Projects/MyApp PROJECT_PATH/Projects/MyApp curl -X POST http://localhost:37777/api/recovery/complete-task \ -H Content-Type: application/json \ -d {\projectPath\: \$PROJECT_PATH\, \note\: \End of day auto-pause\}技巧4处理多分支开发Agent Recall的记忆是基于项目路径的。如果你在同一个项目里切换Git分支由于路径没变记忆是共享的。这通常是有益的分支间的知识可复用。但如果你希望严格隔离一个变通方法是在切换分支后临时在项目根目录创建一个软链接到另一个路径然后在新的路径下打开IDEAgent Recall会将其视为一个“新项目”。不过这需要更复杂的流程管理。