Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

22.1 KB
Raw Blame

id: ADR-0001 title: Optimize ruflo-agentdb β€” accurate surface, quantization opt-ins, controller-managed namespacing, smoke-as-contract status: Proposed date: 2026-05-04 authors: - planner (Claude Code) tags: [plugin, agentdb, mcp, hnsw, rabitq, controllers, namespacing, smoke-test]

Context

Today's ruflo-agentdb

ruflo-agentdb is a thin documentation wrapper around three MCP tool families exposed by @claude-flow/cli: agentdb_* (controller bridge), embeddings_* (RuVector ONNX engine), and ruvllm_hnsw_* (WASM-backed pattern router). The plugin ships six files:

  • .claude-plugin/plugin.json:2 β€” name: "ruflo-agentdb", version: "0.2.0", keywords agentdb, ruvector, hnsw, embeddings, vector-search.
  • README.md:16 β€” claims 19 AgentDB controllers; README.md:49 β€” calls out HNSW "150x-12,500x" speedup and "384-dim ONNX" embeddings.
  • agents/agentdb-specialist.md:15 β€” header MCP Tools (19 Controllers) then enumerates eight agentdb_* tool prefixes plus embeddings_* and ruvllm_hnsw_* as bullet groups.
  • commands/agentdb.md:8 β€” invokes agentdb_health and agentdb_controllers and prints "all 19 controllers and their status".
  • commands/embeddings.md:8 β€” invokes embeddings_status/embeddings_init/embeddings_search. Mentions the model and dimension count but no quantization or HNSW tuning.
  • skills/agentdb-query/SKILL.md:5 β€” allowed-tools enumerates 14 agentdb_* tools (correct count); SKILL.md:26 repeats the "19 Controllers" framing.
  • skills/vector-search/SKILL.md:5 β€” allowed-tools enumerates seven embeddings_* and three ruvllm_hnsw_* tools; SKILL.md:46–50 is a performance table claiming HNSW (n=10,000) 12,500x faster.

There is no scripts/, no docs/ (the ADR file path is the first under that subtree), and no version pin against the underlying agentdb npm package or the CLI MCP surface.

What AgentDB / the CLI actually exposes

Counted directly from source on 2026-05-04 (HEAD of main):

Surface Plugin claim Real count Source
agentdb_* MCP tools "19 controllers" β†’ implies tools 15 tools v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts:629–645 (agentdbTools export array)
embeddings_* MCP tools 7 enumerated in skill 10 tools v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts:159, 260, 328, 418, 520, 717, 835, 910, 926, 970
ruvllm_hnsw_* MCP tools 3 enumerated 3 tools (correct) but capacity is ~11 patterns, not 10,000 v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts:57–58 ("Max ~11 patterns (v2.0.1 limit)")
Controllers in ControllerRegistry "19" 29 names across 6 init levels: 13 AgentDB-layer + 16 CLI-layer v3/@claude-flow/memory/src/controller-registry.ts:34–73 (type ControllerName) and :160–174 (INIT_LEVELS)
RaBitQ 1-bit quantization Not documented 32Γ— compression, two-phase Hamming-prefilter + exact-rerank pipeline embeddings_rabitq_build, _search, _status at embeddings-tools.ts:910, 926, 970; impl at v3/@claude-flow/cli/src/memory/rabitq-index.ts
HNSW tuning (efSearch, efConstruction, M) Not surfaced in any skill efSearch accepted as a constructor param on ruvllm_hnsw_create; efConstruction defaulted to 200 in the lite index; M not exposed via MCP ruvllm-tools.ts:64, v3/@claude-flow/memory/src/hnsw-index.ts:537
Pattern-store fallback when ReasoningBank unavailable Not documented ADR-093 F4: when controller registry returns null, agentdb_pattern-store writes to memory_store with controller: 'memory-store-fallback' agentdb-tools.ts:138–161
Native graph-node backend for causal edges Not documented ADR-087: agentdb_causal-edge tries graph-node first, falls back to bridge agentdb-tools.ts:267–290
agentdb npm dep version Not pinned in plugin agentdb: ^3.0.0-alpha.11 in CLI's package.json:120; pnpm-lock.yaml resolves multiple versions (1.6.1, 2.0.0-alpha.3.4/3.7, 3.0.0-alpha.10/11) v3/@claude-flow/cli/package.json:120; v3/node_modules/.pnpm/

