ruflo `recall` 命令实战：基于 HNSW 向量检索与 MMR 多样性的跨命名空间语义召回

ruflorecall命令实战：基于 HNSW 向量检索与 MMR 多样性的跨命名空间语义召回

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

recall是ruflo-rag-memory插件对外暴露的"快速语义召回"命令，它不依赖精确关键词匹配，而是以句子的语义相似度从 AgentDB 的全部记忆命名空间中找回最相关条目。本文以 recall 命令定义 为核心，结合插件 README、memory-search / memory-bridge 技能、ADR-0001 契约以及@claude-flow/cli的源码实现，完整讲解recall的调用方式、排序原理、命名空间覆盖范围与底层检索管线，读完即可在自己的 Agent 工作流中直接使用。

recall是什么：一条命令打通全部记忆命名空间

在 ruflo 的记忆体系中，AgentDB 将知识按语义划分到多个命名空间（namespace），而recall的设计目标很明确：用户不需要指定命名空间，一条命令同时搜索patterns、tasks、solutions、feedback、security、claude-memories全部 6 个命名空间，并按"综合相关度"返回最相关的 top-k 结果。

npx @claude-flow/cli@latest memory search --query "$ARGUMENTS" --limit 5

命令定义位于 plugins/ruflo-rag-memory/commands/recall.md，其 frontmatter 描述为："Quick semantic recall — searches all memory namespaces with MMR diversity and recency weighting"。也就是说，这条命令的本质是memory search的"无命名空间"快捷封装：省略--namespace时，搜索范围自动扩大到全部命名空间。

使用场景

• 跨会话回忆：几天前、甚至其他项目里记过的解决方案，用一句自然语言就能捞回来（见 EXAMPLES.md 中的跨会话示例）；
• 不确定关键词时的语义查找：记不清原文，只记得"大概意思"；
• 与 Agent 协同：在 Claude Code 的 agent prompt 中通过memory_search({ query: "...", limit: 3 })注入上下文。

三种调用形态

recall根据$ARGUMENTS的内容选择不同行为：

1. 携带查询词：语义搜索

# 默认形态：HNSW 向量检索 + MMR 多样性重排，返回 top 5 npx @claude-flow/cli@latest memory search --query "oauth single page app" --limit 5 # 指定命名空间（recall 默认不指定，即全空间） npx @claude-flow/cli@latest memory search --query "rate limiting" --namespace patterns --limit 5

2. 已加载 ruvector 时：混合检索（更丰富的结果）

npx ruvector search "how did we handle rate limiting?" --hybrid --limit 5

当ruflo-ruvector插件同时加载时，recall可将检索委托给 ruvector 后端获得高级能力：FlashAttention-3 注意力、Graph RAG 多跳检索、稀疏+稠密混合检索（RRF 融合）、DiskANN 大规模持久化索引（见 ruflo-rag-memory README 的 "Integration with ruvector" 一节）。

3. 无参数：列出最近记忆

npx @claude-flow/cli@latest memory list --limit 10

未提供任何参数时，recall退化为"最近记忆列表"，便于快速浏览最近写入的内容。

排序核心：composite score 三因子分解

原文档明确指出，召回结果按综合得分排序：

Results are ranked by composite score:cosine similarity × MMR diversity × recency decay.

即每个候选条目的最终得分是三个因子的乘积，缺一不可：

这三个因子在 CLI 源码中也有直接印证：v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts中memory_search工具描述明确写出 "Backed by HNSW index over ONNX embeddings; returns top-k with similarity scores"，smart参数启用后即运行 "SmartRetrieval（RRF + MMR + Recency）" 管线（见 memory-tools.ts 与 memory-tools.ts）。

为什么需要 MMR 和 recency？

纯 cosine 相似度检索的典型问题是"扎堆"：同一主题的 5 条记忆可能内容高度重复，且旧记忆会永远压住新记忆。MMR 在最大化相关度的同时惩罚与已选结果相似的候选，保证结果集多样性；recency 衰减则让"上周的决定"优先于"三个月前的决定"，对时序类查询（"我们上周决定了什么？"）尤其关键。

底层管线：SmartRetrieval 五阶段（ADR-090）

recall的排序能力建立在 SmartRetrieval 检索管线之上（见 ruflo-rag-memory README 的 "SmartRetrieval (ADR-090)" 一节）。当--smart开启（或查询较复杂）时，完整管线为：

1. Query expansion（查询扩展）——基于模板生成查询变体，不依赖 LLM；
2. Multi-query fan-out + RRF（多查询扇出 + 倒数排名融合）——对多个变体分别检索，再按 Reciprocal Rank Fusion 融合排序；
3. Recency boost（时效提升）——按元数据时间戳做指数衰减加权；
4. MMR diversity（MMR 多样性重排）——token-Jaccard Maximal Marginal Relevance 重排，去除近重复；
5. Session round-robin（会话轮询）——从不同会话交错取结果，避免单一会话垄断。

