ruflo-agentdb

The substrate plugin for Ruflo memory. Wraps three CLI MCP families — agentdb_* (controller bridge, 15 tools), embeddings_* (RuVector ONNX engine, 10 tools), and ruvllm_hnsw_* (WASM-backed pattern router, 3 tools) — into discoverable skills and commands. Other plugins (ruflo-browser, ruflo-rag-memory, ruflo-intelligence) compose this substrate; this plugin owns the namespace convention and the smoke contract for the substrate as a whole.

Status: ADR-0001 implemented. Plugin v0.3.0 targets @claude-flow/cli v3.6.x with bundled agentdb@^3.0.0-alpha.11. The smoke contract (10 checks) is the verification mechanism — see docs/adrs/0001-agentdb-optimization.md.

Install

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-agentdb@ruflo

Compatibility

• CLI: pinned to @claude-flow/cli v3.6 major+minor. Patch bumps within v3.6 are expected to be no-op.
• AgentDB: the CLI bundles agentdb@^3.0.0-alpha.11. The plugin does not pin the npm package — internals (alpha.11 → alpha.12 etc.) are not the plugin's contract.
• Verification: the bundled smoke script is the source of truth (bash plugins/ruflo-agentdb/scripts/smoke.sh). If smoke passes against your CLI version, the plugin's contract holds.

Features

• Controller bridge: 15 agentdb_* MCP tools (hierarchical store/recall, semantic routing, pattern store/search, causal edges, context synthesis, batch ops, consolidation, feedback, sessions).
• RuVector embeddings: 10 embeddings_* MCP tools — 384-dim ONNX (all-MiniLM-L6-v2), HNSW search, hyperbolic (Poincare), neural substrate, and RaBitQ 1-bit quantization (32× memory reduction).
• HNSW pattern router: 3 ruvllm_hnsw_* tools (WASM-backed, ≤11 high-priority patterns — distinct from the large-scale embeddings HNSW path).
• Causal knowledge graphs: agentdb_causal-edge (graph-node backend with bridge fallback per ADR-087).

Controllers (real registry, grouped by INIT_LEVELS)

The "controller count" reported anywhere in this plugin is whatever the runtime tool reports. The canonical list of names is the ControllerName union at v3/@claude-flow/memory/src/controller-registry.ts:34-73 (29 names across 6 init levels). Inspect at runtime:

mcp tool call agentdb_controllers --json

Initialization order per ADR-053 (controller-registry.ts:160-174):

graphAdapter is currently disabled pending an external graph-DB connection (tracked in ADR-095). Other Level-2/3 security controllers (mutationGuard, attestationLog, gnnService, rvfOptimizer, guardedVectorBackend) were activated by ADR-095 G7 in ruflo 3.6.23+.

G7 controllers (activated by ADR-095)

ADR-095 closed five previously-disabled AgentDB controllers:

Commands

• /agentdb — AgentDB health, controller status, session management
• /embeddings — RuVector embedding engine status and operations

Skills

• agentdb-query — Query AgentDB with semantic routing and hierarchical recall
• vector-search — HNSW vector search + RaBitQ quantization + 3 tuning profiles

Namespace convention

This plugin owns the namespace convention that downstream plugins consume. Following it keeps cross-plugin search discoverable and avoids accidental key collisions in the bridge.

Naming

<plugin-stem>-<intent> in kebab-case. Examples already in the wild:

Reserved namespaces (do NOT shadow)

Where namespace strings actually apply

Namespace is not a universal parameter. Read the routing carefully:

• memory_* and embeddings_search route by namespace — pass it.
• agentdb_hierarchical-* routes by tier (working|episodic|semantic) — namespace argument is ignored.
• agentdb_pattern-* routes through the ReasoningBank controller — namespace argument is ignored.
• agentdb_causal-edge routes through the causal graph — namespace argument is ignored.

Don't pass namespace: 'browser-cookies' to agentdb_pattern-store and expect filtering. It will be silently dropped.

GC posture

