尧图网站建设 
agentmemory remember 技能实战指南用 memory_save 持久化决策、代码坑与经验教训【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory本篇指南以 agentmemory 的remember技能及其配套工作示例plugin/skills/remember/EXAMPLES.md为骨架讲解如何通过memory_save工具把 AI 编码 Agent 在会话中的关键决策、代码级坑与操作约束写入长期记忆并通过 concept 标签确保未来能被memory_smart_search精准召回。读完本文你将掌握memory_save三个字段content/concepts/files的完整语义、三个经典保存场景的逐行演练、底层记忆版本链supersession的工作原理以及搭配 recall、forget、lesson、memory-discipline 等技能的正确记忆工作流。一、remember 技能在 agentmemory 中的定位agentmemory 为 AI 编码 Agent 提供基于真实世界基准的持久化记忆。在 plugin/skills/remember/SKILL.md 中remember被定义为一个用户可直接触发的技能user-invocable: true当用户说remember thissave thisnote thatdont forget或者希望把知识保留到未来会话时Agent 就应调用它。它的触发模板非常直接The user wants to save this to long-term memory: $ARGUMENTSremember是 agentmemory 记忆循环的写入端与读取端recall调用memory_smart_search成对出现。技能文档里明确给出了最小可用示例memory_save { content: We rotate JWT refresh tokens on every use; the old token is revoked server-side in auth/refresh.ts., concepts: jwt-refresh-rotation, token-revocation, auth-flow, files: src/auth/refresh.ts }预期输出Saved memory abc12345 with 3 concepts: jwt-refresh-rotation, token-revocation, auth-flow.二、三个实战示例从请求到保存的完整闭环plugin/skills/remember/EXAMPLES.md 给出了三个由浅入深的完整示例覆盖了日常开发中最常见的记忆保存场景。下面逐一展开并结合仓库源码说明每个字段背后的实际语义。示例 1保存一个技术决策用户请求Remember that we decided to drop Redis and use the iii-engine state store for session caching.Agent 调用memory_save { content: We decided to drop Redis and use the iii-engine state store for session caching to remove a moving part., concepts: session-caching, iii-state-store, dropped-redis, files: }工具响应{ id: 7f3a9c21, concepts: [session-caching, iii-state-store, dropped-redis], saved: true }向用户呈现Saved. Tagged itsession-caching,iii-state-store,dropped-redis, so a later recall on caching or Redis will surface this decision.这个例子的要点在于content保留了用户的原始措辞并补上了决策动机to remove a moving part让未来的自己不仅知道选了 iii-engine还知道为什么选它concepts用了三个具体且可检索的标签覆盖了主题session-caching、方案iii-state-store和反方向dropped-redis这样无论未来以caching还是Redis作为检索词都能命中没有关联文件files传空字符串。示例 2保存一个代码专属的坑用户请求Save this: the rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide.Agent 调用memory_save { content: The rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide., concepts: rate-limiter, per-ip-bug, shared-ip-collision, files: src/middleware/limit.ts }工具响应{ id: b21d004e, concepts: [rate-limiter, per-ip-bug, shared-ip-collision], saved: true }向用户呈现Saved memoryb21d004ereferencingsrc/middleware/limit.ts. Concepts:rate-limiter,per-ip-bug,shared-ip-collision.这个例子的核心是文件关联这类实现细节导致的坑最容易被遗忘而files字段把它钉在了具体源码文件上未来任何涉及middleware/limit.ts的记忆检索都可能把它带出来。示例 3模糊请求时的引导式保存用户请求Remember this for later.Agent 处理方式先向用户追问一次实质内容得到答案后再保存。追问后的保存调用memory_save { content: Staging deploys must run the migration job before the app rollout, never after., concepts: staging-deploy, migration-ordering, rollout-sequence, files: }向用户呈现把确认信息连同 concepts 一并回显即把标签原样念给用户听让用户清楚这条记忆将来用什么词可以找回。这个例子的要点是当请求内容模糊时只追问一次拿到实质内容即可保存不要把对话拖长同时无论何时保存都要把 concepts 回显给用户这是技能清单Checklist的硬性要求Confirmation echoes the exact concepts tagged。三、memory_save 字段语义与底层实现三个示例反复使用的memory_save是 MCP 层暴露的工具名。在 src/mcp/server.ts 中memory_save端点会把请求转发给内部函数mem::remember实现在 src/functions/remember.ts。其核心字段如下字段类型语义说明contentstring必填记忆正文服务端校验非空保留用户措辞而非转述concepts逗号分隔字符串或数组检索标签MCP 层按逗号拆分并 trim技能约定 2-5 个、全小写、具体优先files逗号分隔字符串或数组关联文件路径绝对路径或仓库相对路径无则留空typestring可选记忆类型合法值pattern、preference、architecture、bug、workflow、fact缺省为factagentIdstring可选Agent 作用域多 Agent 场景下把记忆写入对应 Agent 的作用域见 src/functions/remember.tsprojectstring可选项目作用域用于跨项目隔离与超集成的项目判定联动ttlDaysnumber可选过期时间大于 0 时写入forgetAfter实现记忆自动过期在底层 src/functions/remember.ts 中一条记忆会被构造成包含idgenerateId(mem)生成、title正文前 80 个字符且通过safeSlice避免截断 emoji/CJK 扩展字符产生孤立高代理项、concepts、files、strength: 7、origin.channel: agent等字段的完整 Memory 对象。保存成功后记忆会同步写入两个检索索引BM25 索引通过getSearchIndex().add(memoryToObservation(memory))写入src/functions/remember.ts保证memory_smart_search能立刻命中——源码注释特别提到缺失这一步会导致保存数秒后检索仍返回空的历史问题向量索引通过vectorIndexAddGuarded(...)写入src/functions/remember.ts索引文本为title content供向量检索使用。这正是 recall 技能中memory_smart_search能同时做 BM25 向量 图检索的原因见 plugin/skills/recall/SKILL.md。四、记忆版本链重复保存时的 supersession 机制技能工作流第 6 步规定要更新一个事实直接保存修正后的版本即可——近似重复的内容会**取代supersede**旧记录旧记录离开检索但仍留在版本链中。这一规则在源码层有精确实现保存时会用 Jaccard 相似度把新内容与候选记忆逐一比较候选来自 BM25 索引的 Top 50 命中索引不可用时回退全量扫描见 src/functions/remember.ts相似度 0.7判定为重复新记忆获得version 1、parentId指向旧记忆、supersedes: [旧id]旧记忆被标记isLatest: false并从 BM25 与向量索引中移除src/functions/remember.ts——旧版本留在 KV 中供版本链查看但不再作为当前事实被召回相似度在0.4 0.7之间时不会取代而是把最接近的一条作为similarTo提示返回供调用方决定是否手动合并src/functions/remember.ts跨项目保护当新记忆与旧记忆都带project且不一致时绝不进行取代src/functions/remember.ts。这一行为有专门的测试用例验证见 test/remember-supersede-recall.test.ts测试确认取代发生时旧记忆从搜索索引消失、新记忆进入索引、version递增并验证了similarTo提示的相似度区间以及索引候选在记忆量大时仍能定位取代目标。五、技能核心方法论Why、Workflow、Anti-patterns、Checklist除了示例plugin/skills/remember/SKILL.md 还定义了这套保存动作背后的完整方法论是正确使用该技能的行为规范。Why为什么这样设计一条记忆的价值取决于能被什么词检索到。用具体 concept 打标签未来recall才能命中同时要保留用户自己的措辞避免转述引入偏差。Workflow六步标准流程从$ARGUMENTS中提炼核心洞察、决策或事实抽取2-5 个全小写的 concept 短语具体优于宽泛jwt-refresh-rotation胜过auth抽取引用的文件路径绝对路径或仓库相对路径没有则为空调用memory_save传入content、concepts逗号分隔字符串和files逗号分隔字符串多 Agent 场景额外传agentId让记忆落入正确的 Agent 作用域确认保存结果并回显 concepts让用户知道检索词更新事实时直接保存修正版近似重复内容会取代旧记录旧记录离开检索但保留在版本链中。Anti-patterns反模式错误concepts: stuff, code, notes—— 宽泛标签将来谁也无法命中正确concepts: jwt-refresh-rotation, token-revocation—— 具体、可检索。Checklist保存前自检清单content保留用户措辞而非转述concepts 具体、全小写、2-5 个文件路径是真实引用不是猜测确认信息回显了所打的确切标签。六、记忆写入的正确时机与 memory-discipline 配合remember是用户显式触发时的保存入口而在没有显式指令时是否主动保存由 plugin/skills/memory-discipline/SKILL.md 这一会话循环纪律来约束。它规定了三类判定任务开始时读代码之前先做一次项目作用域的memory_smart_search命中省去重新发现未命中只损失一次调用任务进行中每当决策落定或坑被解决立刻memory_save且要同时保存决策与原因——会话结束时的批量补记会丢失当时的理由用户纠正你的方法时保存的是 lesson教训而非 memory因为 lessons 带置信度并在相似工作前浮出而 memories 只承载事实。该技能的保存资格判定也值得遵守值得保存的是已落定的决策及其理由、调试中发现的非显然约束、仓库中无法推导出的环境事实应该跳过的是代码里能读到的内容、瞬时状态、密钥、步骤流水账hooks 已经自动捕获了。七、配对的读取端与纠错端remember保存的内容由它的搭档们消费recall读取端调用memory_smart_search做混合检索把结果按会话分组、按 importance 排序呈现空结果时建议 2-3 个替代检索词并停止绝不凭空编造见 plugin/skills/recall/SKILL.md 及其示例 plugin/skills/recall/EXAMPLES.md。示例 1 中保存的 Drop Redis for iii state store 决策在 recall 侧就以sessionId: 7f3a9c21, importance: 8的形态被检索回来形成完整的写读闭环forget纠错端删除误存的记忆底层调用mem::forget会同步清理 BM25/向量索引与访问日志见 src/functions/remember.tslesson行为规则承载来自纠正的行为规则与记忆facts职责分离。八、故障排查memory_save 不可用时的降级路径如果memory_save这个 MCP 工具没有出现说明 stdio MCP shim 未启动。按 plugin/skills/_shared/TROUBLESHOOTING.md 的顺序排查在宿主中运行/plugin list确认agentmemory显示为 enabled重启宿主——插件的.mcp.json只在启动时读取新安装或重新启用的插件不会在会话中途注册工具检查/mcp确认agentmemory服务器显示为 live 连接。若 MCP 工具始终不可用但守护进程在运行可直接调用 REST API 降级设置AGENTMEMORY_URL默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才携带Authorization: Bearer $AGENTMEMORY_SECRET默认的 localhost 守护进程是开放的多余的请求头反而会被拒绝。remember对应的 REST 端点为POST /agentmemory/rememberrecall对应POST /agentmemory/smart-search。注意守护进程同样只在启动时读取.mcp.json任何端口或鉴权变更都需要重启才会在两个传输层生效。结语从 plugin/skills/remember/EXAMPLES.md 的三个示例出发可以看到 agentmemory 的remember技能是一套完整、可执行的记忆写入规范content保真原始决策与动机concepts决定未来的可检索性files把记忆钉在真实代码上底层 src/functions/remember.ts 通过 BM25 向量双索引写入与 0.7 阈值的版本链取代机制保证保存即见、旧版不污染检索。配合recall的读取端与memory-discipline的时机纪律就能让 Agent 的记忆真正跨越会话生效。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 agentmemory remember 技能实战指南：用 memory_save 持久化决策、代码坑与经验教训
agentmemory remember 技能实战指南用 memory_save 持久化决策、代码坑与经验教训【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory本篇指南以 agentmemory 的remember技能及其配套工作示例plugin/skills/remember/EXAMPLES.md为骨架讲解如何通过memory_save工具把 AI 编码 Agent 在会话中的关键决策、代码级坑与操作约束写入长期记忆并通过 concept 标签确保未来能被memory_smart_search精准召回。读完本文你将掌握memory_save三个字段content/concepts/files的完整语义、三个经典保存场景的逐行演练、底层记忆版本链supersession的工作原理以及搭配 recall、forget、lesson、memory-discipline 等技能的正确记忆工作流。一、remember 技能在 agentmemory 中的定位agentmemory 为 AI 编码 Agent 提供基于真实世界基准的持久化记忆。在 plugin/skills/remember/SKILL.md 中remember被定义为一个用户可直接触发的技能user-invocable: true当用户说remember thissave thisnote thatdont forget或者希望把知识保留到未来会话时Agent 就应调用它。它的触发模板非常直接The user wants to save this to long-term memory: $ARGUMENTSremember是 agentmemory 记忆循环的写入端与读取端recall调用memory_smart_search成对出现。技能文档里明确给出了最小可用示例memory_save { content: We rotate JWT refresh tokens on every use; the old token is revoked server-side in auth/refresh.ts., concepts: jwt-refresh-rotation, token-revocation, auth-flow, files: src/auth/refresh.ts }预期输出Saved memory abc12345 with 3 concepts: jwt-refresh-rotation, token-revocation, auth-flow.二、三个实战示例从请求到保存的完整闭环plugin/skills/remember/EXAMPLES.md 给出了三个由浅入深的完整示例覆盖了日常开发中最常见的记忆保存场景。下面逐一展开并结合仓库源码说明每个字段背后的实际语义。示例 1保存一个技术决策用户请求Remember that we decided to drop Redis and use the iii-engine state store for session caching.Agent 调用memory_save { content: We decided to drop Redis and use the iii-engine state store for session caching to remove a moving part., concepts: session-caching, iii-state-store, dropped-redis, files: }工具响应{ id: 7f3a9c21, concepts: [session-caching, iii-state-store, dropped-redis], saved: true }向用户呈现Saved. Tagged itsession-caching,iii-state-store,dropped-redis, so a later recall on caching or Redis will surface this decision.这个例子的要点在于content保留了用户的原始措辞并补上了决策动机to remove a moving part让未来的自己不仅知道选了 iii-engine还知道为什么选它concepts用了三个具体且可检索的标签覆盖了主题session-caching、方案iii-state-store和反方向dropped-redis这样无论未来以caching还是Redis作为检索词都能命中没有关联文件files传空字符串。示例 2保存一个代码专属的坑用户请求Save this: the rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide.Agent 调用memory_save { content: The rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide., concepts: rate-limiter, per-ip-bug, shared-ip-collision, files: src/middleware/limit.ts }工具响应{ id: b21d004e, concepts: [rate-limiter, per-ip-bug, shared-ip-collision], saved: true }向用户呈现Saved memoryb21d004ereferencingsrc/middleware/limit.ts. Concepts:rate-limiter,per-ip-bug,shared-ip-collision.这个例子的核心是文件关联这类实现细节导致的坑最容易被遗忘而files字段把它钉在了具体源码文件上未来任何涉及middleware/limit.ts的记忆检索都可能把它带出来。示例 3模糊请求时的引导式保存用户请求Remember this for later.Agent 处理方式先向用户追问一次实质内容得到答案后再保存。追问后的保存调用memory_save { content: Staging deploys must run the migration job before the app rollout, never after., concepts: staging-deploy, migration-ordering, rollout-sequence, files: }向用户呈现把确认信息连同 concepts 一并回显即把标签原样念给用户听让用户清楚这条记忆将来用什么词可以找回。这个例子的要点是当请求内容模糊时只追问一次拿到实质内容即可保存不要把对话拖长同时无论何时保存都要把 concepts 回显给用户这是技能清单Checklist的硬性要求Confirmation echoes the exact concepts tagged。三、memory_save 字段语义与底层实现三个示例反复使用的memory_save是 MCP 层暴露的工具名。在 src/mcp/server.ts 中memory_save端点会把请求转发给内部函数mem::remember实现在 src/functions/remember.ts。其核心字段如下字段类型语义说明contentstring必填记忆正文服务端校验非空保留用户措辞而非转述concepts逗号分隔字符串或数组检索标签MCP 层按逗号拆分并 trim技能约定 2-5 个、全小写、具体优先files逗号分隔字符串或数组关联文件路径绝对路径或仓库相对路径无则留空typestring可选记忆类型合法值pattern、preference、architecture、bug、workflow、fact缺省为factagentIdstring可选Agent 作用域多 Agent 场景下把记忆写入对应 Agent 的作用域见 src/functions/remember.tsprojectstring可选项目作用域用于跨项目隔离与超集成的项目判定联动ttlDaysnumber可选过期时间大于 0 时写入forgetAfter实现记忆自动过期在底层 src/functions/remember.ts 中一条记忆会被构造成包含idgenerateId(mem)生成、title正文前 80 个字符且通过safeSlice避免截断 emoji/CJK 扩展字符产生孤立高代理项、concepts、files、strength: 7、origin.channel: agent等字段的完整 Memory 对象。保存成功后记忆会同步写入两个检索索引BM25 索引通过getSearchIndex().add(memoryToObservation(memory))写入src/functions/remember.ts保证memory_smart_search能立刻命中——源码注释特别提到缺失这一步会导致保存数秒后检索仍返回空的历史问题向量索引通过vectorIndexAddGuarded(...)写入src/functions/remember.ts索引文本为title content供向量检索使用。这正是 recall 技能中memory_smart_search能同时做 BM25 向量 图检索的原因见 plugin/skills/recall/SKILL.md。四、记忆版本链重复保存时的 supersession 机制技能工作流第 6 步规定要更新一个事实直接保存修正后的版本即可——近似重复的内容会**取代supersede**旧记录旧记录离开检索但仍留在版本链中。这一规则在源码层有精确实现保存时会用 Jaccard 相似度把新内容与候选记忆逐一比较候选来自 BM25 索引的 Top 50 命中索引不可用时回退全量扫描见 src/functions/remember.ts相似度 0.7判定为重复新记忆获得version 1、parentId指向旧记忆、supersedes: [旧id]旧记忆被标记isLatest: false并从 BM25 与向量索引中移除src/functions/remember.ts——旧版本留在 KV 中供版本链查看但不再作为当前事实被召回相似度在0.4 0.7之间时不会取代而是把最接近的一条作为similarTo提示返回供调用方决定是否手动合并src/functions/remember.ts跨项目保护当新记忆与旧记忆都带project且不一致时绝不进行取代src/functions/remember.ts。这一行为有专门的测试用例验证见 test/remember-supersede-recall.test.ts测试确认取代发生时旧记忆从搜索索引消失、新记忆进入索引、version递增并验证了similarTo提示的相似度区间以及索引候选在记忆量大时仍能定位取代目标。五、技能核心方法论Why、Workflow、Anti-patterns、Checklist除了示例plugin/skills/remember/SKILL.md 还定义了这套保存动作背后的完整方法论是正确使用该技能的行为规范。Why为什么这样设计一条记忆的价值取决于能被什么词检索到。用具体 concept 打标签未来recall才能命中同时要保留用户自己的措辞避免转述引入偏差。Workflow六步标准流程从$ARGUMENTS中提炼核心洞察、决策或事实抽取2-5 个全小写的 concept 短语具体优于宽泛jwt-refresh-rotation胜过auth抽取引用的文件路径绝对路径或仓库相对路径没有则为空调用memory_save传入content、concepts逗号分隔字符串和files逗号分隔字符串多 Agent 场景额外传agentId让记忆落入正确的 Agent 作用域确认保存结果并回显 concepts让用户知道检索词更新事实时直接保存修正版近似重复内容会取代旧记录旧记录离开检索但保留在版本链中。Anti-patterns反模式错误concepts: stuff, code, notes—— 宽泛标签将来谁也无法命中正确concepts: jwt-refresh-rotation, token-revocation—— 具体、可检索。Checklist保存前自检清单content保留用户措辞而非转述concepts 具体、全小写、2-5 个文件路径是真实引用不是猜测确认信息回显了所打的确切标签。六、记忆写入的正确时机与 memory-discipline 配合remember是用户显式触发时的保存入口而在没有显式指令时是否主动保存由 plugin/skills/memory-discipline/SKILL.md 这一会话循环纪律来约束。它规定了三类判定任务开始时读代码之前先做一次项目作用域的memory_smart_search命中省去重新发现未命中只损失一次调用任务进行中每当决策落定或坑被解决立刻memory_save且要同时保存决策与原因——会话结束时的批量补记会丢失当时的理由用户纠正你的方法时保存的是 lesson教训而非 memory因为 lessons 带置信度并在相似工作前浮出而 memories 只承载事实。该技能的保存资格判定也值得遵守值得保存的是已落定的决策及其理由、调试中发现的非显然约束、仓库中无法推导出的环境事实应该跳过的是代码里能读到的内容、瞬时状态、密钥、步骤流水账hooks 已经自动捕获了。七、配对的读取端与纠错端remember保存的内容由它的搭档们消费recall读取端调用memory_smart_search做混合检索把结果按会话分组、按 importance 排序呈现空结果时建议 2-3 个替代检索词并停止绝不凭空编造见 plugin/skills/recall/SKILL.md 及其示例 plugin/skills/recall/EXAMPLES.md。示例 1 中保存的 Drop Redis for iii state store 决策在 recall 侧就以sessionId: 7f3a9c21, importance: 8的形态被检索回来形成完整的写读闭环forget纠错端删除误存的记忆底层调用mem::forget会同步清理 BM25/向量索引与访问日志见 src/functions/remember.tslesson行为规则承载来自纠正的行为规则与记忆facts职责分离。八、故障排查memory_save 不可用时的降级路径如果memory_save这个 MCP 工具没有出现说明 stdio MCP shim 未启动。按 plugin/skills/_shared/TROUBLESHOOTING.md 的顺序排查在宿主中运行/plugin list确认agentmemory显示为 enabled重启宿主——插件的.mcp.json只在启动时读取新安装或重新启用的插件不会在会话中途注册工具检查/mcp确认agentmemory服务器显示为 live 连接。若 MCP 工具始终不可用但守护进程在运行可直接调用 REST API 降级设置AGENTMEMORY_URL默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才携带Authorization: Bearer $AGENTMEMORY_SECRET默认的 localhost 守护进程是开放的多余的请求头反而会被拒绝。remember对应的 REST 端点为POST /agentmemory/rememberrecall对应POST /agentmemory/smart-search。注意守护进程同样只在启动时读取.mcp.json任何端口或鉴权变更都需要重启才会在两个传输层生效。结语从 plugin/skills/remember/EXAMPLES.md 的三个示例出发可以看到 agentmemory 的remember技能是一套完整、可执行的记忆写入规范content保真原始决策与动机concepts决定未来的可检索性files把记忆钉在真实代码上底层 src/functions/remember.ts 通过 BM25 向量双索引写入与 0.7 阈值的版本链取代机制保证保存即见、旧版不污染检索。配合recall的读取端与memory-discipline的时机纪律就能让 Agent 的记忆真正跨越会话生效。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考