The "19 controllers" number appears to be a stale snapshot from before ADR-095 G7 closed five disabled-by-default controllers (gnnService, rvfOptimizer, mutationGuard, attestationLog, GuardedVectorBackend) and before ADR-053 added mmrDiversityRanker, contextSynthesizer, batchOperations, memoryConsolidation, hierarchicalMemory to the CLI-layer registry. The plugin README block on G7 (README.md:22–35) is accurate about the five activated controllers and about graphAdapter still being disabled β€” but the surrounding "19" framing is not.

What's missing entirely

Beyond the count drift, the plugin omits four substantive capabilities of the substrate it documents:

  1. Quantization. embeddings_rabitq_* provides 32Γ— memory reduction at index time. CLAUDE.md's V3 perf targets explicitly call out "Memory Reduction 50–75% with quantization" as Implemented; the plugin advertises HNSW speedup but never mentions quantization.
  2. Index tunables. efSearch / efConstruction / M directly control the recall/latency tradeoff; the plugin presents HNSW as a binary "150–12,500Γ—" claim with no operating points.
  3. Namespacing convention. Every consumer plugin (ruflo-browser defines browser-sessions / browser-selectors / browser-templates / browser-cookies in its ADR-0001 Β§3; ruflo-rag-memory references claude-memories / patterns / tasks / solutions; ruflo-intelligence writes to pattern) reinvents namespace naming. There is no contract from ruflo-agentdb about how namespaces should be named, what they should contain, or how they are GC'd. The agentdb_* tools mostly do not even take a namespace parameter β€” they route to controllers (reasoningBank, hierarchicalMemory, causalGraph) β€” but the CLI fallback memory_store and embeddings_search do take namespace strings, so the surface is mixed and undocumented.
  4. Token-efficiency path. The repo ships getCompactContext on the TokenOptimizer (v3/@claude-flow/integration/src/token-optimizer.ts:109), and agentdb_context-synthesize exists for the same goal at the MCP layer. Neither is surfaced by the plugin as a "use this when you want compact retrieved context for an LLM call" workflow.

Why now

ruflo-agentdb is the substrate plugin β€” ruflo-browser (ADR-0001) explicitly depends on AgentDB namespaces and controller-managed sessions; ruflo-rag-memory and ruflo-intelligence route through the same controllers; the whole "memory-as-substrate" story in CLAUDE.md rests on it. Documentation drift in this plugin is contagious β€” every downstream plugin inherits the wrong tool count, the wrong controller count, and the missing quantization story. We just fixed the same class of drift in ruflo-ruvector (ADR-0001 there); the same pattern applies here.

Decision

We propose six changes to ruflo-agentdb. None requires modifying AgentDB itself; all are plugin-local edits plus one new smoke script.

1. Replace "19 controllers" with the real registry, and pin its source

The plugin currently treats "19" as a magic number repeated across five files. Replace it with two explicit references to the real source:

  • README.md swaps the blanket "19 AgentDB controllers" line for a table generated from INIT_LEVELS at controller-registry.ts:160–174. Group by init level (0–6) so the dependency story is visible. Mark each row as one of: active by default, gated on dependency, disabled-pending-ADR. Cite the source file + line.
  • agents/agentdb-specialist.md drops the "19 Controllers" header and replaces the bullet groups with a one-line "controllers are listed at runtime via agentdb_controllers; see registry source for the canonical list."
  • commands/agentdb.md drops the "all 19 controllers" string from step 2; the step now reads "list whatever the runtime reports".
  • skills/agentdb-query/SKILL.md Β§"19 Controllers" becomes "Available controller groups" and lists only the four functional categories already in the skill (hierarchical, pattern, semantic, causal).

The point isn't to memorize the count β€” it's to stop hard-coding any count. The runtime tool agentdb_controllers is already the source of truth; documentation should defer to it.

2. Surface embeddings_rabitq_* as a first-class quantization workflow