# CLI 开启 SmartRetrieval npx @claude-flow/cli@latest memory search --query "auth patterns" --smart --limit 10 # MCP 形式（ruflo-core 提供 MCP server） mcp__plugin_ruflo-core_ruflo__memory_search({ query: "auth patterns", smart: true, limit: 10 })

该管线最适合多会话召回、时序查询与高多样性场景。

全命名空间语义：memory_search_unified与命名空间契约

recall的"全空间搜索"能力在 MCP 层面对应memory_search_unified工具。其命名空间解析有明确的优先级链：namespace（单值）→namespaces（数组）→ … → 传统的 6 命名空间兜底，这一逻辑由回归测试 memory-search-unified-2246.test.ts 锁定，防止未来改动悄悄破坏"无参全空间"行为。

命名空间一览

特别注意claude-memories是一个保留命名空间：它归ruflo-agentdb所有，ruflo-rag-memory只是其"规范化消费方"（canonical consumer），通过 SessionStart 钩子经memory_import_claude自动导入~/.claude/projects/*/memory/*.md到 AgentDB（见 ADR-0001 与 ruflo-agentdb README 的命名空间约定）。这意味着recall搜索到的结果既包含本插件写入的条目，也包含 Claude Code 原生自动记忆的跨项目内容。

记忆桥接（memory-bridge）

claude-memories命名空间由 memory-bridge 技能 维护，导入流程：

1. 读取 Claude Code 记忆文件（当前项目或全部项目）；
2. 生成 384 维 ONNX 嵌入（all-MiniLM-L6-v2）；
3. 存入 AgentDB 的claude-memories命名空间并建 HNSW 索引；
4. 与既有条目去重（余弦相似度 > 0.95 视为重复）；
5. 提供跨源统一语义搜索，结果带来源标注：claude-code/auto-memory/agentdb。

# 手动导入当前项目记忆 /memory-bridge # 导入所有项目 /memory-bridge --all-projects # 检查桥接健康状态（MCP） memory_bridge_status({})

CLI 参数与实测要点

常用参数

recall所调用的memory search命令支持的参数（见 ruflo-memory 命令）：

CLI 层面对缺查询、缺命名空间的容错与提示在 commands/memory.ts 中实现：查询缺失时报 "Query is required"，而混合命名空间结果被截断时会建议--namespace收窄。

端到端验证

仓库对recall行为有专门的回归测试 memory-search-recall-2558.test.ts（对应 #2558：v3.19.0/3.20.0 中已存条目无法被关键词或语义检索召回的问题）。测试断言两点：所有已存条目都能被共享关键词召回（核心回归），且唯一关键词能精准区分目标条目（召回是定向的，而非全量倾倒）。插件自身还有 10 项结构契约检查：

bash plugins/ruflo-rag-memory/scripts/smoke.sh # Expected: "10 passed, 0 failed"

该脚本（smoke.sh）校验版本与关键词、两个技能与 agent 及命令的 frontmatter、v3.6 版本 pin、claude-memories消费关系文档、memory_import_claude/memory_search_unified引用等。

完整实战工作流

结合 EXAMPLES.md，一个典型的"存储→跨会话召回"闭环：

# 会话 1：写入一个模式 npx ruflo memory store \ --key "pattern-concurrent-queue" \ --value "Use a bounded queue with semaphore for concurrent task processing; limits parallelism safely" \ --namespace patterns # 会话 2（第二天，另一个项目）：语义召回 npx ruflo recall "concurrent queue safe processing" # → 返回 "Use a bounded queue with semaphore..." # 精确检索/列表/删除 npx ruflo memory retrieve --key "pattern-concurrent-queue" --namespace patterns npx ruflo memory list --namespace patterns --limit 10 npx ruflo memory delete --key "old-pattern" --namespace patterns

在 Agent 代码中直接调用：

// 在 Claude Code agent 中跨会话取上下文 const findings = await memory_search_unified({ query: "OAuth2 PKCE refresh token security", limit: 5 }); // findings[0] 可能来自 3 周前的会话

小结

recall是 ruflo 记忆体系中"零配置召回"的入口：一条命令覆盖全部 6 个命名空间，按cosine similarity × MMR diversity × recency decay的综合得分排序，底层由 HNSW 向量索引与 SmartRetrieval 五阶段管线支撑，并可无缝升级到 ruvector 的混合检索与 Graph RAG。它既适合交互式使用，也适合作为 Agent 的上下文注入工具——这正是 ruflo "跨会话、跨项目语义记忆"能力的用户侧体现。

延伸阅读：插件架构与安装见 plugins/ruflo-rag-memory/README.md；检索策略选型与命名空间指南见 skills/memory-search/SKILL.md；底层 HNSW 性能审计数据见 docs/reviews/intelligence-system-audit-2026-05-29.md 与基准脚本 scripts/benchmark-intelligence.mjs。

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo