agentmemory recall 技能实战：用 memory_smart_search 跨会话召回决策、代码与经验

agentmemory recall 技能实战用 memory_smart_search 跨会话召回决策、代码与经验【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory本指南围绕 agentmemory 内置的recall技能展开讲解如何借助memory_smart_search工具以混合检索BM25 全文 向量语义 图关系的方式从历史会话的观察记录observations、会话sessions与经验教训lessons中召回与当前任务相关的上下文。读完本文你将掌握 recall 的标准调用姿势、结果展示规范、空结果处理策略以及当 MCP 工具不可用时直接调用 REST 接口的兜底方案并能从源码层面理解这条召回链路的真实工作方式。技能定位recall 是读取侧的第一入口recall是 agentmemory 中一个用户可主动触发user-invocable的技能定义在 plugin/skills/recall/SKILL.md。它的职责单一而明确检索过去会话中关于某个主题的观察、会话和经验不负责写入。它的 YAML frontmatter 完整描述了这个契约--- name: recall description: Search agentmemory for past observations, sessions, and learnings about a topic using hybrid BM25 plus vector plus graph search. Use when the user says recall, what did we do about, did we ever, have we seen, or needs context from past sessions. argument-hint: [search query] user-invocable: true ---从描述可以看出技能在以下时刻应被触发用户明确说 recall用户问 what did we do about…我们之前对 X 做过什么用户问 did we ever…、have we seen…我们是否曾经……用户需要来自过去会话的上下文。用户触发时传入的文本会填入模板The user wants to recall past context about: $ARGUMENTS随后技能开始执行召回流程。快速上手一条命令完成召回recall的核心操作只有一个调用 MCP 工具memory_smart_search传入用户的原始文本作为query并显式设置limit。技能中的 Quick start 给出了最小可用示例memory_smart_search { query: jwt refresh token rotation, limit: 10 }预期输出格式如下以技能文档原文为准2 results across 2 sessions. [importance 8] decision · Rotate refresh tokens on every use (session 7f3a9c21) [importance 5] code · limit.ts counts per-IP (session b21d004e)注意输出中出现了几个关键字段importance重要度、type观察类型如 decision / code、title标题以及sessionId。这意味着召回结果不是简单的相似文本列表而是带有结构化元数据的记忆条目Agent 可以据此判断哪些信息更值得优先引用。底层链路从 MCP 工具到三流混合检索memory_smart_search并非孤立实现它在 MCP 层注册见 src/mcp/tools-registry.ts并由 src/mcp/server.ts 转发到内部函数mem::smart-searchcase memory_smart_search: { if (typeof args.query ! string || !args.query.trim()) { return { status_code: 400, body: { error: query is required for memory_smart_search } }; } const expandIds parseCsvList(args.expandIds).slice(0, 20); const limit Math.max(1, Math.min(100, asNumber(args.limit, 10) ?? 10)); const result await sdk.trigger({ function_id: mem::smart-search, payload: { query: args.query, expandIds, limit }, }); // ...返回 JSON 文本内容 }见 src/mcp/server.tsmem::smart-search的真正实现在 src/functions/smart-search.ts 的registerSmartSearchFunction中。从源码结构看它采用紧凑模式compact mode返回结果并做了三件事混合检索把query交给searchFn即HybridSearch执行三路检索经验召回只要includeLessons ! false就并行触发mem::lesson-recall召回 lessons并对每条 lesson 内容截取前 240 个字符作为预览LESSON_CONTENT_PREVIEW_CHARS 240完整内容可另行拉取访问记录通过recordAccessBatch记录被召回的观察 ID供 retention / 访问追踪使用。三流检索BM25 向量 图HybridSearch类定义在 src/state/hybrid-search.ts其tripleStreamSearch方法并行执行三路检索再用加权 RRFReciprocal Rank Fusion融合排序BM25 全文检索由SearchIndex提供匹配关键词字面相似向量语义检索当配置了VectorIndex与EmbeddingProvider时对查询生成 embedding 后做近邻搜索任何一步失败都会静默降级为仅 BM25图关系检索通过GraphRetrieval先从查询中抽取实体extractEntitiesFromQuery按实体检索关联观察并基于 top-5 向量结果做图扩展expandFromChunks图检索全程 best-effort。融合时默认权重为 BM25 0.4、向量 0.6、图 0.3RRF 常数K 60一个结果同时命中多条流时会获得 5% 的多流一致加成AGREEMENT_BONUS 0.05。之后还会经过两个后处理阶段按会话去重diversifyBySession限制每个会话最多贡献 3 条结果避免单个会话刷屏可选重排当环境变量RERANK_ENABLEDtrue时用 src/state/reranker.ts 加载huggingface/transformers的Xenova/ms-marco-MiniLM-L-6-v2q8 量化对 top-20 结果做交叉编码重排失败则回退到原始顺序。因此技能文档中 hybrid BM25 plus vector plus graph search 的表述与源码实现完全吻合——memory_smart_search返回的每一条结果都携带combinedScore这是三流加权融合后的最终分数。标准工作流五步完成一次可靠召回recall技能定义了一套严格的工作流确保召回过程既完整又不越权发起检索用用户的原始文本作为query调用memory_smart_searchlimit取 10。当用户把问题限定到某个具体仓库时额外传入project参数MCP 参数为memory_smart_search的projectREST 侧同样支持。按会话分组把结果按sessionId分组展示。每条记录都携带来源通道provenance channeluser、agent、tool、import、shared该枚举定义在 src/types.ts 的Origin接口中。当结果之间互相冲突时优先采信user通道而非agent推断并将shared通道的记录标注为其他队友的写入。逐条展示对每条观察展示其类型type、标题title与叙述narrative。高信号优先优先呈现importance 7的高价值观察。空结果兜底若返回零条结果给出 23 个替代搜索词建议并停止绝不猜测。第 2 步中的 provenance 通道在实现上属于写入时固化的信息Origin接口的注释明确写着 Immutable write-time provenance: which trust boundary the content crossed, inherited by derived records不可变的写入时来源内容跨越了哪条信任边界并由派生记录继承。这意味着 recall 阶段读取到的通道信息是可靠的可以用作冲突仲裁依据。参数详解memory_smart_search 的完整入参虽然技能文档只要求传query与limit但底层mem::smart-searchsrc/functions/smart-search.ts还支持以下参数REST 层会做字段白名单校验src/triggers/api.ts 的api::smart-search会显式挑出合法字段丢弃未知字段参数类型默认值/约束作用querystring必填且不能为空白检索关键词缺失时返回error: query is requiredlimitnumber默认 10钳制在 1100返回结果条数上限expandIdsstring / obsId 数组最多 20 个按 ID 直接展开指定观察进入expanded模式跳过混合检索可附带sessionId加速查找projectstring可选限定项目范围透传给 lesson 召回includeLessonsboolean默认 true是否同时召回 lessonslesson 数量额外钳制在min(limit, 10)agentIdstring可选*表示通配多 Agent 路由时的隔离过滤开启AGENTMEMORY_AGENT_SCOPEisolated且无法解析出 agentId 时会拒绝执行防止跨 Agent 泄漏sessionIdstring可选会话锚点用于 follow-up 率诊断sourcestring可选标记调用来源如viewer诊断时会跳过 viewer 发起的搜索两点值得注意的实现细节limit 钳制MCP 层与函数层双重钳制最终上限为 100做 Agent 过滤时会以limit * 3上限 300过度拉取再过滤因为 BM25/向量索引不携带 agentId无法在检索阶段过滤隔离模式 fail-closed当AGENTMEMORY_AGENT_SCOPEisolated且既无环境变量AGENT_ID、调用也未显式传agentId时函数会直接抛出错误而非静默返回跨 Agent 数据——这是刻意设计的失败关闭策略见 src/functions/smart-search.ts 中的#817相关注释。三个实战示例继承技能文档的完整用例plugin/skills/recall/EXAMPLES.md 提供了三个可直接照搬的完整用例覆盖命中决策、多会话多结果、零结果三种典型场景。示例 1命中一条过去的决策用户问Did we ever decide how to cache sessions?我们是否决定过如何缓存会话调用memory_smart_search { query: session caching decision, limit: 10 }返回{ results: [ { sessionId: 7f3a9c21, type: decision, title: Drop Redis for iii state store, narrative: We decided to drop Redis and use the iii-engine state store for session caching., importance: 8 } ] }向用户呈现引用会话 ID 与重要度不加工不润色Yes. In session7f3a9c21you decided to drop Redis and use the iii-engine state store for session caching (importance 8).示例 2跨会话返回多条结果用户问Recall anything about the rate limiter.回忆一下关于限流器的任何内容。返回两条分别来自不同会话的记录{ results: [ { sessionId: b21d004e, type: code, title: limit.ts counts per-IP, narrative: Rate limiter counts per-IP, not per-user., importance: 6 }, { sessionId: c98f1100, type: conversation, title: Discussed sliding window, narrative: Considered a sliding-window limiter, deferred., importance: 4 } ] }展示时按会话分组并让高重要度的 per-IP 代码记录排在最前——这与工作流第 4 步lead with importance 7一脉相承本例最高为 6则按分数降序。示例 3零结果用户问Recall the GraphQL schema migration.返回空集{ results: [] }。此时不能编造而是给出替代检索词No memories matched that. Tryschema change,graphql, ormigrationas narrower terms, orrecap this weekto scan recent sessions.反模式与纪律只呈现工具返回的内容recall技能明确规定了为什么Why与反模式Anti-patterns这是整个技能最重要的行为约束Why: Only surface what the tool returned. Never fabricate an observation, a session id, or an importance score. If nothing comes back, say so.只呈现工具返回的内容。绝不虚构观察、会话 ID 或重要度分数。如果什么都没有返回就直说。技能给出的正反对照错误示范WRONG结果为空却凭假设写下We probably discussed token expiry last week我们上周大概讨论过 token 过期。正确示范RIGHTNo memories matched that query. Tryrefresh token,session expiry, orauth rotation.没有记忆匹配该查询。试试refresh token、session expiry或auth rotation。这条纪律背后有工程支撑memory_smart_search返回的每条结果都携带obsId、sessionId、score、timestamp等字段CompactSearchResult见 src/functions/smart-search.tsAgent 应原样转述这些字段不得改写、四舍五入或转述session id 与分数——技能 Checklist 中将其列为硬性要求。空结果处理与诊断信号除了建议替代词并停止的标准做法空结果在实现层还有一个额外含义mem::smart-search的 follow-up 率诊断issue #771会在sessionId存在且source ! viewer时把本次查询与结果 ID 集写入KV.recentSearches若窗口内默认由getFollowupWindowSeconds()决定前一次查询的结果集与本次完全不相交就计一次smartSearchFollowupWithinWindow指标。源码注释特别指出空结果集不被计为 follow-up因为检索无返回属于检索失败而非读了但没用计入会虚高诊断率。换言之空结果时技能层面的停止并建议与实现层面的不计入负面指标是相互呼应的一对设计。故障排查MCP 工具不可用时的三条路径与 REST 兜底recall的 Troubleshooting 一节指向共享排障文档 plugin/skills/_shared/TROUBLESHOOTING.md其中给出了memory_smart_search不可用时的完整处理顺序在宿主中执行/plugin list确认agentmemory显示为已启用重启宿主——插件的.mcp.json只在启动时读取新安装或重新启用的插件不会在会话中途注册工具检查/mcp确认agentmemory服务器处于存活连接状态。若 MCP 工具始终不可用但守护进程daemon在运行可直接调用 REST API 兜底设置AGENTMEMORY_URL为 daemon 基地址默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才添加Authorization: Bearer $AGENTMEMORY_SECRET头——默认的 localhost daemon 是开放的带多余请求头反而会被拒绝。recall 对应的 REST 端点是POST /agentmemory/smart-search。该端点由api::smart-search注册src/triggers/api.ts支持query、expandIds、limit、project、includeLessons、agentId、sessionId、source等字段并要求query与expandIds至少提供其一否则返回 400。示例调用curl -X POST $AGENTMEMORY_URL/agentmemory/smart-search \ -H Content-Type: application/json \ -H Authorization: Bearer $AGENTMEMORY_SECRET \ -d {query: jwt refresh token rotation, limit: 10}当未设置AGENTMEMORY_SECRET时省略 Authorization 头。排障文档还提醒daemon 仅在启动时读取.mcp.json因此任何端口或鉴权变更都需要重启后才对两种传输方式生效。技能协同recall 在记忆读写闭环中的位置recall是 agentmemory 记忆体系写入—读取—沉淀闭环中的读取侧主角它与相邻技能的分工如下均位于 plugin/skills 目录remember写入侧recall 召回的就是它存储的内容recap、handoff、session-history同一份数据的不同会话级视图——recap 扫描近期会话、handoff 生成交接摘要、session-history 浏览会话列表memory-discipline定义何时应主动而非等待用户指令发起这类检索。从 REST 端点映射也能看出这种协同关系recall 对应POST /agentmemory/smart-searchrecap 与 handoff 都组合使用GET /agentmemory/sessionsPOST /agentmemory/smart-searchsession-history 则只用GET /agentmemory/sessions。自检清单一次合格 recall 的验收标准技能文档末尾给出了一份可直接用于自查的 Checklist任何一次 recall 执行都应逐条通过展示的每条观察都来自工具响应无虚构结果已按会话分组高重要度优先空结果触发了替代词建议而非编造内容未对 session id 或分数进行转述或四舍五入。把这份清单与本文的源码分析对照可以看出前两条对应memory_smart_search返回结构化CompactSearchResult含 sessionId、type、title、score以及HybridSearch的diversifyBySession RRF 排序第三条对应工作流第 5 步与 follow-up 诊断对空结果的特殊处理第四条则是技能只呈现工具返回内容纪律的直接体现。掌握这四条标准你就能把recall从一个搜索命令升级为可靠、可审计的跨会话记忆召回流程。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考