@claude-flow/memory 3.0.0-alpha.9 → 3.0.1

package/dist/controller-registry.d.ts

@@ -0,0 +1,290 @@
+/**
+ * ControllerRegistry - Central controller lifecycle management for AgentDB v3
+ *
+ * Wraps the AgentDB class and adds CLI-specific controllers from @claude-flow/memory.
+ * Manages initialization (level-based ordering), health checks, and graceful shutdown.
+ *
+ * Per ADR-053: Replaces memory-initializer.js's raw sql.js usage with a unified
+ * controller ecosystem routing all memory operations through AgentDB v3.
+ *
+ * @module @claude-flow/memory/controller-registry
+ */
+import { EventEmitter } from 'node:events';
+import type { IMemoryBackend, EmbeddingGenerator, SONAMode } from './types.js';
+import type { LearningBridgeConfig } from './learning-bridge.js';
+import type { MemoryGraphConfig } from './memory-graph.js';
+import type { CacheConfig } from './types.js';
+/**
+ * Controllers accessible via AgentDB.getController()
+ */
+export type AgentDBControllerName = 'reasoningBank' | 'skills' | 'reflexion' | 'causalGraph' | 'causalRecall' | 'learningSystem' | 'explainableRecall' | 'nightlyLearner' | 'graphTransformer' | 'mutationGuard' | 'attestationLog' | 'vectorBackend' | 'graphAdapter';
+/**
+ * CLI-layer controllers (from @claude-flow/memory or new)
+ */
+export type CLIControllerName = 'learningBridge' | 'memoryGraph' | 'agentMemoryScope' | 'tieredCache' | 'hybridSearch' | 'federatedSession' | 'semanticRouter' | 'sonaTrajectory' | 'hierarchicalMemory' | 'memoryConsolidation' | 'batchOperations' | 'contextSynthesizer' | 'gnnService' | 'rvfOptimizer' | 'mmrDiversityRanker' | 'guardedVectorBackend';
+/**
+ * All controller names
+ */
+export type ControllerName = AgentDBControllerName | CLIControllerName;
+/**
+ * Initialization level for dependency ordering
+ */
+export interface InitLevel {
+    level: number;
+    controllers: ControllerName[];
+}
+/**
+ * Individual controller health status
+ */
+export interface ControllerHealth {
+    name: ControllerName;
+    status: 'healthy' | 'degraded' | 'unavailable';
+    initTimeMs: number;
+    error?: string;
+}
+/**
+ * Aggregated health report for all controllers
+ */
+export interface RegistryHealthReport {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    controllers: ControllerHealth[];
+    agentdbAvailable: boolean;
+    initTimeMs: number;
+    timestamp: number;
+    activeControllers: number;
+    totalControllers: number;
+}
+/**
+ * Runtime configuration for controller activation
+ */
+export interface RuntimeConfig {
+    /** Database path for AgentDB */
+    dbPath?: string;
+    /** Vector dimension (default: 384 for MiniLM) */
+    dimension?: number;
+    /** Embedding generator function */
+    embeddingGenerator?: EmbeddingGenerator;
+    /** Memory backend config */
+    memory?: {
+        enableHNSW?: boolean;
+        learningBridge?: Partial<LearningBridgeConfig>;
+        memoryGraph?: Partial<MemoryGraphConfig>;
+        tieredCache?: Partial<CacheConfig>;
+    };
+    /** Neural config */
+    neural?: {
+        enabled?: boolean;
+        modelPath?: string;
+        sonaMode?: SONAMode;
+    };
+    /** Controllers to explicitly enable/disable */
+    controllers?: Partial<Record<ControllerName, boolean>>;
+    /** Backend instance to use (if pre-created) */
+    backend?: IMemoryBackend;
+    /**
+     * Pre-initialized AgentDB instance to use. When provided, the
+     * registry skips its own dynamic-import / initialize cycle and uses
+     * this instance as-is — useful for testing, multi-registry sharing,
+     * and consumers that already hold an AgentDB they want governed by
+     * the registry. Issue #2019 added the regression tests that depend
+     * on this injection point.
+     */
+    agentdb?: unknown;
+    /**
+     * `MemoryService` (or compatible) used to back the `nightlyLearner`
+     * controller. When provided, ADR-125 Phase 4 wraps it with
+     * `MemoryConsolidator.runAll()` instead of delegating directly to AgentDB's
+     * `NightlyLearner`. Accepts `any` to avoid a circular import.
+     */
+    memoryService?: any;
+}
+/**
+ * Level-based initialization order per ADR-053.
+ * Controllers at each level can be initialized in parallel.
+ * Each level must complete before the next begins.
+ */
+export declare const INIT_LEVELS: InitLevel[];
+/**
+ * Central registry for AgentDB v3 controller lifecycle management.
+ *
+ * Handles:
+ * - Level-based initialization ordering (levels 0-6)
+ * - Graceful degradation (each controller fails independently)
+ * - Config-driven activation (controllers only instantiate when enabled)
+ * - Health check aggregation across all controllers
+ * - Ordered shutdown (reverse initialization order)
+ *
+ * @example
+ * ```typescript
+ * const registry = new ControllerRegistry();
+ * await registry.initialize({
+ *   dbPath: './data/memory.db',
+ *   dimension: 384,
+ *   memory: {
+ *     enableHNSW: true,
+ *     learningBridge: { sonaMode: 'balanced' },
+ *     memoryGraph: { pageRankDamping: 0.85 },
+ *   },
+ * });
+ *
+ * const reasoning = registry.get<ReasoningBank>('reasoningBank');
+ * const graph = registry.get<MemoryGraph>('memoryGraph');
+ *
+ * await registry.shutdown();
+ * ```
+ */
+export declare class ControllerRegistry extends EventEmitter {
+    private controllers;
+    private agentdb;
+    private backend;
+    private config;
+    private initialized;
+    private initTimeMs;
+    private hierarchicalFallback;
+    /**
+     * Initialize all controllers in level-based order.
+     *
+     * Each level's controllers are initialized in parallel within the level.
+     * Failures are isolated: a controller that fails to init is marked as
+     * unavailable but does not block other controllers.
+     */
+    initialize(config?: RuntimeConfig): Promise<void>;
+    /**
+     * Shutdown all controllers in reverse initialization order.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get a controller instance by name.
+     * Returns null if the controller is not initialized or unavailable.
+     */
+    get<T>(name: ControllerName): T | null;
+    /**
+     * Check if a controller is enabled and initialized.
+     */
+    isEnabled(name: ControllerName): boolean;
+    /**
+     * Aggregate health check across all controllers.
+     */
+    healthCheck(): Promise<RegistryHealthReport>;
+    /**
+     * Get the underlying AgentDB instance.
+     */
+    getAgentDB(): any;
+    /**
+     * Get the memory backend.
+     */
+    getBackend(): IMemoryBackend | null;
+    /**
+     * Check if the registry is initialized.
+     */
+    isInitialized(): boolean;
+    /**
+     * Get the number of active (successfully initialized) controllers.
+     */
+    getActiveCount(): number;
+    /**
+     * List all registered controller names and their status.
+     */
+    listControllers(): Array<{
+        name: ControllerName;
+        enabled: boolean;
+        level: number;
+    }>;
+    /**
+     * Initialize AgentDB instance with dynamic import and fallback chain.
+     */
+    private initAgentDB;
+    /**
+     * Check whether a controller should be initialized based on config.
+     */
+    private isControllerEnabled;
+    /**
+     * Close any prior controller instance for `name` before it is replaced.
+     *
+     * #2432 fix — pre-fix, `controllers.set(name, ...)` silently orphaned the
+     * prior instance. For backends that allocate native / WASM resources
+     * (notably `SqlJsRvfBackend` which keeps an Emscripten MEMFS file ~11 MB
+     * per `new SQL.Database(buffer)` until `close()` runs), GC'ing the JS
+     * wrapper does NOT reclaim the underlying allocation. A long-running
+     * `mcp start` process that re-init'd controllers hundreds of times grew
+     * external memory by ~36 GB in production over 6 weeks.
+     *
+     * Best-effort close: catch and ignore errors — replacement must proceed
+     * even if the prior instance's close throws (it's already orphaned at
+     * this point either way).
+     */
+    private closePriorIfAny;
+    /**
+     * Initialize a single controller with error isolation.
+     */
+    private initController;
+    /**
+     * Factory method to create a controller instance.
+     * Handles CLI-layer controllers; AgentDB-internal controllers are
+     * accessed via agentdb.getController().
+     */
+    private createController;
+    /**
+     * Shutdown a single controller gracefully.
+     */
+    private shutdownController;
+    /**
+     * Create an EmbeddingService for controllers that need it.
+     * Uses the config's embedding generator or creates a minimal local service.
+     */
+    /**
+     * Adapt an arbitrary embedder to the contract agentdb's controllers call
+     * (#3327).
+     *
+     * ReasoningBank uses asymmetric query/passage embedding — `embedQuery()` on
+     * search, `embedPassage()` on store. Several embedders reaching here expose
+     * only `embed()`:
+     *   • agentdb's mock embedder, substituted whenever the Transformers.js
+     *     model fails to load (offline, or a failed `sharp` optional install);
+     *   • any host-supplied `embeddingGenerator` wrapper.
+     *
+     * Passing one of those through unchanged throws `... is not a function`
+     * deep inside the controller, where the bridge's catch converts it into a
+     * silent fallback — the failure this whole fix is about. Aliasing is
+     * semantically safe: a symmetric model returns the same vector for both
+     * roles, which is precisely what a single `embed()` implies.
+     *
+     * Returns null when there is nothing usable to adapt.
+     */
+    private adaptEmbedderForAgentdb;
+    private createEmbeddingService;
+    /**
+     * Tiered store used when agentdb's HierarchicalMemory is unavailable.
+     *
+     * Since agentdb 3.0.0-alpha.17 dropped the `HierarchicalMemory` export
+     * entirely, this is the ONLY backing store for `agentdb_hierarchical-*`
+     * in practice — so it is handed AgentDB's SQLite connection and writes
+     * through to it. Without a connection it stays volatile and reports
+     * `isDurable() === false` so callers can refuse to claim success (#2887).
+     *
+     * Keeps the legacy duck-typed API — store(key, value, tier) /
+     * recall(query, topK) / getTierStats() — plus Zep/Graphiti-style temporal
+     * validity (validFrom / validUntil / supersededBy).
+     */
+    private createTieredMemoryStub;
+    /** Build the tiered fallback and record/emit why the native one was skipped. */
+    private tieredMemoryFallback;
+    /**
+     * Why `hierarchicalMemory` is served by the tiered fallback, and whether
+     * that fallback is durable. Null when the native controller is in use.
+     */
+    getHierarchicalFallback(): {
+        reason: string;
+        persistence: string;
+    } | null;
+    /**
+     * No-op consolidation stub — the first-class implementation for
+     * `memoryConsolidation` since agentdb has never shipped a working native
+     * MemoryConsolidation on any installable range (#2977). `promoted: 0,
+     * pruned: 0` on its own reads as "ran and found nothing to do"; `source`
+     * and `note` make it explicit that consolidation never actually ran.
+     */
+    private createConsolidationStub;
+}
+export default ControllerRegistry;
+//# sourceMappingURL=controller-registry.d.ts.map

package/dist/controller-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-registry.d.ts","sourceRoot":"","sources":["../src/controller-registry.ts"],"names":[],"mappings":"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"}