ADR-053: AgentDB v3 Controller Activation & Runtime Wiring

Status: Implemented Date: 2026-02-25 Updated: 2026-02-25 Authors: RuvNet, Claude Flow Team Version: 1.3.0 Published: v3.1.0-alpha.51 Related: ADR-006 (Unified Memory), ADR-049 (Self-Learning Memory GNN), ADR-050 (Intelligence Loop), ADR-009 (Hybrid Memory Backend), ADR-060 (Proof-Gated Mutations)

Context

Between issues #1207 and #1227, a systemic pattern has emerged: AgentDB v3 ships a rich controller ecosystem — 28 controllers (as of 3.0.0-alpha.7) covering self-learning, causal reasoning, episodic replay, explainable recall, proof-gated mutations, graph intelligence, skill promotion, and multi-armed bandit optimization — but the CLI runtime (@claude-flow/cli) instantiates none of them. The result is that powerful capabilities are available as dead exports while the runtime falls back to generic memory operations via memory-initializer.js.

AgentDB v3 Package Status (alpha.7)

• 42 named exports from main entry (28 exports in controllers barrel)
• 21 controllers activated internally in AgentDB.ts (lines 114-152), 28 total exports (21 controllers + 7 security/services)
• 4 hard deps (sql.js, ajv, zod, @modelcontextprotocol/sdk), zero native compilation
• 3.5 MB unpacked, 0 npm audit vulnerabilities
• CJS + ESM both fully working (dual exports, dynamic import for CJS)
• sql.js fallback: Main entry works without better-sqlite3 (import crash from alpha.6 fixed)
• @claude-flow/memory upgraded from [email protected] to agentdb@^3.0.0-alpha.7

AgentDB v3 Internal Capabilities (alpha.7)

The following capabilities are fully wired inside AgentDB and available to consumers via the AgentDB class:

1. Proof-Gated Mutations (ADR-060)

• MutationGuard validates all inserts, searches, batch inserts, removes, saves, and loads
• 4-tier proof engine fallback: @ruvector/graph-transformer (native NAPI-RS) → ruvector-graph-transformer-wasm → @ruvnet/ruvector-verified-wasm (legacy) → pure JS validation
• 82-byte cryptographic attestations with proveDimension() + createAttestation() when native available
• AttestationLog: append-only SQLite audit table (mutation_attestations) with proof/denial tracking, pattern aggregation, and pruning
• Security: SHA-256 structural hashes, token-based auth with TTL, path traversal prevention, parameterized SQL queries

2. GraphTransformerService (8 verified modules)

• 3-tier acceleration: native NAPI-RS → WASM → JS fallback (all methods always return results)
• Proof operations: proveDimension(), createAttestation(), verifyAttestation()

3. GuardedVectorBackend

• Wraps RuVectorBackend (or HNSWLibBackend) with proof-gated access via MutationGuard
• createGuardedBackend('auto', config) factory auto-detects best available backend
• Backend detection: RuVector (native/WASM, with optional GNN/Graph) → HNSWLib → error
• Proofs prevent dimension mismatch errors at source (validated before reaching backend)
• Automatic fallback: if guarded backend fails, controllers work without vectorBackend (set to null)

4. Services Layer

5. AgentDB.ts Controller Wiring (lines 45-127)

• initialize(): Dynamic import of better-sqlite3 with db-fallback.js sql.js fallback
• Schema loading: schema.sql + frontier-schema.sql from dist/schemas/
• EmbeddingService: Xenova/all-MiniLM-L6-v2 (384-dim) auto-initialized
• GraphTransformerService: 8 modules auto-initialized
• createGuardedBackend('auto'): Proof-gated vector backend with MutationGuard + AttestationLog
• 8 controllers instantiated with optional vectorBackend: ReflexionMemory, SkillLibrary, ReasoningBank, CausalMemoryGraph, CausalRecall, LearningSystem, ExplainableRecall, NightlyLearner
• Optional GraphDatabaseAdapter for persistent graph storage
• getController(name) accessor with 14 named controller slots

Full Export Inventory (42 main + 28 barrel)

Main entry (agentdb) — 42 exports:

Controllers barrel (agentdb/controllers) — 28 exports: All controllers + security + vector math (no AgentDB class, no services, no optimizations)

AgentDB v3 Release History

Problem Scope