Add a new section to skills/vector-search/SKILL.md titled "Quantized search (32Γ— memory)" with:

  • A 5-step recipe: embeddings_init β†’ embeddings_rabitq_build (one-time, after corpus is loaded) β†’ embeddings_rabitq_search (Hamming-prefilter to top-N candidates) β†’ optional rerank via embeddings_search (exact, on the candidate set) β†’ embeddings_rabitq_status for index health.
  • A "when to use" rule: corpora β‰₯ 5,000 vectors and/or memory-constrained environments. Below that, the rebuild cost outweighs the savings.
  • The exact tool names added to the allowed-tools frontmatter line.
  • A note: RaBitQ _search returns candidate IDs only; the rerank step is the user's responsibility (mirrors the docstring at embeddings-tools.ts:911).

embeddings_neural (line 520) is the other undocumented embeddings_* tool. It is the substrate-level entry point and is implicitly covered by embeddings_init/_generate; we will add a one-line note to commands/embeddings.md acknowledging it exists, and stop there. We do not invent a second skill for it.

3. Expose HNSW tuning as a deliberate, documented choice

The plugin currently presents HNSW as a magic number (12,500x faster at vector-search/SKILL.md:50). That number is the published ceiling under specific parameters; without surfacing those parameters the claim is unfalsifiable.

skills/vector-search/SKILL.md gets a new "Tuning" section that documents three operating points and ties each to a tool call:

Profile efSearch M Use case
recall-first 200 32 Pattern recall during planning, search quality matters more than ms
balanced (default) 64 16 General-purpose semantic recall
latency-first 16 8 Hot-path routing where p99 latency matters

efSearch is passed via ruvllm_hnsw_create (ruvllm-tools.ts:64). M is not currently MCP-exposed; we document it as a registry-level setting with a forward reference: "raise as a follow-up ADR if M should be MCP-tunable."

We also fix the speed claim. The 12,500Γ— number is for the embeddings/HNSW path inside @claude-flow/memory, not for the WASM ruvllm_hnsw_* tools β€” those are capped at ~11 patterns (ruvllm-tools.ts:58). The skill currently lumps them together. The new copy reads: "embeddings_search uses the @claude-flow/memory HNSW index (large-scale, 150–12,500Γ—). ruvllm_hnsw_* is a separate WASM-backed router for ≀11 high-priority patterns β€” useful for hot routes, not for corpus search."

4. Define a namespace convention contract for downstream plugins

