agentmemory remember 技能实战把洞察、决策与经验可靠地写入 AI 智能体的长期记忆【免费下载链接】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/SKILL.md展开讲解如何让 AI 编码智能体在用户说出记住这个保存一下别忘了时把洞察、决策和学习经验以结构化、可检索的方式写入长期记忆并保证未来任意会话都能通过recall找回。读完本文你将掌握memory_save的完整参数语义、概念标签的提取规范、文件路径关联方式、版本迭代替换机制以及 MCP 工具不可用时的 REST 兜底方案——既能照着做也能从源码层面理解其底层实现。一、技能定位remember是什么、什么时候触发在 agentmemory 中remember是一个可被用户直接调用的技能user-invocable: true。它的职责非常聚焦把一段文本写入长期记忆存储并通过可搜索的概念标签concepts让未来的recall能命中它。技能头部声明plugin/skills/remember/SKILL.md给出了触发条件--- name: remember description: Save an insight, decision, or learning to agentmemorys long-term storage with searchable concept tags. Use when the user says remember this, save this, note that, dont forget, or wants to preserve knowledge for future sessions. argument-hint: [what to remember] user-invocable: true ---当用户说出 remember this、save this、note that、dont forget 等意图或明确表示要为未来会话保留知识时Agent 就把用户的原始请求注入模板The user wants to save this to long-term memory: $ARGUMENTS注意这里的定位差异remember保存的是事实、决策、坑点facts / decisions / gotchas而行为规则类的修正应该走lesson技能被动观察式的自动记录则由memory-discipline决定。技能文档的 See also 一节明确说明了边界recall检索本技能保存的内容本技能的对偶操作forget删除误保存的记忆lesson由修正产生的行为规则记忆只存放事实memory-discipline决定何时主动保存。二、快速上手一次标准的memory_save调用技能的 Quick start 给出了最典型的调用形态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.可以看到memory_save接受三个核心字段字段类型含义contentstring必填要长期保存的洞察、决策或事实原文concepts逗号分隔字符串检索用的概念标签2–5 个、小写、具体化files逗号分隔字符串关联的源码文件路径绝对路径或仓库相对路径无则留空对照 MCP 工具注册表src/mcp/tools-registry.tsmemory_save的完整输入模式还包含更多可选参数后面参数全解一节会逐一展开。三个完整工作示例技能附带的 plugin/skills/remember/EXAMPLES.md 提供了三个真实场景的完整调用链可以照着演练示例 1保存一个架构决策用户说Remember that we decided to drop Redis and use the iii-engine state store for session caching.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.示例 2保存一个代码级坑点用户说Save this: the rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide.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, ... }此时files字段记录了真实文件路径未来按文件维度检索也能命中。示例 3请求含糊、无关联文件用户只说 Remember this for later.此时先追问一次实质内容再保存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 回显给用户确认。三、Why记忆的价值取决于检索词的质量SKILL.md 的 Why 一节点明了整个技能的设计哲学A memory is only as useful as the terms that retrieve it. Tag with specific concepts so a futurerecallfinds it, and preserve the users own phrasing.即一条记忆的价值完全取决于将来用什么词能把它检索出来。因此两件事必须同时做到用具体的概念标签保证未来recall能命中保留用户的原始措辞而不是 Agent 的转述。这直接体现在源码实现里保存时content会被原样存储同时title由safeSlice(data.content, 80)截取前 80 个字符生成src/functions/remember.ts 会先切掉可能截断的 UTF-16 高位代理项避免 emoji 或扩展 CJK 字符被切出乱码检索与召回都建立在用户原话之上。四、Workflow六步标准保存流程SKILL.md 给出了完整的执行流程这里结合源码逐步解读第 1 步从$ARGUMENTS中提炼核心洞察、决策或事实。这是内容提取阶段只保留值得长期保存的信息。第 2 步提取 2–5 个小写概念短语具体优于通用jwt-refresh-rotation优于auth。这对应 MCP 层对concepts的解析逗号分隔、逐项trim并过滤空串src/mcp/server.ts最终以数组形式传入mem::remember。第 3 步提取关联文件路径绝对路径或仓库相对路径没有则为空。files同样按逗号分隔解析。第 4 步调用memory_save传入content、concepts、files。在多 Agent 场景下还需要传agentId让记忆落入正确的 Agent 作用域。第 5 步确认保存成功并回显 concepts让用户知道未来的检索词是什么。第 6 步更新事实时直接保存修正版。近乎重复的内容会取代旧记录——旧记录保留在版本链中、离开召回结果但仍可被 viewer 查看。多 Agent 作用域与项目作用域第 4 步提到的agentId在源码中有一套完整的作用域逻辑src/functions/remember.ts请求体中的agentId优先多 Agent 运行时在写入时显式打标其次回退到环境变量AGENT_IDgetAgentId()两者都没有 → 记忆无作用域legacy 行为作为共享记忆。agentId会被截断到 128 字符。类似的还有project参数它会参与后面的取代判定绝不跨项目取代另一条记忆见下文源码详解并且只有当两侧都显式声明了 project 时该保护才生效——无 project 的旧数据被视为通配符不会被孤立。五、Anti-patterns 与 Checklist避免写出谁也找不到的记忆SKILL.md 用一组正反对照强调了标签质量WRONG:concepts: stuff, code, notes(generic tags nothing can find later).RIGHT:concepts: jwt-refresh-rotation, token-revocation(specific, retrievable).保存前请对照 Checklist 自检Content 保留用户的措辞而非转述Concepts 具体、小写、2–5 项文件路径是真实引用不是猜测确认信息回显了实际打上的概念标签。六、源码纵深mem::remember底层到底做了什么memory_saveMCP 工具只是入口真正的写入逻辑在mem::remember函数src/functions/remember.ts。从源码可以看到一条完整的调用链memory_save (MCP 工具) └─ sdk.trigger({ function_id: mem::remember, ... }) // src/mcp/server.ts └─ registerRememberFunction(sdk, kv) // src/functions/remember.ts ├─ 参数校验 → 类型归一 → 候选生成 → 相似度判定 ├─ 构造 Memory 对象 → 写入 KV └─ 同步 BM25 索引 向量索引 → 触发 cascade-update1. 参数校验与类型归一入口首先做防御性校验src/functions/remember.tscontent必填且不能是纯空白否则返回{ success: false, error: content is required }files、concepts、sourceObservationIds必须是数组type只能是pattern | preference | architecture | bug | workflow | fact六种之一非法值一律回退为默认的fact。project会在进入任何后续逻辑前先trim归一化保证后续所有比较与存储使用同一份清洗值源码注释明确要求此点之后不得再引用原始的data.project。2. 候选生成用 BM25 索引缩小相似度比对范围取代判定需要与新内容比对存量记忆但不会遍历全量记忆库src/functions/remember.ts若 BM25 索引就绪且非空用新内容查询索引取前50 条命中再过滤出mem_前缀的 ID共享索引里还混有 observations它们占用槽位但永远解析不成记忆索引未就绪或查询失败时回退到全量扫描——这样冷索引下取代机制也不会静默失效候选生成本身只是优化手段失败绝不阻塞保存本身logger.warn后走全量扫描。3. 相似度判定0.7 取代、0.4 提示合并对每个候选记忆计算 Jaccard 相似度src/functions/remember.tssimilarity 0.7→ 判定为重复旧记忆被取代版本号 10.4 similarity 0.7→ 记为nearMatch最接近的一个作为建议性提示返回给调用方similarTo字段提示这两条可以考虑用memory_update/forget合并但绝不自动执行跨项目保护新旧记忆都带显式 project 且不一致时直接跳过该候选绝不取代。Jaccard 相似度的实现位于 src/state/schema.ts先做 NFC 归一化再分词建集合求交集比。值得注意的边界处理是空 token 集合比如 AI、a b 这类 ≤2 字符的词被丢弃后回退到归一化后精确相等判定——这样重存完全相同的短记忆仍能正确取代而互不相关的短串AI vs ML得分为 0不会被误取代。4. 记忆对象与版本链新记忆按如下结构落盘src/functions/remember.ts字段说明idgenerateId(mem)生成的唯一 IDtype归一化后的记忆类型默认facttitlecontent 前 80 字符安全截断content用户原文concepts/files标签与文件路径数组strength固定 7写入即高置信度version被取代则旧版本号 1否则 1parentId/supersedes版本链指针指向被取代的旧记忆isLatesttrue表示当前最新origin{ channel: agent, capturedAt }溯源信息agentId/project作用域字段按需附加forgetAfter可选ttlDays 0时设置过期时间毫秒换算被取代的旧记忆isLatest置为 false 并保留在 KV 中viewer 的版本链依赖它但会同时从 BM25 索引和向量索引中移除——源码注释的立场很明确召回返回一条过时事实比什么都不返回更糟。5. 保存后的索引同步与级联写入 KV 后还有两件关键收尾src/functions/remember.ts索引同步把新记忆加入 BM25 索引并写入向量索引。这一步有专门的 try/catch 与日志——若索引失败重启时的重建也会把记忆补回来索引失败绝不阻塞保存本身源码注释提到这是修复 #257 的关键没有它保存后几秒内memory_recall仍返回空。级联更新发生取代时触发mem::cascade-update事件让依赖旧记忆的下游数据如受影响的观察记录联动更新。6. REST 兜底/agentmemory/remembermem::remember不仅挂在 MCP 工具下也暴露为 REST 端点POST /agentmemory/remembersrc/triggers/api.ts请求体支持content、type、concepts、files、ttlDays、sourceObservationIds、project、agentId全量参数。当 MCP 工具不可用时这就是技能文档 Troubleshooting 指向的兜底通道。七、参数全解memory_save输入模式综合 src/mcp/tools-registry.ts 与 src/mcp/server.tsmemory_save的完整参数如下参数必填类型说明content是string要记住的洞察/决策/模式不能为空白type否stringpattern、preference、architecture、bug、workflow、fact默认factconcepts否string逗号分隔的关键概念标签files否string逗号分隔的关联文件路径project否string稳定的规范项目标识slug / UUID / 注册表键必须与会话启动时使用的值一致不要用文件系统路径或临时显示名——它们会跨机器变化并静默破坏项目作用域agentId否stringAgent 身份标识设置后 agent 作用域的 recall/search 只对同一 agentId 生效省略则为共享记忆从实现看concepts和files在 MCP 层都是字符串按逗号切分、逐项 trim、过滤空项最终以数组传给mem::rememberproject、agentId为空字符串时会被丢弃不传 undefined。八、Troubleshootingmemory_save不可用怎么办技能文档统一指向 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 守护进程是开放的带多余 header 反而会被拒绝。本技能对应的 REST 调用是POST /agentmemory/remember。注意守护进程同样只在启动时读取.mcp.json端口或鉴权变更后必须先重启两个传输通道才会生效。九、配套技能与recall组成读写闭环remember是写入端它对偶的读取端是 plugin/skills/recall/SKILL.md。recall 使用memory_smart_search混合 BM25 向量 图检索按查询词找回记忆memory_smart_search { query: jwt refresh token rotation, limit: 10 }对应的预期输出会按会话分组、按 importance 排序展示——这正是 remember 保存的概念标签发挥作用的地方没有第 2 步精心提取的jwt-refresh-rotation、token-revocation这类具体标签未来的召回就会落空。两技能配合形成了完整的写入标签 → 检索命中闭环配套的forget负责纠错删除lesson负责行为规则memory-discipline负责判断何时主动保存共同构成 agentmemory 的记忆体系。总结remember技能是 agentmemory 长期记忆的写入入口核心要点可归纳为四条保留用户原话、打具体可检索的标签、关联真实文件路径、确认时回显概念。底层实现则通过 BM25 候选加速、Jaccard 0.7 取代 / 0.4 提示合并、版本链保留、双索引同步与 cascade-update 保证写入的可靠性与可检索性。对集成开发而言memory_save有三层入口——MCP 工具、mem::rememberSDK 函数与POST /agentmemory/rememberREST 端点可按宿主能力自由选用多 Agent 部署时记得传agentId与稳定的project标识让每一条记忆都落在正确的作用域里。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考