ruflo-agentdb 插件完全指南AgentDB 控制器桥、RuVector 嵌入与 RaBitQ 量化搜索实战【免费下载链接】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-agentdb 是 Ruflo 原生 agent meta-harness中承载记忆子系统的底层 substrate 插件它把三条 CLI MCP 工具族——agentdb_*控制器桥15 个工具、embeddings_*RuVector ONNX 引擎10 个工具、ruvllm_hnsw_*WASM 支撑的模式路由器3 个工具——包装成可被 Agent 发现和调用的 skills 与 commands。ruflo-browser、ruflo-rag-memory、ruflo-intelligence等下游插件都组合在这层 substrate 之上因此本插件同时拥有命名空间约定namespace convention和整层 substrate 的 smoke 契约。读完本文你将掌握插件安装与兼容性边界、29 个控制器7 个初始化层级的真实清单、RaBitQ 1-bit 量化32× 内存压缩工作流、HNSW 三档调优、跨插件命名空间规范以及 13 项编号检查 3 项文档不变式的验证机制。插件定位与安装ruflo-agentdb 是文档化包装 契约定义型插件它自身不重新实现记忆功能而是把claude-flow/cliv3.6.x 已暴露的 MCP 工具面整理成可发现、可验证的 skills/commands并对外输出 namespace 规范与 fallback 语义供下游插件消费。安装方式通过 Ruflo 插件市场/plugin marketplace add ruvnet/ruflo /plugin install ruflo-agentdbruflo插件元数据定义在 plugins/ruflo-agentdb/.claude-plugin/plugin.json当前版本0.3.1keywords 包含agentdb、ruvector、hnsw、embeddings、vector-search、rabitq、quantization、namespace-convention、controller-bridge、mcp。兼容性边界CompatibilityCLI锁定claude-flow/cliv3.6 的 majorminorv3.6 内的 patch 升级预期为 no-op。AgentDBCLI 内置agentdb^3.0.0-alpha.11。插件不对 npm 包做版本锁定——AgentDB 内部版本如 alpha.11 → alpha.12不是本插件的契约范围。验证以捆绑的 smoke 脚本为唯一真源bash plugins/ruflo-agentdb/scripts/smoke.sh。只要 smoke 在你的 CLI 版本上通过插件契约即成立。三大 MCP 工具族插件文档化的完整工具面插件面向三个工具族来源均为v3/claude-flow/cli/src/mcp-tools/下的实现文件工具族数量能力源码位置agentdb_*15控制器桥分层 store/recall、语义路由、pattern store/search、因果边、上下文合成、批量操作、合并、反馈、会话agentdb-tools.tsembeddings_*10384 维 ONNXall-MiniLM-L6-v2、HNSW 搜索、双曲Poincare嵌入、神经 substrate、RaBitQ 1-bit 量化32× 内存压缩embeddings-tools.tsruvllm_hnsw_*3WASM 支撑的模式路由器容量上限约 11 个高优先级 pattern区别于大规模 embeddings HNSW 路径ruvllm-tools.ts15 个agentdb_*工具的完整清单agentdb_health、agentdb_controllers、agentdb_pattern-store、agentdb_pattern-search、agentdb_feedback、agentdb_causal-edge、agentdb_route、agentdb_session-start、agentdb_session-end、agentdb_hierarchical-store、agentdb_hierarchical-recall、agentdb_consolidate、agentdb_batch、agentdb_context-synthesize、agentdb_semantic-route。10 个embeddings_*工具embeddings_init、embeddings_generate、embeddings_compare、embeddings_search、embeddings_neuralsubstrate 级入口常规使用已被_init/_generate覆盖、embeddings_hyperbolicPoincare 球空间适合代码树/组织架构等层级数据、embeddings_status、embeddings_rabitq_build、embeddings_rabitq_search、embeddings_rabitq_status。3 个ruvllm_hnsw_*工具ruvllm_hnsw_createdim384max11、ruvllm_hnsw_add、ruvllm_hnsw_route。注意这是小容量模式路由器不是语料库索引——把它当作对一组精选 pattern 的快速分类器sub-ms 级固定开销不要用于大规模语料搜索。控制器注册表29 个控制器 × 7 个初始化层级插件中任何控制器数量表述都应以运行时工具的报告为准。规范名称清单是 controller-registry.ts 中ControllerNameunion29 个名称分 61 层。运行时检查mcp tool call agentdb_controllers --json初始化顺序遵循 ADR-053controller-registry.ts的INIT_LEVELS层级控制器角色0基础预存在Bootstrap1reasoningBank、hierarchicalMemory、learningBridge、hybridSearch、tieredCache核心智能2memoryGraph、agentMemoryScope、vectorBackend、mutationGuard、gnnService图 安全3skills、explainableRecall、reflexion、attestationLog、batchOperations、memoryConsolidation专门化4causalGraph、nightlyLearner、learningSystem、semanticRouter因果 路由5graphTransformer、sonaTrajectory、contextSynthesizer、rvfOptimizer、mmrDiversityRanker、guardedVectorBackend高级服务6federatedSession、graphAdapter会话管理graphAdapter目前因等待外部 graph-DB 连接而保持禁用ADR-095 跟踪。其余 Level-2/3 安全控制器mutationGuard、attestationLog、gnnService、rvfOptimizer、guardedVectorBackend已由 ADR-095 G7 在 ruflo 3.6.23 中激活。G7 控制器ADR-095 激活附源码出处ADR-095 关闭了五个此前默认禁用的 AgentDB 控制器控制器角色源码gnnService在 AgentDB 因果图上做图神经网络嵌入 关系打分无参构造agentdb/dist/src/services/GNNService.jsrvfOptimizerRuVector 格式压缩——持久化前量化 去重向量块agentdb/dist/src/optimizations/RVFOptimizer.jsmutationGuardWASM 支撑的状态变更证明生成ADR-060agentdb/dist/src/security/MutationGuard.jsattestationLog变更的哈希链审计日志由独立.swarm/attestation.db支撑agentdb/dist/src/security/AttestationLog.jsGuardedVectorBackend用mutationGuardattestationLog包装现有 vectorBackendagentdb/dist/src/backends/ruvector/GuardedVectorBackend.jsCommands 与 Skills命令Commands/agentdb— AgentDB 健康检查、控制器状态、会话管理。标准操作流见 commands/agentdb.md调用agentdb_health检查数据库健康调用agentdb_controllers列出运行时报告的total/active计数——不要硬编码任何数量运行时工具即真源汇总总条目、活跃会话、控制器 active/total、存储大小若available: false桥不可用按 README 的 Bridge unavailable 替换表改用memory_store/memory_search有问题时建议npx claude-flow/clilatest memory init --force重新初始化。/embeddings— RuVector 嵌入引擎状态与操作见 commands/embeddings.mdembeddings_status展示模型all-MiniLM-L6-v2、维度384、HNSW 索引状态、缓存命中率未初始化时调用embeddings_init搜索用embeddings_search支持 namespace 过滤大语料内存受限时走 RaBitQ 量化路径层级数据用embeddings_hyperbolic。Skillsagentdb-querySKILL.md——通过控制器桥查询和管理 AgentDB语义路由、分层召回、因果图、上下文合成、pattern store/search。标准流程agentdb_health→agentdb_session-start→agentdb_hierarchical-storetier 为working|episodic|semantic→agentdb_hierarchical-recall→agentdb_pattern-search→agentdb_context-synthesize→agentdb_causal-edge。功能分组分层store/recall、patternReasoningBank 路由、语义semantic-route、context-synthesize、因果causal-edgegraph-node 后端 桥 fallback、生命周期health/controllers/session、批量batch ≤500 条、consolidate、质量feedback。vector-searchSKILL.md——两条向量搜索路径选型 RaBitQ 量化 三档 HNSW 调优详见下文。命名空间约定Namespace conventionruflo-agentdb 拥有下游插件消费的命名空间约定遵循它可保持跨插件搜索可发现性避免桥中 key 冲突。命名规则plugin-stem-intentkebab-case。已在用的实例插件命名空间ruflo-browserbrowser-sessions、browser-selectors、browser-templates、browser-cookiesruflo-rag-memory使用桥目标claude-memoriesruflo-intelligence使用 fallback 目标pattern保留命名空间不要遮蔽命名空间归属来源patternReasoningBank fallback 写入此处agentdb-tools.ts:144claude-memoriesClaude Code 自动记忆桥目标bridgedefaultmemory_store默认memory-tools.ts命名空间实际上作用于哪里关键路由语义命名空间不是通用参数需仔细读路由规则memory_*和embeddings_search按命名空间路由——需要传 namespaceagentdb_hierarchical-*按tierworking|episodic|semantic路由——namespace 参数被忽略agentdb_pattern-*经由 ReasoningBank 控制器路由——namespace 参数被忽略agentdb_causal-edge经由因果图路由——namespace 参数被忽略。不要向agentdb_pattern-store传namespace: browser-cookies期待过滤——它会被静默丢弃。GC 姿态与命名护栏本插件不做命名空间的 GC。需要生命周期的消费插件如browser-sessions在purge后自己通过memory_deleteagentdb_consolidate删除如需清理请自行调度。命名护栏命名空间不应包含:与桥内 key 分隔符冲突、必须≤200 字符、必须通过validateIdentifier即agentdb-tools.ts:122使用的同一校验器。Claude Code 如何向 AgentDB 填充数据claude-memories保留命名空间由 Claude Code 自己的自动记忆桥填充而非用户直接调用。两种机制机制触发写入内容memory_import_claudeMCP 工具手动或 hook 驱动读取~/.claude/projects/*/memory/*.md解析 YAML frontmatter切分 section以 384 维嵌入存储。allProjects: true时导入全部 Claude 项目.claude/helpers/auto-memory-hook.mjsSessionStart导入和SessionEnd同步——在.claude/settings.json中接线import→ 为当前项目调用桥sync→ 把 AgentDB 洞察回流到~/.claude/projects/*/memory/MEMORY.md检查或强制刷新# 桥里现在有什么 mcp tool call memory_bridge_status --json # 从 Claude Code 项目记忆强制重新导入 mcp tool call memory_import_claude --json -- {allProjects: true} # 跨命名空间搜索claude-memories auto-memory patterns tasks feedback mcp tool call memory_search_unified --json -- {query: your query}memory_search_unified默认搜索[default, claude-memories, auto-memory, patterns, tasks, feedback]——这些正是桥实际填充的命名空间。default是兜底auto-memory与claude-memories不同auto-memory 保存桥内部缓存claude-memories 保存解析后的*.mdsection。复数化陷阱Pluralization gotchaReasoningBank fallback 写入pattern单数其他 hookshooks pretrain、神经训练路径写入patterns复数。它们是不同的命名空间。不确定时用memory_list --namespace pattern和memory_list --namespace patterns确认数据实际落在哪。在确认之前不要重构下游代码去修复复数化。Hook 集成约定哪些命名空间自动累积状态多个 Claude Code hook 会向 AgentDB 写入。消费插件应知道哪些命名空间自动累积、哪些需显式调用Hook调用的工具目标命名空间说明SessionStartmemory_import_claude经 auto-memory-hook.mjsclaude-memories每次会话启动时导入~/.claude/projects/*/memory/*.mdSessionEndauto-memory-hook.mjs sync桥 →MEMORY.md将 AgentDB 洞察回流到 Claude Code 的 MEMORY.mdpost-task --train-neuralagentdb_pattern-storeReasoningBankpattern注册表不可用时memory-store-fallback为 SONA 蒸馏存储任务完成模式pretrain一次性memory_storepatterns复数引导学习语料trajectory-begin/step/endruvector hooksruvector substrate独立插件sona/agentdb 命名空间由ruflo-ruvector处理见 plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md对消费插件的三点启示不要重复写入。已经调用hooks post-task --train-neural就不必再手动memory_store --namespace pattern二选一。不要自己刷新claude-memories。每次 SessionStart 会自动导入手动memory_import_claude只用于强制刷新不是稳态操作。识别 fallback 响应。当agentdb_pattern-store返回controller: memory-store-fallback时数据仍然落盘了。运营 fallback三个可分支的降级路径桥代码中存在三个 fallback消费方应将其视为可分支语义而非软失败。Pattern-store fallbackADR-093 F4当 ReasoningBank 控制器注册表返回 null 时agentdb_pattern-store直写memory_store并返回{ success: true, patternId: pattern-..., controller: memory-store-fallback, note: ReasoningBank controller registry unavailable. Pattern persisted via memory_store. }controller: memory-store-fallback表示 pattern已持久化——不是错误。源码见agentdb-tools.ts:138-161。Causal-edge 的 graph-node 原生后端ADR-087agentdb_causal-edge优先尝试原生ruvector/graph-node后端失败时回退到桥。响应中包含_graphNodeBackend: true表示原生后端处理了该调用。源码见agentdb-tools.ts:267-290。桥不可用Bridge unavailable当bridgeHealthCheck()返回 nullclaude-flow/memory未安装或controller-registry.ts缺失时每个agentdb_*handler 返回{ success: false, error: AgentDB bridge not available — claude-flow/memory not installed... Use memory_store/memory_search tools instead. }桥不可用时的替换表不可用的agentdb_*改用agentdb_hierarchical-store/_recallmemory_store/memory_searchagentdb_pattern-store/_searchmemory_store --namespace pattern/memory_search --namespace patternagentdb_semantic-routeembeddings_searchagentdb_context-synthesizememory_search_unifiedRaBitQ 量化搜索32× 内存压缩的 5 步工作流针对 ≥5,000 向量和/或内存受限环境使用 RaBitQ 1-bit 量化工作流低于 5,000 向量时重建成本超过收益请用标准路径步骤工具用途1embeddings_init引擎预热2embeddings_rabitq_build语料加载后一次性构建 1-bit 索引3embeddings_rabitq_searchHamming 预过滤返回 top-N 候选 ID廉价4embeddings_search在候选集上可选的全精度精确重排5embeddings_rabitq_status索引健康、内存占用、构建耗时注意embeddings_rabitq_search只返回候选 ID——第 4 步的重排由调用方负责对应embeddings-tools.ts:911的 docstring。不重排结果是近似的重排后可在 32× 更低内存下获得全精度质量。实测性能来自scripts/benchmark-intelligence.mjsruvector NAPI 后端recall10 ≈ 0.99方法相对暴力扫描的加速暴力扫描基线HNSWN5,000约 3.2×–4.7× 更快HNSWN20,000约 1.9× 更快HNSW低于交叉点的小 N持平或慢于暴力扫描RaBitQ 量化32× 内存压缩N≈14.7k 时 0.60 ms/查询ruvllm_hnsw_routen≤11每次路由 sub-ms固定开销旧文档中的150×–12,500×数字是暴力扫描 fallback 时代的产物已被退役参见项目 CLAUDE.md V3 Performance Targets。大型embeddings_search路径才对应 HNSW 加速WASM 的ruvllm_hnsw_*上限约 11 个 patternruvllm-tools.ts:58两者不可混为一谈。HNSW 调优三档操作点HNSW 暴露三个旋钮权衡召回率与延迟。默认值下的头条数字不代表所有负载档位efSearchM适用场景recall-first20032规划期间的 pattern 召回质量优先于毫秒balanced默认6416通用语义召回latency-first168热点路径路由p99 延迟敏感efSearch通过ruvllm_hnsw_create传入ruvllm-tools.ts:64M目前是注册表层设置未通过 MCP 暴露如需 MCP 可调可提出后续 ADRefConstruction在 lite 索引中默认 200hnsw-index.ts:537。双曲嵌入embeddings_hyperbolic则映射到 Poincare 球空间距离为测地距离而非余弦距离适合代码树、组织架构等层级数据。验证smoke 即契约bash plugins/ruflo-agentdb/scripts/smoke.sh # 预期输出10 passed, 0 failed离线模式 13 项编号检查 3 项文档不变式smoke.sh 是插件契约的验证机制默认离线安全、CI 友好通过--live标志可叠加真实 MCP 工具调用需要运行中的 daemon。它调用每个文档化的 MCP 工具、演练 RaBitQ 工作流、并做源码级检查 fallback 路径不存在 env-var 开关可在运行时强制 fallback。核心检查项文档不变式 INV1用户面向文档中不再出现 19 controllers 表述ADR 目录除外因 ADR 记录历史文档不变式 INV2embeddings_rabitq_build/_search/_status三件套在 vector-search SKILL 中全部有文档文档不变式 INV3README 含 Namespace convention 与 Reserved namespaces 小节插件版本 0.3.1 且 keywords 含rabitq、quantization、namespace-convention、controller-bridgeREADME/agent/command/skill 四文件全部引用运行时工具agentdb_controllers控制器计数向运行时让位15 个agentdb_*工具名全部在插件文档中出现10 个embeddings_*工具名全部出现且 WASM 上限约 11 patterns 被承认RaBitQ 小节含 5 步配方 rerank 注意项memory-store-fallback字符串在agentdb-tools.ts中可源码检索tier 校验器working|episodic|semantic在源码中可检索MAX_BATCH_SIZE 500agentdb-tools.ts:20存在命名空间护栏文档完整保留列表 冒号规则 200 字符上限自动记忆桥机制文档完整memory_import_claudeauto-memory-hook.mjsmemory_bridge_statusmemory_search_unifiedHook 集成表存在SessionStart、post-task --train-neural、ReasoningBank → pattern复数化陷阱已文档化对比pattern与patterns。该脚本不测试控制器精确计数、不依赖agentdb的具体 minor 版本、不演练被禁用的graphAdapter——这些是明确的反目标。架构决策与关联插件插件演进由 ADR-0001 驱动把过时的 19 controllers 表述替换为运行时工具报告的 29 名注册表、把 RaBitQ 从不可见变为一等公民量化工作流、把 HNSW 从魔法数字变为可调操作点、正式确立命名空间约定契约、把三个既有 fallback 写入文档并用 smoke-as-contract 取代人工核对。ADR 关联的上游决策包括 ADR-053控制器激活管线、ADR-087graph-node 原生后端、ADR-093 F4memory-store-fallback、ADR-095 G7激活五个此前禁用的控制器。相关插件ruflo-rag-memory简单 store/search/recall 接口消费claude-memories保留命名空间、ruflo-intelligenceSONA 神经模式经 ReasoningBank 消费pattern保留命名空间、ruflo-browser组合browser-sessions/-selectors/-templates/-cookies命名空间约定、ruflo-ruvector锁定 ruvector CLI 的兄弟 substrate 插件。本插件按 MIT 协议发布。上手建议安装后用agentdb_healthagentdb_controllers确认桥状态与运行时控制器清单按 How Claude Code populates AgentDB 的三条命令观察claude-memories自动累积语料 ≥5,000 时启用 RaBitQ 工作流任何下游插件在命名命名空间前先读 README 的 Namespace convention 一节避免与pattern/claude-memories/default冲突并记得命名空间字符串只对memory_*与embeddings_search生效。【免费下载链接】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），仅供参考