ADR-053: AgentDB v3 Controller Activation & Runtime Wiring

[ruvnet]

Summary

ADR-053 addresses the systemic gap where AgentDB v3 exports 42 named exports (28 in controllers barrel) but the CLI runtime instantiates none of them. This ADR proposes a 6-phase activation plan with a ControllerRegistry wrapping the AgentDB class.

ADR Location: v3/implementation/adrs/ADR-053-agentdb-v3-controller-activation.md
Status: Accepted (v1.2.0)

AgentDB v3 Status (alpha.7)

Metric	Value
Main exports	42
Controllers barrel	28
Internal controllers (AgentDB.ts)	14 (8 core + 3 proof-gated + 2 services + graph adapter)
Hard deps	4 (sql.js, ajv, zod, MCP SDK)
Size	3.5 MB
CVEs	0
CJS + ESM	Both working (dynamic import)
sql.js fallback	Works without better-sqlite3
@claude-flow/memory	Upgraded to ^3.0.0-alpha.7

Key Capabilities in alpha.7

1. Proof-Gated Mutations — MutationGuard validates all inserts/searches, 4-tier fallback (native→wasm→legacy-wasm→js), 82-byte cryptographic attestations
2. GraphTransformerService — 8 verified modules (sublinearAttention, verifiedStep, causalAttention, grangerExtract, hamiltonianStep, spikingAttention, gameTheoreticAttention, productManifoldDistance), all with JS fallbacks
3. GuardedVectorBackend — Wraps RuVectorBackend with proof-gated access, automatic SQL fallback
4. AttestationLog — Append-only SQLite audit trail with denial pattern aggregation
5. SemanticRouter — Embedding-based query routing with keyword fallback
6. SonaTrajectoryService — RL-backed trajectory learning with frequency prediction fallback
7. LLMRouter — Multi-provider (OpenRouter/Gemini/Anthropic/ONNX) with auto-selection

Release History

Version	Key Change	Status
alpha.3	Initial v3	ESM-only, CJS broken
alpha.4	Native deps	Regression: 33.4MB
alpha.5	Zero-native, proof-gated	6 high CVEs
alpha.6	sqlite3→peerDeps	Import crash
alpha.7	Dynamic import, all controllers	All clear

Problem

CLI's memory-initializer.js (1929 lines) runs a self-contained SQLite system that duplicates what @claude-flow/memory + AgentDB provides. The CLI never imports @claude-flow/memory at runtime.

Phased Plan

Phase 1: Foundation (P0) — Blocks everything

• Eliminate dual memory system (CLI → AgentDB class → controllers)
• Fix hook-handler stdin reading (hook-handler.cjs ignores stdin: all hook data silently lost on Claude Code 2.x (prompt, tool_input, file_path always empty) #1211)
• Fix init hook config invalid keys (Setting Error on Init #1230)
• HybridBackend proxy for v3 methods (Bug: HybridBackend doesn't proxy recordFeedback/verifyWitnessChain to AgentDBBackend #1212)
• Wire dead config.json keys (Bug: 12 config.json keys written during init are never consumed at runtime #1204)
• Topology alignment to hierarchical-mesh (Bug: swarm init uses legacy 'hierarchical' default, --v3-mode flag contradicts init defaults #1202, Bug: init --start-all and CLAUDE.md templates use stale --topology hierarchical #1206)

Phase 2: Core Intelligence (P1)

• ReasoningBank activation (Bug: ReasoningBank not instantiated — pattern-store/search hooks use generic memory instead of ReasoningBank #1210)
• LearningBridge activation (Bug: LearningBridge from @claude-flow/memory has zero runtime callers #1213)
• SolverBandit Thompson Sampling (Wire SolverBandit Thompson Sampling into hooks_route agent selection #1217)
• BM25 HybridSearch (Wire BM25 hybrid search into memory_search handler #1219)
• recordFeedback callers (Bug: recordFeedback() exposed by AgentDB v3 has zero callers #1209)

Phase 3: Advanced Memory (P2)

• MemoryGraph activation (Bug: MemoryGraph class exported from @claude-flow/memory but never instantiated at runtime #1214)
• ReflexionMemory episodic replay (Wire ReflexionMemory episodic replay into session lifecycle #1221)
• CausalMemoryGraph experiments (Wire CausalMemoryGraph experiment framework into post-task hooks #1223)
• NightlyLearner daemon wiring (Wire NightlyLearner into daemon consolidation cycle #1218)
• WitnessChain callers (Bug: verifyWitnessChain() and getWitnessChain() have zero callers #1208)

Phase 4: Specialization (P3)

• SkillLibrary Voyager pattern (Bug: AgentDB v3 SkillLibrary controller not instantiated by CLI #1215)
• ExplainableRecall Merkle provenance (Bug: ExplainableRecall controller exported by AgentDB v3 but never instantiated #1216)
• LearningSystem 9-RL algorithms (Wire LearningSystem 9-RL algorithm selection into hooks_route #1224)
• FederatedSessionManager LoRA transfer (Wire FederatedSessionManager for cross-agent session aggregation #1222)
• AgentMemoryScope 3-scope isolation (Wire AgentMemoryScope 3-scope isolation into memory operations #1227)
• TieredCacheManager 5-tier compression (Wire 5-tier compression config into HybridBackend initialization #1220)

Phase 5: Proof-Gated Intelligence (P3) — Already activated in AgentDB.ts

• GuardedVectorBackend → wire into HybridBackend
• MutationGuard → route CLI mutations through guard
• AttestationLog → expose in session-start health checks
• GraphTransformerService → wire 8 modules into MemoryGraph
• SemanticRouter → replace hand-rolled hooks_route routing
• SonaTrajectoryService → replace LocalSonaCoordinator

Phase 6: MCP Surface (P3)

• Namespaced agentdb_* MCP tools (Expose AgentDB controllers as namespaced MCP tools #1226)
• COW branching MCP tool (Add COW branching MCP tool for memory snapshots #1225)
• Expose agentdb-mcp-server and attention/learning tool handlers

Related Issues

#1196 #1202 #1204 #1206 #1207 #1208 #1209 #1210 #1211 #1212 #1213 #1214 #1215 #1216 #1217 #1218 #1219 #1220 #1221 #1222 #1223 #1224 #1225 #1226 #1227 #1229 #1230

Contributors

• @sparkling — systematic gap analysis (20+ issues)
• @HF-teamdev — hook-handler stdin fix (hook-handler.cjs ignores stdin: all hook data silently lost on Claude Code 2.x (prompt, tool_input, file_path always empty) #1211)
• @ffMathy — UX/onboarding feedback (How do I use this? Paradox of choice and confusion as a beginner #1196)
• @ThyannSeng — Windows Defender false positive report (Window Defender: Trojan:JS/CrypoStealz.AE!MTB #1229)
• @bendelonlee — init hook config issue (Setting Error on Init #1230)