agentmemory 的 forget Skill 深度指南用 memory_smart_search 与 memory_governance_delete 安全删除 AI 代理记忆【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemoryforget 是 agentmemory 为 AI 编码代理提供的一个记忆撤销技能当用户说出 forget this、delete memory、remove that note 或出于隐私需要抹除特定数据时代理通过它精准定位并删除指定的记忆条目。读完本文你将掌握 forget skill 的完整六步工作流、memory_smart_search/memory_governance_delete/memory_lesson_delete三个 MCP 工具的精确参数与调用方式以及底层删除实现KV 存储、搜索索引、向量索引与审计日志的联动和可复现的实战用例。forget skill 是什么记忆的撤销入口agentmemory 是面向 AI 编码代理的持久化记忆系统记忆由rememberskill 写入、由recallskill 检索。而 forget skill 扮演的正是这两个方向的逆操作——remember的撤销undo。其 frontmatter 定义了技能的调用契约name: forget description: Delete specific observations from agentmemory after showing them and getting explicit confirmation. Use when the user says forget this, delete memory, remove that note, or wants to scrub specific data for privacy. argument-hint: [what to forget - session ID, file path, or search term] user-invocable: true三个关键点值得注意user-invocable: true这是一个可由用户直接触发而非仅供内部编排的技能触发语forget this、delete memory、remove that note以及任何为了隐私抹除特定数据的意图argument-hint用户提供的遗忘对象可以是 session ID、文件路径或搜索词但注意——这只是定位线索真正的删除永远以 memory ID 为单位进行。从源码看该技能最终映射到 MCP 工具层。在 src/mcp/tools-registry.ts 中memory_smart_search被定义为 Hybrid semantickeyword search with progressive disclosureL128-142memory_governance_delete被定义为 Delete specific memories with audit trailL340-353二者的组合构成了 forget 的主链路。快速上手一次安全的删除会话SKILL.md 给出了最短可行的调用序列。第一步用搜索定位目标记忆memory_smart_search { query: old api key in config, limit: 20 }向用户展示匹配结果并得到明确同意后第二步执行删除memory_governance_delete { memoryIds: [abc12345, def67890], reason: user privacy request }预期输出Found 2 matching memories. Confirmed. Deleted 2 memories.注意整个流程中两次工具调用的职责分离搜索负责找到删除负责抹掉二者之间必须隔着一次人工确认详见下文工作流。完整工作流六步安全删除协议SKILL.md 将删除流程规范化为六步这是 forget 技能的灵魂所在搜索定位用memory_smart_search发起搜索query传用户的原始表述limit设为20覆盖足够候选避免遗漏同一目标的多个记忆展示并确认把匹配到的 session id、memory id、title 完整展示给用户索要明确确认。文档明确警告沉默、或一句含糊的 sure, whatever 都不足以作为删除依据执行删除确认后调用memory_governance_deletememoryIds可传数组或逗号分隔字符串reason可选默认值为plugin skill request整会话删除的特殊处理若要删除整个 session必须从搜索结果中收集该 session 的全部 memory id 一并传入。MCP 不接受裸的sessionId参数——这一点在源码中得到印证memory_governance_delete的 inputSchema 中required字段只有memoryIds而memoryIds的类型是字符串逗号分隔根本没有 sessionId 字段见 src/mcp/tools-registry.ts课程lessons单独处理课程是独立的数据类型memory_governance_delete不会触碰课程删除单条课程要用memory_lesson_delete并传其lessonId汇报实际删除数把返回的计数如实报告给用户。计数为 0 意味着这些 ID 不存在此时要如实说明未找到对应记忆而不是谎称删除了。三个核心 MCP 工具的参数详解结合 src/mcp/tools-registry.ts 中的工具定义将 forget 涉及的工具参数整理如下memory_smart_search定位参数类型必填说明querystring是搜索关键词expandIdsstring否逗号分隔的 observation ID用于展开渐进披露的详情limitnumber否最大返回条数默认 10该工具执行的是语义 关键词混合检索hybrid semantickeyword search这意味着既可以用自然语言描述以前贴在配置里的那个旧 API key也能用字面关键词命中目标比纯向量检索更容易召回用户口述的模糊目标。forget skill 建议显式传limit: 20因为删除场景最怕漏网——同一份敏感信息可能被拆成多条记忆。memory_governance_delete删除参数类型必填说明memoryIdsstring是逗号分隔的 memory ID 列表必填reasonstring否删除原因会写入审计日志工具描述中特别强调 with audit trail即每一次删除都会留下审计记录。memory_lesson_delete删除课程参数类型必填说明lessonIdstring是课程 ID格式为lsn_...源码中该工具被定义为软删除soft-deleteDeleted lessons are excluded from recall and list; re-saving the same content creates a fresh lesson见 src/mcp/tools-registry.ts。也就是说课程删除后不会从召回与列表中再次出现但内容并未物理抹除若重新保存相同内容会生成一条全新课程。源码纵深一次 memory_governance_delete 到底做了什么工具层之下真正的删除逻辑实现在 src/functions/governance.ts 的mem::governance-delete函数中。逐行阅读其实现L10-52可以还原一次删除的完整副作用参数校验memoryIds必须是非空数组否则直接返回{ success: false, error: memoryIds array is required }逐条删除对每个 ID先kv.get确认记忆存在随后执行四条联动清理kv.delete(KV.memories, id)从 KV 主存储删除记忆本体deleteAccessLog(kv, id)清理该记忆的访问日志来自 access-tracker 模块避免记忆已删但访问痕迹仍在的隐私残留getSearchIndex().remove(id)从搜索索引移除vectorIndexRemove(id)从向量索引移除持久化只要删除了至少一条就flushIndexSave()立即落盘索引保证删除即时生效审计无论删除数量多少都会通过recordAudit写入一条delete类型的审计记录附带reason与deleted数量返回值{ success: true, deleted, total: data.memoryIds.length }——deleted与total可能不一致部分 ID 不存在时这正是工作流第 6 步如实汇报计数的底层依据。同一文件中的mem::governance-bulkL54 起则提供按条件批量删除按 type、日期范围、质量分数过滤支持dryRun预览可作为 forget 之外的治理补充。测试用例如何验证删除语义test/governance.test.ts 为上述行为提供了可执行证据重点用例包括governance-delete removes specified memoriesL85-92删除后result.deleted为 1governance-delete handles non-existent IDs gracefullyL99-105传不存在的 ID 时deleted为 0不抛错governance-delete removes the memory from the search indexL183 起验证删除会同步清理搜索索引governance-delete flushes persistence immediatelyL196 起与skips persistence flush when nothing was deletedL209 起验证只有实际删除时才触发持久化 flush与 governance.ts 中if (deleted 0) await flushIndexSave()的实现完全对应审计相关用例L245 起删除后审计日志中functionId为mem::governance-delete。课程软删除的源码实现src/functions/lessons.ts 的mem::lesson-deleteL264-291展示了与记忆删除不同的策略若课程不存在或已删除返回{ success: false, error: lesson not found }命中后仅将lesson.deleted true并更新时间戳不物理删除KV 记录同时从内存课程记录与课程索引移除并写入lesson_delete审计。这解释了 SKILL.md 中memory_governance_deletedoes not touch lessons的设计记忆与课程是两套独立的删除路径代理在遗忘场景中必须根据数据类型选择正确的工具。实战用例三个可复现的对话场景forget/EXAMPLES.md 提供了三个完整的端到端示例覆盖了正常删除、整会话删除与用户反悔三种情形。场景一删除泄露的密钥用户说Forget that note where I pasted the API key.memory_smart_search { query: api key, limit: 20 }搜索结果返回包含id、sessionId、title、narrative的条目{ results: [ { id: abc12345, sessionId: 7f3a9c21, title: Pasted staging API key, narrative: STAGING_KEYsk-live-... } ] }展示并等待确认确认文案必须让用户看到具体内容Found 1 match:abc12345(session7f3a9c2) Pasted staging API keyDelete this memory? (yes/no)用户同意后memory_governance_delete { memoryIds: [abc12345], reason: user privacy request }返回{ deleted: 1 }最终向用户汇报 Deleted 1 memory (abc12345). 整个链路把找到 → 展示 → 确认 → 删除 → 汇报完整走了一遍。场景二删除整个临时会话的全部观察用户说Delete everything from the throwaway spike session.先用语义搜索把会话内所有记忆找齐memory_smart_search { query: spike prototype throwaway, limit: 20 }假设返回 4 条结果、sessionId均为c98f1100。展示全部四条并得到确认后一次性传入所有 IDmemory_governance_delete { memoryIds: [m1, m2, m3, m4], reason: drop throwaway spike session }示例末尾特意强调永远不要发送{ sessionId: c98f1100 }——MCP 只按 memory id 删除。这是整个技能最容易踩的坑用户习惯说删掉那个会话但工具契约只认 ID 列表代理必须先把会话翻译成 ID 集合。场景三用户反悔用户说Actually, on second thought, keep them.此时不调用任何删除工具直接确认Understood, nothing deleted. The 4 memories from sessionc98f110are intact.这个场景同样重要删除是不可逆的代理应当把不删除也当作一等行为明确汇报未执行任何操作。反模式什么绝对不能做SKILL.md 用一组正反对照明确了行为边界WRONG搜索返回匹配后不展示、不等确认立刻调用memory_governance_delete。RIGHT先列出匹配项询问 Delete these 2? (yes/no)只有在收到明确 yes 后才执行删除。删除是破坏性且不可逆的操作destructive and irreversible确认不是形式主义。配套的 checklist 可作为每次删除前的自查清单删除前已将匹配结果展示给用户收到了明确同意而非臆测memoryIds中是从搜索结果拿到的真实 ID绝不传裸sessionId最终消息如实报告了实际删除数量。与 remember / recall 的协作关系SKILL.md 的 See also 部分点明了 forget 在技能体系中的位置remember写入侧forget 是它的撤销操作undo。记忆写入后若发现内容有误或含敏感信息forget 负责回滚recall在删除前先用recall精确定位目标 memory ID。实际上 forget 主链路使用的memory_smart_search同样是检索工具家族的一员它的渐进披露progressive disclosure设计保证代理先用粗粒度结果展示给用户确认必要时再通过expandIds展开详情。三者构成完整闭环remember 写入 → recall/smart_search 定位 → forget 删除。故障排查MCP 工具不可用怎么办SKILL.md 的 Troubleshooting 指向共享文档 plugin/skills/_shared/TROUBLESHOOTING.md。当memory_smart_search或memory_governance_delete不在工具列表中时按顺序排查在宿主中运行/plugin list确认agentmemory处于 enabled 状态重启宿主插件的.mcp.json只在启动时读取新装或重新启用的插件不会在会话中途注册工具检查/mcp确认agentmemoryserver 显示为活连接。若 MCP 工具始终不可用但守护进程在运行可走 REST 兜底设置AGENTMEMORY_URL默认http://localhost:3111仅在设置了AGENTMEMORY_SECRET时携带Authorization: Bearer头——默认的本机守护进程是开放的多余的请求头反而会被拒绝。forget 对应的 REST 端点为POST /agentmemory/smart-search定位与POST /agentmemory/remember路径体系中的删除接口。同样地端口的任何变更都需要重启守护进程后才会在两个传输层生效因为.mcp.json只在启动时读取。总结forget skill 的设计核心可以浓缩为三句话先展示、后删除——删除不可逆展示与明确确认是不可省略的安全阀只认 memory ID——memory_governance_delete的参数契约是memoryIds整会话删除必须先翻译成 ID 集合课程删除则走独立的memory_lesson_delete软删除路径删除是系统工程——底层实现会同步清理 KV 主存储、访问日志、搜索索引与向量索引并留下审计记录确保删除在索引与审计层面都彻底且可追溯。对于在自己的编码代理中接入 agentmemory 的开发者把 forget/SKILL.md 与 forget/EXAMPLES.md 一起作为代理的行为规范配合 governance.ts 与 governance.test.ts 理解底层语义即可安全地把遗忘能力交给代理——既满足用户的隐私擦除诉求又不会造成误删事故。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考