agentmemory 记忆持久化实战深入 OpenCode/remember斜杠命令与memory_save工具链【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory本文以 agentmemory 仓库中 OpenCode 插件的/remember斜杠命令为切入点完整讲解如何在 OpenCode 环境中把一次性的洞察、决策与经验显式写入跨会话持久记忆从命令安装、五步执行流程到memory_saveMCP 工具的参数语义再到mem::remember底层去重、索引与作用域机制。读完本文你将能够在自己或团队的 OpenCode 工作流中正确使用显式记忆写入并理解一条记忆从斜杠命令到 SQLite 状态库的完整链路。一、命令定位显式记忆写入的入口在 agentmemory 的 OpenCode 集成中/remember与/recall是两个内置斜杠命令参见 plugin/opencode/README.md 的 Slash commands 一节/recall query—— 检索过往会话的观测observations与经验lessons/remember text—— 把一条洞察、决策或学习成果显式保存进长期记忆。/remember的本质是memory_saveMCP 工具的薄封装文档原句为 Wraps thememory_saveMCP tool。它的价值在于agentmemory 的自动捕获通过插件事件钩子能记录会话过程但只有当你明确说这条很重要时它才会被提升为可被后续会话长期检索的记忆memory。/remember就是那个明确说的动作——适用于用户主动要求记住这个、发现了某个 bug、做出了架构决策、或学到了某个项目约定等场景。二、安装与启用/remember命令随 OpenCode 插件一起分发安装分三步完整步骤见 plugin/opencode/README.md启动 agentmemory 服务端npx agentmemory/agentmemory默认监听http://localhost:3111。在~/.config/opencode/opencode.json或项目级.opencode/opencode.json中注册 MCP 服务{ mcp: { agentmemory: { type: local, command: [npx, -y, agentmemory/mcp], enabled: true } } }安装插件并把两个命令复制到 OpenCode 的命令目录mkdir -p ~/.config/opencode/plugins cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/ mkdir -p ~/.config/opencode/commands cp plugin/opencode/commands/recall.md ~/.config/opencode/commands/ cp plugin/opencode/commands/remember.md ~/.config/opencode/commands/命令文件可放在全局~/.config/opencode/commands/或项目级.opencode/commands/目录。重启 OpenCode 或新开会话后/remember即可使用同时插件会在每个会话首轮通过experimental.chat.system.transform把 agentmemory 工具使用说明注入系统提示见 plugin/opencode/agentmemory-capture.ts让 Agent 在合适的时机主动调用memory_save而不只是被动响应/remember。三、用法与执行流程命令语法非常简单/remember [what to remember]紧跟命令的是需要记忆的内容原文例如/remember JWT 刷新令牌必须在双 token 方案里独立轮换不能在 access token 里复用Agent 收到命令后应严格按文档规定的五步流程执行分析需要记忆的内容——从用户的原始表述中提炼出核心洞察、决策或事实提取 25 个可检索概念——使用小写关键词短语优先选择具体术语文档示例优先jwt-refresh-rotation而非宽泛的auth提取记忆涉及的相关文件路径调用memory_save携带四个字段content——要记住的完整文本尽量保留用户原话concepts——提取出的概念列表files——提取出的文件列表无相关文件时传空数组type——从pattern、preference、architecture、bug、workflow、fact六类中选取确认保存成功并把打上的概念标签展示给用户让用户知道后续用哪些检索词可以召回这条记忆。第五步是文档特意强调的收尾动作由于memory_save返回的 JSON 中带有所保存记忆的conceptsAgent 应回显这些标签形成写入—标注—可召回的闭环。四、memory_save参数完整语义memory_save的完整输入模式定义在 src/mcp/tools-registry.ts其字段如下参数类型必填说明contentstring是要记住的洞察、决策或模式全文typestring否记忆类型pattern/preference/architecture/bug/workflow/fact默认factconceptsstring否逗号分隔的关键概念用于检索filesstring否逗号分隔的相关文件路径projectstring否稳定的规范项目标识符如 slug、UUID必须与会话启动时使用的值一致不要使用文件系统路径或临时显示名否则跨机器会静默破坏项目作用域agentIdstring否记忆归属的 Agent 身份设置后agent 作用域的召回只对该 agentId 可见缺省为共享记忆值得注意的是MCP 层把concepts与files定义为逗号分隔字符串服务端 src/mcp/server.ts 在转发前会用split(,)拆分并trim()去除空白、过滤空项再以数组形式传给mem::remember。因此Agent 在调用时既可以直接传 jwt-refresh-rotation, token-rotation, auth 这样的字符串也可以按工具契约传数组——两端均被兼容。另外两个可选字段与多实例/团队场景强相关project保证记忆归属正确项目、跨项目互不串扰agentId支持多 Agent 运行时把记忆隔离到特定角色。五、底层实现mem::remember的完整写入链路memory_saveMCP 工具经由sdk.trigger({ function_id: mem::remember, ... })调用核心实现 src/functions/remember.ts。理解这条链路有助于判断何时该用/remember以及保存后会发生什么。1. 入参校验与类型兜底content为空或非字符串直接返回{ success: false, error: content is required }files、concepts、sourceObservationIds若传入则必须是数组type不在六类枚举内时枚举定义见 src/types.ts静默回退为fact不会报错。2. 相似记忆检测与版本取代保存并非无脑追加。实现先用 BM25 索引取前 50 个候选过滤出mem_前缀的记忆 id再对内容做Jaccard 相似度比较src/functions/remember.ts相似度 0.7判定为新内容取代旧记忆。旧记忆的isLatest被置为false并同时从 BM25 与向量索引中移除——让召回返回一个已过时的旧事实比什么都不返回更糟源码注释原意新记忆继承版本号 1并通过parentId/supersedes字段挂到版本链上同时触发mem::cascade-update级联更新remember.ts。相似度 0.4不足取代阈值作为similarTo提示返回建议调用方后续用memory_update/forget合并。这一机制保证了反复remember同一主题时记忆库不会无限膨胀成重复条目。注意当新旧记忆均带project且不一致时绝不跨项目取代无 project 字段的旧数据视为通配避免历史数据被困。3. 双索引同步与 TTL保存成功后新记忆会同步写入两类检索索引BM25 关键词索引getSearchIndex().add(...)与向量索引vectorIndexAddGuarded(...)。源码注释特别指出remember.ts若省略这一步memory_smart_search与memory_recall在保存后数秒内会返回空结果——这也是/remember之后能立刻被/recall命中的关键。此外ttlDays参数可为记忆设置forgetAfter过期时间到期后自动进入遗忘流程。4. 作用域与审计agentId优先级为请求体显式传入 环境变量AGENT_ID 不作用域旧行为project在保存前统一trim()归一化后续所有比较与存储使用同一清洗值删除路径mem::forget同文件 remember.ts会同步清理记忆、观测、访问日志与两个索引并写入审计记录与/remember构成完整的写入—遗忘闭环。六、六类记忆类型的选择建议type是/remember五步流程中唯一需要主观判断的字段六类枚举来自 src/types.ts 的MemoryType类型适用场景示例pattern项目反复出现的编码模式、惯用法preference用户/团队偏好如错误处理统一用 Result 而非异常architecture架构决策及其理由bug排查过的 bug 根因与规避方法workflow构建、发布、测试等流程约定fact与项目相关的事实性信息选取原则想象未来的你会用什么词条检索这条记忆。pattern、bug、architecture这类强语义类型在 lesson 与 patterns 分析管道中如memory_patterns、memory_consolidate也会被当作结构化信号选择准确能让下游的自动归纳收益更大。七、最佳实践让/remember真正可召回概念宁具体勿宽泛jwt-refresh-rotation优于authrls-policy-rls_enabled优于security。概念是 BM25 检索的直接命中介质精度直接决定召回质量。务必携带文件路径files字段让记忆与memory_file_history、文件富化管道/enrich联动——在未来的会话里当你再次编辑同一文件时与该文件相关的历史决策会自动注入上下文。与/recall结对使用保存后用/recall 概念验证一次确认检索词能命中文档对/recall的要求是绝不幻觉结果只展示 MCP 工具真实返回见 plugin/opencode/commands/recall.md所以命中与否一目了然。善用自动捕获不滥用显式命令普通会话过程由插件自动观察/remember只用于真正值得跨会话沉淀的内容决策、bug、约定避免把记忆库变成日志堆。团队场景显式指定project与agentId多项目、多 Agent 部署时这两字段决定了记忆隔离边界务必使用稳定的规范标识符。结语/remember虽然只是 OpenCode 插件中的一条斜杠命令但它串联起了 agentmemory 的完整显式记忆写入链路命令层负责指令化提取memory_save负责参数契约mem::remember负责校验、去重、版本取代与双索引同步。理解这条链路后你就能在正确的场景用正确的参数保存记忆让跨会话的 Agent 协作真正记得住、找得回。相关源码与配置可进一步查阅 plugin/opencode/commands/remember.md、src/mcp/tools-registry.ts、src/mcp/server.ts 与 src/functions/remember.ts。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考