ruflo-rag-memory 插件深度解析：基于 HNSW 向量检索与 AgentDB 的跨会话语义记忆系统

ruflo-rag-memory 插件深度解析基于 HNSW 向量检索与 AgentDB 的跨会话语义记忆系统【免费下载链接】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/rufloruflo-rag-memory 是 ruflo原 Claude Flow生态中负责长期语义记忆的核心插件它以 AgentDBSQLite vector_indexes为持久化底座以 HNSW 近似最近邻索引提供高速向量检索并把 Claude Code 原生自动记忆桥接进统一的语义检索空间。读完本文你将掌握该插件的安装、CLI/MCP 双通道操作、六类命名空间的语义划分、五阶段 SmartRetrieval 检索流水线、静态加密开关以及smoke-as-contract的验证机制并能在自己的 Agent 工作流中实现跨会话、跨项目的模式复用与知识召回。插件定位与核心能力ruflo-rag-memory 提供的是典型的 Retrieval-Augmented GenerationRAG记忆能力对 AgentDB 执行语义写入store、语义搜索search与语义召回recall底层依赖HNSW 索引的向量搜索并桥接 Claude Code 的原生自动记忆auto-memory进入 AgentDB使用384 维 ONNX 嵌入all-MiniLM-L6-v2实现统一的跨会话语义检索。插件本身是消费方它不拥有底层存储实现而是站在 ruflo-agentdb 的 AgentDB 后端与 ruflo-ruvector 高级向量算子之上面向用户暴露一套简洁的记忆操作面。按照 ADR-0001 插件契约 的定义该插件由 1 个 Agentmemory-specialist、2 个技能memory-bridge、memory-search和 2 个命令/recall、/ruflo-memory构成插件元数据版本为 0.2.1关键字包含mcp、claude-memories、bridged-memory。快速上手跨会话存储与召回存储一条想记住的模式然后在任意会话甚至跨项目里用语义去搜它——这是该插件最核心的使用闭环# 存下一条要记住的模式 npx ruflo memory store --key oauth-flow --value OAuth2 with pkce for SPAs, use refresh tokens --namespace patterns # 之后甚至跨项目用语义召回 npx ruflo recall oauth single page app # 按 key 精确取回条目 npx ruflo memory retrieve --key oauth-flow --namespace patterns在 Agent 提示词Prompt中使用 MCP 工具做上下文注入# In your Claude Code agent prompt: const context await memory_search({ query: authentication patterns, limit: 3 }); # Returns top 3 semantic matches from all sessions完整的多会话示例参见 EXAMPLES.md例如第一天存入pattern-concurrent-queue使用带信号量的有界队列做并发任务处理第二天在另一个项目里执行npx ruflo recall concurrent queue safe processing即可直接命中该模式修复竞态条件后存入solutions命名空间并打上--tags async,cleanup,race再次遇到相似问题时可立即召回修复方案。安装与依赖通过 Claude Code 插件目录安装claude --plugin-dir plugins/ruflo-rag-memory依赖要求ruflo-core插件提供 MCP 服务器所有memory_*/agentdb_*MCP 工具均由它对外暴露CLI 兼容性固定钉在claude-flow/cliv3.6 的 majorminor 版本线上验证契约bash plugins/ruflo-rag-memory/scripts/smoke.sh是插件通过门槛见下文验证一节。命令体系详解插件的命令定义在 commands/ruflo-memory.md 与 commands/recall.md 中操作面覆盖 store / search / retrieve / list / delete / consolidate / bridge# 存储一条记忆条目 memory store --key pattern-auth --value JWT with refresh tokens --namespace patterns # 语义搜索HNSW 索引 memory search --query authentication patterns --namespace patterns --limit 5 # 按 key 取回 memory retrieve --key pattern-auth --namespace patterns # 列出条目 memory list --namespace patterns --limit 10 # 删除 memory delete --key old-entry --namespace patterns # 跨所有命名空间快速语义召回 recall how did we handle rate limiting?各子命令的参数形态与默认行为操作参数说明store--key KEY --value VALUE [--namespace NS]写入记忆条目默认命名空间defaultsearch--query QUERY [--namespace NS] [--limit N] [--hybrid] [--graph-rag]默认走稠密向量检索--hybrid走 ruvector 稀疏稠密融合--graph-rag走多跳检索retrieve--key KEY [--namespace NS]按 key 精确取回list[--namespace NS] [--limit N]列出条目默认 limit 10delete--key KEY [--namespace NS]删除条目consolidate[--namespace NS]去重余弦相似度 0.92 合并、剪枝30 天未触碰且零检索命中、重建 HNSW 索引经hooks worker dispatch --trigger consolidate触发bridge[--all-projects]导入 Claude Code 自动记忆到 AgentDB细节见memory-bridge技能无参数时默认执行memory list。常用命名空间为patterns、tasks、solutions、feedback、security、claude-memories。其中consolidate与 Agent 侧的记忆整合工作流审计 → 去重 → 剪枝 → 压缩 → 重建索引一一对应见 memory-specialist.md。架构与数据流插件在 README.md 中给出了完整的端到端数据流Claude Code Auto-Memory (~/.claude/projects/*/memory/*.md) │ ▼ (ONNX all-MiniLM-L6-v2, 384-dim) Memory Bridge │ ▼ AgentDB (SQLite vector_indexes) │ ├── patterns namespace ├── tasks namespace ├── solutions namespace ├── feedback namespace ├── security namespace └── claude-memories namespace │ ▼ (HNSW ANN index) Semantic Search (HNSW ANN — measured ~1.9x at N20k vs brute force)从源码结构看整条链路的关键节点是Claude Code 的SessionStart钩子在会话启动时把本地 markdown 记忆文件读入 →memory_import_claudeMCP将文件内容用 ONNX 384 维嵌入向量化 → 写入 AgentDB 的claude-memories保留命名空间 → 查询时经 HNSW ANN 索引做语义搜索。Agent 侧memory-specialist的检索流水线见 agents/memory-specialist.md可概括为Query → [Embedding (ONNX 384d)] → [HNSW ANN search] ↓ [Optional: BM25 sparse search] ↓ [RRF Fusion (k60)] ↓ [MMR Reranking (λ0.7)] ↓ [Recency Boost (decay0.95/day)] ↓ Top-K Results其中 RRF 融合常数 k60、MMR 的 λ0.7、recency 衰减 0.95/天均为实现中采用的默认参数。命名空间体系语义分桶不同意图的内容写入不同命名空间是保证召回精度的第一道关卡命名空间用途示例 Keypatterns成功过的代码/设计模式pattern-auth-jwttasks任务上下文与结果task-refactor-apisolutionsBug 修复与解决方案fix-race-conditionfeedback用户反馈与纠正feedback-test-stylesecurity漏洞模式vuln-sql-injectionclaude-memories桥接进来的 Claude Code 记忆auto-importedmemory-search技能给出了命名空间选型建议见 skills/memory-search/SKILL.mdpatterns回答How did we handle X?tasks回答What was the context for Y?solutions回答How did we fix Z?feedback回答What did the user prefer?security面向Known vulnerabilities in...省略命名空间参数则搜索全部命名空间。Agent 侧还定义了各命名空间的保留策略patterns/solutions/feedback/security永久保留tasks保留 90 天claude-memories随会话启动同步。Claude Memory Bridge把 Claude Code 自动记忆搬进 AgentDBClaude Code 会把会话记忆以 markdown 文件形式保存在~/.claude/projects/*/memory/*.md。memory-bridge技能见 skills/memory-bridge/SKILL.md负责把它们自动导入 AgentDB读取全部记忆文件当前项目或全部项目用 ONNX all-MiniLM-L6-v2 生成 384 维嵌入存入 AgentDB 的claude-memories命名空间并建立 HNSW 索引与已有条目去重余弦相似度 0.95使统一语义搜索覆盖全部记忆来源。# 手动导入当前项目 /memory-bridge # 导入所有项目 /memory-bridge --all-projects # 检查桥接健康状态 # Via MCP: memory_bridge_status({})完整操作流程分为五步先调memory_bridge_status({})检查 Claude 文件数、AgentDB 条目数、SONA 状态与连接状态再执行memory_import_claude({})或memory_import_claude({ allProjects: true })CLI 备选为node .claude/helpers/auto-memory-hook.mjs import-all导入后再次用memory_bridge_status核对条目数与文件数一致需要时执行--dedupe合并近重复项最后用memory_search_unified验证跨源检索。检索结果带来源归属claude-code、auto-memory或agentdb。自动导入通过SessionStart钩子触发手动调用仅用于三种场景首次全量导入所有项目、正常会话之外的批量记忆变更、模型更新后强制重新向量化。SmartRetrieval五阶段检索流水线ADR-090--smart模式启用一套五阶段检索流水线目标是提升跨会话召回的回忆质量Query expansion查询扩展——基于模板生成查询变体不依赖 LLMMulti-query fan-out RRF多查询扇出 倒数秩融合——对各变体的检索结果做 Reciprocal Rank FusionRecency boost时新性加权——从元数据时间戳做指数衰减MMR diversity最大边界相关去重——基于 token-Jaccard 的 MMR 重排Session round-robin会话轮询交错——把来自不同会话的结果交错排列。# CLI npx claude-flow/clilatest memory search --query auth patterns --smart --limit 10 # MCP mcp__plugin_ruflo-core_ruflo__memory_search({ query: auth patterns, smart: true, limit: 10 })最适合多会话召回、时间类查询上周我们是怎么决策的以及需要多样化结果集的场景。按 commands/recall.md 的说明/recall命令本质上是跨全部命名空间patterns/tasks/solutions/feedback/security/claude-memories的语义召回结果按复合分排序余弦相似度 × MMR 多样性 × 时新性衰减无参数时退化为memory list --limit 10显示最近条目。统一检索与检索策略选型memory_search_unified同时查询所有命名空间并做 MMR 多样性重排# Via MCP: memory_search_unified({ query: auth security, limit: 5 }) # Via CLI: npx claude-flow/clilatest memory search --query auth security --limit 5memory-search技能按查询类型给出了策略选型表查询类型策略理由事实型查找稠密检索HNSW快、单跳、精确语义匹配多跳推理Graph RAG沿文档间实体关系追踪关键词 语义混合稀疏 稠密 RRF融合 BM25 精确性与嵌入召回率需要多样化结果稠密 MMR 重排去除近重复最大化覆盖面近期上下文稠密 时新性加权优先时间上相关的条目探索性查询Graph RAG 社区发现发现聚类与潜在关联技能内对策略收益给出量化说明混合检索对关键词语义型查询提升 20–49%Graph RAG 对推理型查询提升 30–60%这些为该插件技能文档中声明的经验数据来自其 ruvector 集成路径。复杂查询还可通过agentdb_context-synthesize把多个命名空间的结果合成上下文。HNSW 性能数据与暴力检索的对比插件 README 引用 docs/reviews/intelligence-system-audit-2026-05-29.md 与 scripts/benchmark-intelligence.mjs 中的实测结果操作相对暴力检索说明向量检索N5k快约 3.2x–4.7xruvector NAPIrecall10 约 0.99向量检索N20k快约 1.9xANN 在超过交叉点后胜出向量检索交叉点以下打平或更慢小数据量下暴力检索更优文档特别澄清此前流传的150x–12,500x数据是暴力检索回退路径的伪影artifact在审计测试台audit harness下无法复现——这提醒使用者ANN 的收益存在索引规模交叉点HNSW 在 N 较大时才有显著优势小规模数据集不必强上 ANN。该性能测量方法可复现对应基准脚本位于 scripts/benchmark-intelligence.mjs。与 ruvector 的高级算子集成当同时加载ruflo-ruvector插件时rag-memory 把高级检索委托给 ruvector 后端FlashAttention-3——O(N) 内存复杂度的注意力实现Graph RAG——多跳知识检索混合检索稀疏 稠密——RRF 融合DiskANN——大规模持久化索引。对应的 CLI 形态来自 commands/ruflo-memory.md 与memory-search技能# 混合检索稀疏 稠密 npx ruvector search QUERY --hybrid --limit 5 # Graph RAG多跳 npx ruvector search QUERY --graph-rag --limit 5 # 大脑知识检索 npx ruvector brain search query桥接进 AgentDB 的记忆在 ruvector 加载后也会被其索引从而支持跨会话的混合检索与多跳查询。静态加密opt-in 的 AES-256-GCM 落盘加密ruflo 3.6.25插件写入的.swarm/memory.dbSQLite blob支持按 ADR-096-encryption-at-rest 实现的 opt-in 静态加密。启用条件为同时设置CLAUDE_FLOW_ENCRYPT_AT_REST1与CLAUDE_FLOW_ENCRYPTION_KEY每次写入.swarm/memory.db时以新的 12 字节 IV 加密writeFileRestricted({encrypt:true})读取走readFileMaybeEncrypted(path, null)——通过魔数RFE1嗅探使迁移窗口期内遗留的明文 memory.db 文件保持可用嵌入向量随 SQLite blob 一并加密Phase 1 无需单独的列级加密任何一比特翻转都会导致 GCM 认证失败并产生解密错误而非静默损坏。用ruflo doctor -c encryption可验证门控状态。默认关闭开启不需要迁移步骤读取时嗅探明文字节开启后的首次写入会把 DB 重写为加密格式。密钥来源按优先级为CLAUDE_FLOW_ENCRYPTION_KEYbase64 编码的 32 字节→ OS 钥匙串keytarmacOS Keychain / Windows DPAPI / Linux libsecret→ 交互式口令 scrypt KDF派生密钥仅驻留进程内存salt 存于~/.claude-flow/.kdf-salt0600 权限若开启开关但无任何密钥来源可用CLI 会立即报错而非静默写明文fail-closed 姿态。加密格式为magic(4B RFE1) iv(12B) ciphertext tag(16B)。命名空间协调claude-memories 保留命名空间消费者契约该插件是claude-memories保留命名空间的权威用户侧消费者canonical consumer。保留命名空间契约由 ruflo-agentdb ADR-0001 的 Namespace convention 一节定义AgentDB 插件自己拥有三个**不可被遮蔽MUST NOT be shadowed**的保留命名空间——patternReasoningBank 回退写入处、claude-memoriesClaude Code 自动记忆桥接目标、defaultmemory_store默认值其余下游插件按plugin-stem-intent的 kebab-case 规则命名自己的命名空间。本插件的自动导入流程严格遵循该契约Claude Code SessionStart hook → memory_import_claude (MCP) → claude-memories namespace (reserved, ruflo-agentdb owned) → exposed by this plugins memory-bridge skill memory_search_unified要点是本插件消费claude-memories但不拥有它patterns/tasks/solutions/feedback/security等非保留命名空间全部经由memory_*namespace-routed工具访问全程不做错误的命名空间路由无agentdb_hierarchical-*或带命名空间参数的agentdb_pattern-store调用。这一契约关系在 ADR-0001-rag-memory-contract 中被正式文档化。验证smoke-as-contract插件的通过即契约验证脚本是 scripts/smoke.sh执行方式bash plugins/ruflo-rag-memory/scripts/smoke.sh # Expected: 10 passed, 0 failed脚本内含 10 项结构化检查覆盖①plugin.json声明 0.2.1 且含mcp/claude-memories/bridged-memory关键字② 两个技能 1 个 Agent 2 个命令存在且 frontmatter 合法③ README 钉死claude-flow/cliv3.6④ README 引用 ruflo-agentdb 命名空间约定⑤claude-memories消费者契约命名空间名、memory_import_claude、SessionStart均被文档化⑥ 引用memory_search_unified⑦ 静态加密块完整ADR-096、AES-256-GCM、RFE1 魔数⑧ ADR-0001 存在且状态为 Accepted⑨ 无19 AgentDB controllers过期表述回归⑩ 技能中无通配符allowed-tools授权。相关插件与生态定位ruflo-agentdb——完整的 AgentDB 控制器桥15 个agentdb_*MCP 工具命名空间约定的所有者持有claude-memories保留命名空间ruflo-ruvector——高级向量运算FlashAttention-3、Graph RAG、混合检索本插件的高级检索后端ruflo-rvf——便携 RVF 记忆格式支持跨机器导出/导入ruflo-knowledge-graph——对记忆做实体抽取与图遍历ruflo-intelligence——从检索模式中学习轨迹SONA。LicenseMIT。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考