Additionally, the HybridBackend facade (#1212) does not proxy new v3 methods (recordFeedback, verifyWitnessChain, getWitnessChain), and the hook handler (#1211) ignores stdin on Claude Code 2.x, making all hooks non-functional.

Root Cause

The v2→v3 migration was a package-level upgrade without a corresponding CLI integration pass. Each controller was implemented and exported in isolation, but no orchestration layer connects them to the MCP tools, hook handlers, or daemon workers that the CLI exposes.

Decision

Implement a phased controller activation plan organized by dependency order, with a central ControllerRegistry that manages lifecycle (init, health check, shutdown) for all AgentDB v3 controllers.

Phase 1: Foundation (Critical Path)

Priority: P0 — Blocks all other phases

Phase 2: Core Intelligence (Self-Learning Loop)

Priority: P1 — Enables the RETRIEVE→JUDGE→DISTILL→CONSOLIDATE pipeline

Phase 3: Advanced Memory (Graph & Episodic)

Priority: P2 — Rich memory features

Phase 4: Specialization (Skill & Scope)

Priority: P3 — Advanced agent capabilities

Phase 5: Proof-Gated Intelligence (since alpha.5, activated in alpha.7)

Priority: P3 — Cryptographic integrity & graph intelligence

All 6 controllers below are already activated inside AgentDB.ts (lines 102-152). The CLI work is exposing them through the ControllerRegistry and wiring them into hooks/MCP.

Phase 6: MCP Surface (Agent-Facing)

Priority: P3 — Explicit agent access

Architecture

ControllerRegistry

A central registry (replacing the current memory-initializer.js) that wraps the AgentDB class and adds CLI-specific controllers from @claude-flow/memory:

interface ControllerRegistry {
  // Lifecycle
  initialize(config: RuntimeConfig): Promise<void>;
  shutdown(): Promise<void>;
  healthCheck(): Promise<HealthReport>;

  // Controller access
  get<T>(name: ControllerName): T | null;
  isEnabled(name: ControllerName): boolean;

  // AgentDB instance (manages 14 internal controllers)
  agentdb: AgentDB;

  // CLI-layer controllers (from @claude-flow/memory, not in AgentDB)
  controllers: Map<ControllerName, ControllerInstance>;
}

// Controllers accessible via AgentDB.getController()
type AgentDBControllerName =
  | 'reasoningBank' | 'skills' | 'reflexion'
  | 'causalGraph' | 'causalRecall'
  | 'learningSystem' | 'explainableRecall' | 'nightlyLearner'
  | 'graphTransformer' | 'mutationGuard' | 'attestationLog'
  | 'vectorBackend' | 'graphAdapter';

// CLI-layer controllers (from @claude-flow/memory or new)
type CLIControllerName =
  | 'learningBridge' | 'memoryGraph' | 'agentMemoryScope'
  | 'tieredCache' | 'hybridSearch' | 'federatedSession'
  | 'semanticRouter' | 'sonaTrajectory';

type ControllerName = AgentDBControllerName | CLIControllerName;

Initialization Order

Controllers have dependencies that dictate initialization order:

Level 0: HybridBackend (already exists)
Level 1: ReasoningBank, LearningBridge, HybridSearch, TieredCache
Level 2: MemoryGraph, AgentMemoryScope, GuardedVectorBackend, MutationGuard
Level 3: SkillLibrary, ExplainableRecall, ReflexionMemory, AttestationLog
Level 4: CausalMemoryGraph, NightlyLearner, LearningSystem, SemanticRouter
Level 5: GraphTransformerService, SonaTrajectoryService (depend on graph + trajectories)
Level 6: FederatedSessionManager (depends on session lifecycle)

Graceful Degradation

Each controller activation is wrapped in try/catch with fallback to the current behavior:

try {
  const reasoningBank = new ReasoningBank(db, config);
  registry.register('reasoningBank', reasoningBank);
} catch (err) {
  logger.warn(`ReasoningBank unavailable: ${err.message}, using generic memory`);
}

This ensures that a failure in any single controller doesn't break the entire memory subsystem.

Config-Driven Activation

Each controller respects its config.json flags:

{
  "memory": {
    "enableHNSW": true,
    "learningBridge": { "sonaMode": true, "confidenceDecayRate": 0.01 },
    "memoryGraph": { "pageRankDamping": 0.85, "maxNodes": 10000 }
  },
  "neural": { "enabled": true, "modelPath": "./data/models" }
}

Controllers are only instantiated when their config section is present and enabled.

Consequences

Positive

• 42 exports activated: Unlocks the full AgentDB v3 capability surface (14 internal + CLI-layer controllers).
• Proof-gated integrity: All memory mutations require cryptographic proofs via MutationGuard (4-tier fallback).
• Tamper-evident audit: AttestationLog provides append-only SQLite audit trail with denial pattern aggregation.
• Graph intelligence: 8 verified GraphTransformerService modules for structural reasoning with JS fallbacks.
• Self-learning loop: RETRIEVE→JUDGE→DISTILL→CONSOLIDATE pipeline becomes functional.
• Improved search quality: BM25 hybrid search replaces naive string matching.
• Explainability: Merkle provenance on search results.
• Adaptive routing: Thompson Sampling + SemanticRouter + gameTheoreticAttention for multi-agent decisions.
• Trajectory learning: SonaTrajectoryService replaces LocalSonaCoordinator with RL-backed prediction.
• Memory isolation: 3-scope isolation prevents agent state leaks.
• Graceful degradation: Each controller and backend fails independently (vector → SQL, native → WASM → JS).

Negative

• Increased init time: More controllers to instantiate (mitigated by lazy init).
• Memory footprint: Each controller maintains internal state (mitigated by TieredCacheManager).
• Testing surface: 20+ controllers need integration tests.
• Upgrade complexity: Future AgentDB versions may change controller APIs.

Risks

• Circular dependencies: Controllers that depend on each other (e.g., SkillLibrary needs ReasoningBank scores). Mitigated by the Level-based initialization order.
• Config explosion: Too many knobs for users. Mitigated by sensible defaults and the init --wizard flow.
• AgentDB version churn: 5 releases (alpha.3–alpha.7) were needed to reach a stable baseline. Future alphas may introduce breaking changes. Mitigated by pinning ^3.0.0-alpha.7 with verified test suite.
• False positive security alerts: Windows Defender flags SKILL.md files as trojans (#1229). Mitigated by documenting known false positives and providing exclusion guidance.

UX Concern: Onboarding Complexity (Issue #1196)

This ADR acknowledges issue #1196 (beginner confusion from the paradox of choice). While the controller activation is internal plumbing, the UX problem is real. We recommend:

1. Beginner's Guide: Create a "Getting Started in 5 Minutes" doc.
2. Auto-start dependencies: ruflo / claude-flow should auto-start MCP when needed.
3. Simplified CLI entry point: A single npx ruflo start "build me a todo app" command that handles everything.
4. Progressive disclosure: Hide advanced options behind --advanced flags.

This is tracked separately but noted here as the most valuable community feedback received.

Validation

Each phase gate requires:

1. Unit tests: Each controller has isolated tests.
2. Integration test: Controller initializes from config.json and processes a request.
3. Graceful degradation test: Controller failure doesn't crash the system.
4. E2E test: Full pipeline test (hook trigger → controller → memory write → search retrieval).
5. Performance gate: No regression beyond 10% in CLI startup time.

Prerequisite: Eliminate Dual Memory System

The most critical integration gap is that the CLI (memory-initializer.js, 1929 lines) runs a self-contained SQLite memory system that duplicates what @claude-flow/memory + AgentDB already provides. Before wiring controllers, the CLI must be refactored to use @claude-flow/memory's HybridBackend as its storage layer instead of raw sql.js calls.

This consolidation eliminates ~1000 lines of duplicated SQLite/HNSW/embedding code from memory-initializer.js and routes all memory operations through the controller pipeline.

Import Strategy

Option A: Use AgentDB class (recommended for full integration)

The AgentDB class is the primary integration surface. It handles all initialization, fallback chains, schema loading, and controller wiring internally. The CLI's ControllerRegistry should wrap this class:

import { AgentDB } from 'agentdb';

const db = new AgentDB({ dbPath: './data/memory.db', dimension: 384 });
await db.initialize();

// Access controllers via getController()
const reasoning = db.getController('reasoningBank');  // ReasoningBank
const skills    = db.getController('skills');          // SkillLibrary
const reflexion = db.getController('reflexion');       // ReflexionMemory
const causal    = db.getController('causalGraph');     // CausalMemoryGraph
const learning  = db.getController('learningSystem');  // LearningSystem
const explain   = db.getController('explainableRecall');
const nightly   = db.getController('nightlyLearner');
const graph     = db.getController('graphTransformer');// GraphTransformerService
const guard     = db.getController('mutationGuard');   // MutationGuard (or null)
const log       = db.getController('attestationLog');  // AttestationLog (or null)
const vector    = db.getController('vectorBackend');   // GuardedVectorBackend (or null)

await db.close();

Option B: Individual controller imports (for selective use)

// Controllers-only (lighter, no AgentDB class, no auto-init)
import { ReasoningBank, SkillLibrary } from 'agentdb/controllers';

// Services (not in controllers barrel — must use main entry)
import { SemanticRouter, SonaTrajectoryService, LLMRouter } from 'agentdb';

Database Fallback Chain

AgentDB.initialize()
  → try: import('better-sqlite3')       // Native, fastest
  → catch: import('./db-fallback.js')    // sql.js WASM, zero-native

Vector Backend Fallback Chain

createGuardedBackend('auto', config)
  → detectBackends()
    → try: import('ruvector')                  // Native + GNN + Graph
    → try: import('@ruvector/core')            // Scoped native
    → try: import('hnswlib-node')              // Node.js HNSW
    → throw: 'No vector backend available'
  → wrap with MutationGuard + AttestationLog
  → return GuardedVectorBackend

If the entire guarded backend creation fails, AgentDB.ts catches the error and sets vectorBackend = null. All 8 controllers still work without vector search — they degrade to SQL-only queries.

Proof Engine Fallback Chain (MutationGuard)

MutationGuard.initialize()
  → try: import('@ruvector/graph-transformer')      // Native NAPI-RS (sub-ms proofs)
  → try: import('ruvector-graph-transformer-wasm')   // Browser WASM
  → try: import('@ruvnet/ruvector-verified-wasm')    // Legacy WASM
  → fallback: pure JS validation (no attestations, but validates dimensions/inputs)

Not Yet Exported (Internal/MCP)

The following modules exist in AgentDB but are not exported from the main entry or controllers barrel. They may be relevant for Phase 6 (MCP Surface):

Implementation Status (v3.1.0-alpha.51)

Completed: Foundation Bridge (Phase 1 Core)

The bridge pattern was implemented as memory-bridge.ts (858 lines) in @claude-flow/cli, routing CLI operations through ControllerRegistry → HybridBackend → AgentDB v3. This eliminates the dual memory system described in the "Prerequisite" section.

Files delivered:

Verified capabilities (13 integration tests passing):

Regression check: 0 new failures. CLI: 445 passed (39 pre-existing failures). Memory: 352 passed (1 flaky benchmark).

Remaining Phases (Not Yet Implemented)

Issue Status

All 13 controllers are instantiated via AgentDB v3, registered in the ControllerRegistry, and accessible through the bridge. Embeddings are generated on every store operation. Semantic search uses cosine similarity over stored embeddings.

Separate Issues (Not Part of ADR-053 Scope)

These are independent issues tracked separately:

Future Enhancement: Deep Controller Consumption (Phases 2-6)

Phases 2-6 describe deeper integration where specific CLI commands and hooks call controller-specific methods (e.g., post-task → reasoningBank.recordFeedback(), route → semanticRouter.route()). These are enhancements beyond the original "not instantiated" issues and are tracked as future work.

References

• Issues: #1196, #1204, #1206, #1207-#1230
• Tracking issue: #1228
• ADR-060: Proof-Gated State Mutation (agentdb internal)
• Contributor: @sparkling (claude-flow-patch repository)
• Contributor: @HF-teamdev (hook-handler stdin fix)
• Contributor: @ffMathy (UX/onboarding feedback)
• Contributor: @ThyannSeng (Windows Defender false positive report, #1229)
• Contributor: @bendelonlee (init hook config issue, #1230)
• AgentDB v3: [email protected] (4 deps, 3.5MB, 0 CVEs, CJS+ESM, sql.js fallback)
• @claude-flow/memory: upgraded to agentdb@^3.0.0-alpha.7
• AgentDB source files reviewed: AgentDB.js, MutationGuard.js, AttestationLog.js, GuardedVectorBackend.js, factory.js, GraphTransformerService.js, SemanticRouter.js, SonaTrajectoryService.js, LLMRouter.js, index.js, controllers/index.js