agentmemory 记忆纪律实战指南用先读后写循环让 AI 编码 Agent 的持久记忆真正生效【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory导读agentmemory 为 AI 编码 Agent 提供了基于真实世界基准测试的持久记忆能力hooks 自动捕获会话中的工具调用与事件LLM 压缩沉淀并在未来会话中注入上下文。然而自动捕获无法替代判断——哪个事实重要、哪个决策已尘埃落定、哪次纠正应当改变未来的行为。本文围绕仓库中的 memory-discipline 技能系统讲解这套让持久记忆回本的工作纪律任务开始前先检索、决策落定时即时保存、被纠正时沉淀为 lesson。读完你既能掌握机械化的五步工作循环也能结合源码理解memory_smart_search、memory_save、memory_lesson_save背后的混合检索、去重接替与置信度强化原理。核心原则记忆只在正确时机产生回报Memory only pays off when reads happen before the work and writes happen at decision points. This loop is the skill; every tool call in it is mechanical.这是 memory-discipline 的开篇论断记忆的回报取决于两个时机——读取发生在工作开始之前先检索、后动手命中一次就省下整个重新发现过程未命中也不过一次工具调用的代价。写入发生在决策落定之时在一个决策敲定的瞬间保存它理由还热乎、上下文还完整等会话结束再批量补记理由早已丢失。这套循环本身是机械化的不需要灵感每个工具调用点都是固定动作。它才是真正意义上的技能skill而非靠自觉的临时行为。为什么 hooks 不够自动捕获无法代替判断agentmemory 通过一系列 hooks 自动记录 Agent 的工作过程例如 post-tool-use.ts 会在每次工具调用后把tool_name、tool_input、tool_output截断到 8000 字符上报到/agentmemory/observe端点session-end.ts 会在会话结束时从 transcript 中提取用户查询并触发总结。也就是说发生了什么完全不需要你操心。但 hooks 无法捕获的是判断judgment哪个事实值得跨会话保留哪个决策已经尘埃落定settled不再是待议项哪次用户纠正应当改变未来的行为方式这些判断恰好落在正确的时机点上就是记忆纪律discipline的全部内容。换句话说hooks 负责记录纪律负责挑选与时机。快速上手一读一写两个调用在任何非平凡任务开始时先做项目级检索第一个工具调用就交给它memory_smart_search { query: auth refresh flow, project: myrepo, limit: 5 }随后在每一个落定的决策点上保存格式如下memory_save { content: Chose cursor pagination over offset; offset scans broke past 100k rows in db/list.ts., concepts: cursor-pagination, offset-scan-limit, files: src/db/list.ts }注意两处要点project是稳定标识符。根据 MCP 工具定义 中对memory_save的说明project应是稳定的规范项目标识slug、UUID 或 registry key且必须与会话启动时使用的值一致不要使用文件系统路径或临时显示名否则跨机器会静默破坏项目隔离。concepts要具体。jwt-refresh-rotation胜过authcursor-pagination胜过pagination——只有具体的概念词未来的检索才能命中。完整工作循环五步机械化流程memory-discipline 给出了从任务开始到会话结束的完整循环任务开始读代码之前对任何非平凡任务先以任务主题 项目名调用memory_smart_search。把第一个工具调用花在这里——命中一次就省下重新发现未命中也不过一次调用的代价。这是整个循环中成本收益比最高的一步。任务中途决策落定/坑点解决之时立即调用memory_save保存内容必须同时包含决策与理由附 25 个具体概念词和真实文件路径。务必在解决的那一刻保存会话结束时的批量保存会丢失理由。用户纠正你的做法时保存 lesson 而不是 memory见 lesson 技能。Lesson 带置信度会在相似工作前重新浮出memory 承载事实。重复做曾被纠正过的任务类型之前调用memory_lesson_recall以任务类型为查询词让之前纠正沉淀的规则先出现。会话结束什么都不做。hooks 会自动总结与整合consolidate手动补一次 recap 保存只会与 hooks 重复。什么值得保存判断的边界该保存Save落定的决策及其理由settled decisions with reasons调试中发现的非显然约束non-obvious constraints无法从仓库推导出的环境事实environment facts not derivable from the repo。不该保存Skip任何从代码中可读出的内容——代码本身就是事实来源重复存入只会制造噪音瞬时状态transient state密钥secrets逐步叙述step-by-step narration——hooks 已经捕获了它。这套边界的本质是职责分工仓库存代码事实hooks 存过程流水显式记忆只存判断产物。反模式与正确姿势WRONG: finish implementing, then search memory to double-check, and batch-save a summary of everything done. RIGHT: search first, save each decision as it settles, let hooks own the summary.错误姿势实现完成后再回头检索复核然后批量保存一份全程总结。此时检索失去意义工作已完成批量保存丢掉了每个决策的即时理由还与 hooks 的自动总结重复。正确姿势先检索后动手每个决策落定即存带理由总结交给 hooks。自查清单让纪律可校验每次会话结束前用这份清单自检原文清单非平凡任务的第一个工具调用是项目级搜索project-scoped search每条保存都带理由而不只是结论用户纠正被保存为 lesson而非 memory没有保存仓库或 hooks 已经记录的内容。配套技能recall、remember 与 lesson 的分工memory-discipline 是何时调用的调度层而具体的读写执行由它的配套技能完成recall 技能面向用户的读取侧user-invoked。当用户说recallwhat did we do about等时触发内部调用memory_smart_search执行 BM25 向量 图的三路混合检索。其纪律是只呈现工具返回的内容绝不虚构观察记录、会话 id 或重要性评分空结果时给出 23 个替代检索词并停下不猜测。remember 技能面向用户的写入侧对应memory_save。核心纪律是保留用户的原始措辞不转述、提取 25 个具体小写概念词、记录真实文件路径更新事实时直接保存修正版本近似重复内容会接替supersede旧记录。lesson 技能行为规则的存储与召回。memory_lesson_save保存一条带置信度的规则如Run vitest with --run in CI; watch mode hangs the pipeline.——触发条件 动作 后果memory_lesson_recall在同类工作前以任务类型为查询召回结果按置信度与新鲜度排序。三者与 memory-discipline 的关系可以概括为discipline 决定何时做remember/recall 负责读写事实lesson 负责读写行为规则。源码级原理这三个调用在底层做了什么memory_smart_search三路混合检索 渐进式披露memory_smart_search对应 SDK 函数mem::smart-search见 smart-search.ts其核心检索链路在 hybrid-search.ts 中实现三路流BM25 关键词索引 向量索引bm25Weight 0.4、vectorWeight 0.6 知识图检索graphWeight 0.3通过 RRFReciprocal Rank FusionRRF_K 60融合排序渐进式披露compact mode默认只返回obsId、sessionId、title、type、score、timestamp的紧凑结果避免一次性把大段叙事塞进上下文需要完整内容时再用expandIds展开指定观察记录lesson 联动mem::smart-search默认同时调用mem::lesson-recall可通过includeLessons: false关闭把高置信度 lesson 一并带出——这正是 discipline 第 4 步重复被纠正过的任务前召回 lesson的底层实现Agent 隔离多 Agent 模式下支持agentId过滤隔离模式下若无 agent id 解析会 fail-closed 拒绝跨 Agent 读取防止信息泄漏使用跟踪每次检索都会通过recordAccessBatch记录访问供 retention保留策略评估记忆热度。此外源码还内置了一个 followup-rate 诊断#771若同一会话在时间窗内连续两次检索结果集合完全不重叠会被视为读而未用信号并计数用于度量 Agent 是否真的消费了检索结果。memory_save去重、接替与双索引写入memory_save对应mem::remember见 remember.ts保存时的关键逻辑近重复接替supersession保存前用 BM25 索引检索候选记忆对内容做 Jaccard 相似度比较——相似度 0.7 时新记忆接替旧记忆旧记录isLatest falseversion 1从检索索引中移除但留在版本链中供 viewer 回溯这正是 remember 技能中更新事实直接保存修正版的底层机制0.40.7 之间的近似匹配会作为similarTo建议返回不自动处理跨项目记忆永不互相接替双索引写入保存后同时写入 BM25 索引与向量索引vectorIndexAddGuarded确保memory_smart_search与向量召回能立刻命中——源码注释明确这是修复保存后几秒内检索为空的回归#257类型与元数据type支持pattern、preference、architecture、bug、workflow、fact六种缺省fact支持ttlDays过期agentId与project用于多 Agent 与多项目隔离标题自动取内容前 80 字符并做了 UTF-16 代理对安全截断。memory_lesson_save / memory_lesson_recall置信度强化与衰减lesson 体系实现在 lessons.ts 中与 memory 的关键差异在于置信度动力学强化同一内容重复保存按内容指纹fingerprintId(lsn, ...)命中不会新建记录而是执行reinforceLesson——reinforcements 1置信度按confidence 0.1 * (1 - confidence)向 1.0 收敛。这正是重复纠正会上升的实现衰减mem::lesson-decay-sweep按周为单位衰减decayRate 0.05置信度下限 0.05从未强化且置信度 ≤ 0.1 的 lesson 会被软删除——一次性噪音会淡出召回排序mem::lesson-recall在专用 BM25 索引上检索最终得分 confidence × relevance × recencyBoost新鲜度以强化时间为基准并按minConfidence默认 0.1过滤安全边界lesson 内容与 context 中禁止存密钥recall 返回的 lesson 文本是参考资料Agent 应权衡采纳但绝不应当覆盖用户当前的明确指令。排障当 memory_smart_search / memory_save 不可用时若memory_*MCP 工具没有出现在工具列表中说明 stdio MCP shim 未启动。按 TROUBLESHOOTING.md 依次排查在宿主中运行/plugin list确认agentmemory显示为已启用重启宿主——插件的.mcp.json只在启动时读取新装或重新启用的插件不会在会话中途注册工具检查/mcp确认agentmemoryserver 显示为活跃连接。若 MCP 工具持续不可用但守护进程在运行可退回到 REST API 直连默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才添加Authorization: Bearer头——默认本地守护进程是开放的传入多余头会被拒绝。对应本纪律的端点映射为memory_save→POST /agentmemory/remembermemory_smart_search→POST /agentmemory/smart-search。注意守护进程同样只在启动时读取配置端口或认证变更都需要重启才能生效。结语把记忆从存储升级为循环agentmemory 的价值不在于能存多少而在于存得对、读得早。memory-discipline 用五步机械化循环把这种价值兑现任务前memory_smart_search先读决策落定memory_save即写用户纠正memory_lesson_save沉淀规则同类任务前memory_lesson_recall复现教训会话结束则信任 hooks 的自动总结与整合。理解底层实现——三路混合检索、近重复接替、置信度强化衰减——能帮助你在实际使用中判断该存什么、存多细、何时存让每一次工具调用都物有所值。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
`)