This plugin does not GC namespaces. Consumer plugins that want lifecycle (e.g., browser-sessions after a purge) own their own deletion via memory_delete + agentdb_consolidate. If you need cleanup, schedule it.

Naming guardrails

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).

How Claude Code populates AgentDB

The claude-memories reserved namespace is filled by Claude Code's own auto-memory bridge, not by direct user calls. Two mechanisms:

To inspect or refresh:

# What's in the bridge right now?
mcp tool call memory_bridge_status --json

# Force a re-import from Claude Code's project memory
mcp tool call memory_import_claude --json -- '{"allProjects": true}'

# Cross-namespace search across claude-memories + auto-memory + patterns + tasks + feedback
mcp tool call memory_search_unified --json -- '{"query": "your query"}'

memory_search_unified defaults to searching ['default', 'claude-memories', 'auto-memory', 'patterns', 'tasks', 'feedback'] — these are the namespaces the bridge actually populates. The default namespace is the catch-all; auto-memory is distinct from claude-memories (auto-memory holds bridge-internal cache, claude-memories holds parsed *.md sections).

Pluralization gotcha: the ReasoningBank fallback writes to pattern (singular). Other hooks (hooks pretrain, neural training paths) write to patterns (plural). They are different namespaces. When in doubt, memory_list --namespace pattern and memory_list --namespace patterns will tell you which one your data is in. Don't refactor your downstream code to "fix" the pluralization until you've confirmed which namespace was actually written.

Hook integration convention

Several Claude Code hooks fire writes into AgentDB. Consumer plugins should know which namespaces accumulate state automatically vs. by explicit call, so they don't rebuild what the hook system already provides.

Implication for consumer plugins:

• Don't double-write. If you're already calling hooks post-task --train-neural, you don't also need to manually memory_store --namespace pattern. Pick one path.
• Don't refresh claude-memories yourself. It auto-imports on every SessionStart. Manual memory_import_claude is for force-refresh, not steady-state.
• Surface fallback responses. When controller: 'memory-store-fallback' comes back from agentdb_pattern-store, the data still landed — see "Pattern-store fallback" below.

Operational fallbacks

Three fallbacks exist in the bridge code; consumers should branch on them rather than treat them as soft failures.

Pattern-store fallback (ADR-093 F4)

When the ReasoningBank controller registry returns null, agentdb_pattern-store writes through to memory_store and returns:

{
  "success": true,
  "patternId": "pattern-...",
  "controller": "memory-store-fallback",
  "note": "ReasoningBank controller registry unavailable. Pattern persisted via memory_store."
}

A controller: 'memory-store-fallback' response is a pattern that was persisted — not an error. Source: agentdb-tools.ts:138-161.

Causal-edge graph-node backend (ADR-087)

agentdb_causal-edge tries the native @ruvector/graph-node backend first; on failure, falls back to the bridge. The response includes _graphNodeBackend: true when the native backend handled the call. Source: agentdb-tools.ts:267-290.

Bridge unavailable

When bridgeHealthCheck() returns null (the @claude-flow/memory package is not installed or controller-registry.ts is missing), every agentdb_* handler returns:

{
  "success": false,
  "error": "AgentDB bridge not available — @claude-flow/memory not installed... Use memory_store/memory_search tools instead."
}

Replacement table for bridge-unavailable mode:

Verification

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

The smoke script is the contract. It calls each documented MCP tool, exercises the RaBitQ workflow, and source-inspects the fallback path (no env-var gate exists to force the fallback live).

Architecture Decisions

• ADR-0001 — Optimize ruflo-agentdb (accurate surface, RaBitQ, namespacing, smoke contract)

Related Plugins

• ruflo-rag-memory — simple store/search/recall interface; consumes the claude-memories reserved namespace
• ruflo-intelligence — SONA neural patterns; consumes the pattern reserved namespace via ReasoningBank
• ruflo-browser — composes the namespace convention for browser-sessions/-selectors/-templates/-cookies (ADR-0001 §3 there)
• ruflo-ruvector — pinned ruvector CLI; sibling substrate plugin

License

MIT