Add a new section to README.md titled "Namespace convention" that ruflo-agentdb owns and downstream plugins consume. The contract:

  • Naming: <plugin-stem>-<intent> kebab-case. Examples: browser-sessions, browser-selectors, browser-cookies (ruflo-browser), claude-memories (ruflo-rag-memory's bridge), pattern (ruflo-intelligence ReasoningBank fallback).
  • Three reserved namespaces owned by the AgentDB plugin itself, not to be shadowed: pattern (ReasoningBank fallback writes here per agentdb-tools.ts:144), claude-memories (Claude Code auto-memory bridge target), default (memory_store default per memory-tools.ts:194).
  • Controller routing: tools in the agentdb_hierarchical-* family route by tier (working|episodic|semantic) not by namespace; tools in the agentdb_pattern-* family route by ReasoningBank, again not by namespace. Document explicitly that namespace strings only apply to memory_* and embeddings_search paths. This stops downstream plugins from passing a namespace arg to agentdb_pattern-store and being silently confused when it's ignored.
  • GC posture: ruflo-agentdb does not GC namespaces. Consumer plugins that want lifecycle (e.g., browser-sessions after purge) own their own deletion via memory_delete + agentdb_consolidate. Document this so consumers don't expect cleanup we don't provide.
  • Naming guardrail: a namespace SHOULD NOT contain : (collides with key-internal delimiters used in the bridge), MUST be ≀200 chars, and MUST pass validateIdentifier (the same validator already used in agentdb-tools.ts:122).

This section is the load-bearing artifact for cross-plugin discipline. Without it, every plugin author re-invents.

5. Document the operational fallbacks that already exist

Three fallback paths exist in the bridge code and are invisible in the plugin's docs:

  • Pattern-store fallback (agentdb-tools.ts:138–161, ADR-093 F4): when ReasoningBank's controller registry is unavailable, agentdb_pattern-store returns controller: 'memory-store-fallback'. Document this in agents/agentdb-specialist.md so the agent does not interpret a fallback response as a soft failure.
  • Causal-edge graph-node backend (agentdb-tools.ts:267–290, ADR-087): agentdb_causal-edge tries the native @ruvector/graph-node backend first, then the bridge. Document the _graphNodeBackend: true field so consumers can branch on it.
  • Bridge unavailable (returned by every handler when bridgeHealthCheck returns null): the response is { success: false, error: '...Use memory_store/memory_search instead.' }. Add one paragraph in the README enumerating which memory_* tool replaces which agentdb_* tool when the bridge is unavailable.

6. Smoke test as the contract (mirrors ruvector ADR-0001 Β§5)

Add scripts/smoke.sh (file does not exist yet β€” first one in this plugin). It runs against any environment that has npx @claude-flow/cli@latest available with MCP enabled. Each check is a one-liner around mcp tool call ... --json + jq. The contract is "10 passed, 0 failed".

Numbered checks (this is the verifiable artifact, not the prose above):

  1. agentdb_health returns { available: true, ... }. The bridge is wired.
  2. agentdb_controllers.total >= 15 and agentdb_controllers.active >= 10. The lower-bound assertions are deliberately loose β€” they verify "the registry initialized at all" without hard-coding the 29-name ControllerName union or the 15 agentdb_* MCP tools (which are different counts). If a future ADR removes a default-active controller, raise the floor; do not raise the test to an exact match.
  3. The 15 documented agentdb_* tool names are all callable: 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. Each gets a smoke call with minimal args; non-error response = pass.
  4. The 10 documented embeddings_* tools are all callable: embeddings_init, embeddings_generate, embeddings_compare, embeddings_search, embeddings_neural, embeddings_hyperbolic, embeddings_status, embeddings_rabitq_build, embeddings_rabitq_search, embeddings_rabitq_status.
  5. The 3 documented ruvllm_hnsw_* tools are all callable: ruvllm_hnsw_create (dim=384, max=11), ruvllm_hnsw_add, ruvllm_hnsw_route.
  6. RaBitQ build runs: embeddings_rabitq_build then embeddings_rabitq_status reports available: true.
  7. Pattern-store with the bridge intentionally unavailable returns controller: 'memory-store-fallback'. Caveat β€” this check has a load-bearing unverified assumption: the env-var name MEMORY_BRIDGE_DISABLE=1 was inferred from the fallback code path, not confirmed against the actual gating mechanism in bridgeHealthCheck. Implementer must grep agentdb-tools.ts + memory-bridge.ts for the real switch (it may instead key on AGENTDB_BRIDGE, on a missing AgentDB controller, or on no env var at all). If no clean runtime switch exists, downgrade this check to a code-path inspection (assert the fallback string literal is reachable in source) rather than a runtime assertion.
  8. agentdb_hierarchical-store rejects a tier value not in {working, episodic, semantic} (regression on agentdb-tools.ts:426).
  9. agentdb_batch rejects a 501-element entries array (regression on MAX_BATCH_SIZE = 500 at agentdb-tools.ts:20).
  10. Namespace convention guardrails: memory_store --namespace 'has:colon' is rejected; memory_store --namespace '<205 chars>' is rejected (tests the rule we just documented).

The script does NOT test the controller count exactly, does NOT depend on agentdb being a specific minor version, and does NOT exercise the disabled graphAdapter controller. Those are explicit non-goals.

7. Pinning posture

Following ruvector ADR-0001:

  • Add a "Compatibility" subsection to README.md that states: "Plugin v0.3.x targets @claude-flow/cli v3.6.x with bundled agentdb@^3.0.0-alpha.11. The plugin is documentation-only and does not pin via package.json; the smoke contract is the verification mechanism."
  • Bump .claude-plugin/plugin.json to 0.3.0 when this ADR's changes land. Patch bumps thereafter for accuracy fixes; minor for new namespace-convention rules or new MCP tools surfaced.
  • Plugin pins the CLI's major+minor (v3.6), not the npm agentdb package, because the CLI is the layer the plugin actually invokes. AgentDB internals (e.g., the alpha.11 β†’ alpha.12 bump) are not the plugin's contract.

Consequences

Positive:

  • Every count, tool name, and capability claim in the plugin matches a verifiable line in the source. The "19 controllers" myth is gone.
  • RaBitQ goes from invisible to a documented quantization workflow β€” downstream plugins handling large corpora (ruflo-rag-memory, future ruflo-knowledge-graph integrations) get a 32Γ— memory-reduction story by reference, not by re-discovery.
  • HNSW becomes tunable instead of a magic number. Consumer plugins choose an operating point.
  • A namespace convention exists. ruflo-browser's ADR Β§3 already implements it ad hoc; this ADR formalizes it so the next plugin author doesn't re-derive it.
  • Operational fallbacks (pattern-store fallback, graph-node backend) are now part of the contract; agents can branch on them deterministically.
  • scripts/smoke.sh makes plugin-level regressions catchable in CI.

Negative:

  • Three downstream plugins reference "19 controllers" in their own docs (grep across plugins/). Updating them is a separate, mechanical task β€” but if it's not done, the inconsistency moves rather than disappears.
  • The namespace convention is non-binding (we have no enforcement in the bridge). It documents intent. If a downstream plugin ignores it, the substrate still works β€” it just gets harder to reason about. Future enforcement would be a validate-namespace helper exposed via MCP, but that is out of scope here.
  • Smoke depends on the daemon being healthy and the embeddings backend being warm. Cold-start runs may flake on embeddings_rabitq_build if no vectors are loaded yet. Mitigation: smoke seeds 10 vectors via memory_store before exercising the rabitq path.
  • We do not propose changing agentdb-tools.ts itself. Some of the "19 controllers" claim is upstream framing in the AgentDB README too; we cannot unilaterally fix that, only stop propagating it from the plugin.

Neutral:

  • Plugin version moves 0.2.0 β†’ 0.3.0. Semver-minor because the namespace convention is a new contract for consumers, not a removal.
  • No new MCP tools are introduced. We are surfacing existing surface, not extending it.
  • No change to the .claude-plugin/plugin.json keywords beyond optionally adding rabitq and quantization. Keywords are advisory only.

Verification

A future implementation must satisfy this smoke contract before the ADR moves from Proposed β†’ Accepted:

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

Plus three documentation invariants checked by a one-line grep each:

  • ! grep -rn "19 AgentDB controllers\|all 19 controllers\|19 Controllers" plugins/ruflo-agentdb/ β€” no occurrence remains.
  • grep -q "embeddings_rabitq_build" plugins/ruflo-agentdb/skills/vector-search/SKILL.md β€” quantization workflow is documented.
  • grep -q "Namespace convention" plugins/ruflo-agentdb/README.md β€” namespace contract section exists.

Related

  • plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md β€” pinning + smoke-as-contract precedent (this ADR mirrors Β§5 and Β§6).
  • plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md β€” browser-* namespace family that motivated Β§4 (namespace convention contract).
  • v3/docs/adr/ADR-053-... β€” controller activation pipeline (referenced by the bridge module docstring at memory-bridge.ts:5).
  • v3/docs/adr/ADR-087-graph-node-native-backend.md β€” graph-node backend used as the primary agentdb_causal-edge path.
  • v3/docs/adr/ADR-093-mcp-audit-may-2026-remediation.md β€” F4 introduced the memory-store-fallback controller string surfaced by Β§5.
  • v3/docs/adr/ADR-095-architectural-gaps-from-april-audit.md β€” G7 closed five disabled controllers; the README block README.md:22–35 summarizes G7 correctly.
  • v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts β€” 15 agentdb_* tool definitions (canonical surface for Β§6 check 3).
  • v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts β€” 10 embeddings_* tool definitions including RaBitQ trio at :910–981.
  • v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts β€” 3 ruvllm_hnsw_* tools, ~11-pattern WASM cap at :58.
  • v3/@claude-flow/memory/src/controller-registry.ts:34–73 β€” ControllerName union (canonical 29-name list).
  • v3/@claude-flow/memory/src/controller-registry.ts:160–174 β€” INIT_LEVELS (canonical dependency-ordered grouping).
  • v3/@claude-flow/cli/src/memory/rabitq-index.ts β€” RaBitQ implementation referenced by the quantization workflow in Β§2.
  • v3/@claude-flow/integration/src/token-optimizer.ts:109 β€” getCompactContext token-efficiency path (deferred: Β§6 covers agentdb_context-synthesize only; the integration-layer optimizer is a separate ADR if surfaced).