@monoes/memory 1.0.0

package/dist/checkpointer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SwarmCheckpointer — JSON-lines file-based graph checkpointing.
+ *
+ * Each checkpoint is appended as a single JSON line to a file,
+ * similar to the CostTracker pattern used elsewhere in the project.
+ * No native SQLite dependency required.
+ */
+import type { AgentState, SwarmCheckpoint, CheckpointMeta } from './types/checkpoint.js';
+export type { AgentState, SwarmCheckpoint, CheckpointMeta };
+/** Configuration accepted by the checkpointer constructor. */
+export interface CheckpointerConfig {
+    dbPath: string;
+    swarmId: string;
+    sessionId: string;
+}
+/**
+ * Persists and retrieves full swarm checkpoints using a JSON-lines file.
+ *
+ * Each line in the file is a self-contained JSON object representing one
+ * {@link SwarmCheckpoint}. Newest entries are always appended at the end.
+ */
+export declare class SwarmCheckpointer {
+    private stepCounter;
+    private readonly dbPath;
+    private readonly swarmId;
+    private readonly sessionId;
+    constructor(config: CheckpointerConfig);
+    /** Read all checkpoints from the file (oldest-first). */
+    private readAll;
+    /** Overwrite the file with the given checkpoints. */
+    private writeAll;
+    /** Compute a deterministic SHA-256 hash of the serialisable state. */
+    private computeHash;
+    /**
+     * Save a full checkpoint of the entire swarm.
+     *
+     * @returns The generated `checkpointId`.
+     */
+    saveFull(agentStates: AgentState[], messageQueues: Record<string, unknown[]>, taskResults: Record<string, unknown>, trigger: SwarmCheckpoint['trigger'], parentCheckpointId?: string): string;
+    /**
+     * Save an incremental checkpoint that patches one agent's state.
+     *
+     * Loads the latest checkpoint, replaces (or appends) the given agent's
+     * state, and writes a new checkpoint line.
+     */
+    saveIncremental(agentId: string, newState: AgentState): void;
+    /**
+     * Load a checkpoint by its ID.
+     *
+     * @returns The checkpoint, or `null` if not found.
+     */
+    load(checkpointId: string): SwarmCheckpoint | null;
+    /**
+     * List checkpoint metadata, newest-first.
+     *
+     * @param limit Maximum number of entries to return (default 20).
+     */
+    list(limit?: number): CheckpointMeta[];
+    /**
+     * Return the most recent checkpoint, or `null` if none exist.
+     */
+    latest(): SwarmCheckpoint | null;
+    /**
+     * Compute the difference between two checkpoints in terms of agents.
+     */
+    diff(fromId: string, toId: string): {
+        addedAgents: string[];
+        removedAgents: string[];
+        changedAgents: string[];
+    };
+    /**
+     * Purge checkpoints older than the given number of days.
+     *
+     * @returns The number of checkpoints removed.
+     */
+    purge(olderThanDays?: number): number;
+}
+//# sourceMappingURL=checkpointer.d.ts.map

package/dist/checkpointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointer.d.ts","sourceRoot":"","sources":["../src/checkpointer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEzF,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC;AAE5D,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,kBAAkB;IAUtC,yDAAyD;IACzD,OAAO,CAAC,OAAO;IAUf,qDAAqD;IACrD,OAAO,CAAC,QAAQ;IAKhB,sEAAsE;IACtE,OAAO,CAAC,WAAW;IAanB;;;;OAIG;IACH,QAAQ,CACN,WAAW,EAAE,UAAU,EAAE,EACzB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EACxC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,EACnC,kBAAkB,CAAC,EAAE,MAAM,GAC1B,MAAM;IAsBT;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,GAAG,IAAI;IAgB5D;;;;OAIG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAKlD;;;;OAIG;IACH,IAAI,CAAC,KAAK,SAAK,GAAG,cAAc,EAAE;IAiBlC;;OAEG;IACH,MAAM,IAAI,eAAe,GAAG,IAAI;IAMhC;;OAEG;IACH,IAAI,CACF,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX;QAAE,WAAW,EAAE,MAAM,EAAE,CAAC;QAAC,aAAa,EAAE,MAAM,EAAE,CAAC;QAAC,aAAa,EAAE,MAAM,EAAE,CAAA;KAAE;IAwB9E;;;;OAIG;IACH,KAAK,CAAC,aAAa,SAAI,GAAG,MAAM;CAQjC"}

package/dist/checkpointer.js

@@ -0,0 +1,174 @@
+/**
+ * SwarmCheckpointer — JSON-lines file-based graph checkpointing.
+ *
+ * Each checkpoint is appended as a single JSON line to a file,
+ * similar to the CostTracker pattern used elsewhere in the project.
+ * No native SQLite dependency required.
+ */
+import { randomUUID, createHash } from 'node:crypto';
+import { existsSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
+/**
+ * Persists and retrieves full swarm checkpoints using a JSON-lines file.
+ *
+ * Each line in the file is a self-contained JSON object representing one
+ * {@link SwarmCheckpoint}. Newest entries are always appended at the end.
+ */
+export class SwarmCheckpointer {
+    stepCounter = 0;
+    dbPath;
+    swarmId;
+    sessionId;
+    constructor(config) {
+        this.dbPath = config.dbPath;
+        this.swarmId = config.swarmId;
+        this.sessionId = config.sessionId;
+    }
+    // ---------------------------------------------------------------------------
+    // Persistence helpers
+    // ---------------------------------------------------------------------------
+    /** Read all checkpoints from the file (oldest-first). */
+    readAll() {
+        if (!existsSync(this.dbPath))
+            return [];
+        const raw = readFileSync(this.dbPath, 'utf-8').trim();
+        if (!raw)
+            return [];
+        return raw
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    /** Overwrite the file with the given checkpoints. */
+    writeAll(checkpoints) {
+        const data = checkpoints.map((c) => JSON.stringify(c)).join('\n') + (checkpoints.length ? '\n' : '');
+        writeFileSync(this.dbPath, data, 'utf-8');
+    }
+    /** Compute a deterministic SHA-256 hash of the serialisable state. */
+    computeHash(agentStates, messageQueues, taskResults) {
+        const payload = JSON.stringify({ agentStates, messageQueues, taskResults });
+        return createHash('sha256').update(payload).digest('hex');
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Save a full checkpoint of the entire swarm.
+     *
+     * @returns The generated `checkpointId`.
+     */
+    saveFull(agentStates, messageQueues, taskResults, trigger, parentCheckpointId) {
+        const checkpointId = randomUUID();
+        this.stepCounter += 1;
+        const checkpoint = {
+            checkpointId,
+            swarmId: this.swarmId,
+            sessionId: this.sessionId,
+            step: this.stepCounter,
+            trigger,
+            agentStates,
+            messageQueues,
+            taskResults,
+            stateHash: this.computeHash(agentStates, messageQueues, taskResults),
+            createdAt: new Date().toISOString(),
+            parentCheckpointId,
+        };
+        appendFileSync(this.dbPath, JSON.stringify(checkpoint) + '\n', 'utf-8');
+        return checkpointId;
+    }
+    /**
+     * Save an incremental checkpoint that patches one agent's state.
+     *
+     * Loads the latest checkpoint, replaces (or appends) the given agent's
+     * state, and writes a new checkpoint line.
+     */
+    saveIncremental(agentId, newState) {
+        const prev = this.latest();
+        const agentStates = prev ? [...prev.agentStates] : [];
+        const idx = agentStates.findIndex((a) => a.agentId === agentId);
+        if (idx >= 0) {
+            agentStates[idx] = newState;
+        }
+        else {
+            agentStates.push(newState);
+        }
+        const messageQueues = prev?.messageQueues ?? {};
+        const taskResults = prev?.taskResults ?? {};
+        this.saveFull(agentStates, messageQueues, taskResults, 'manual', prev?.checkpointId);
+    }
+    /**
+     * Load a checkpoint by its ID.
+     *
+     * @returns The checkpoint, or `null` if not found.
+     */
+    load(checkpointId) {
+        const all = this.readAll();
+        return all.find((c) => c.checkpointId === checkpointId) ?? null;
+    }
+    /**
+     * List checkpoint metadata, newest-first.
+     *
+     * @param limit Maximum number of entries to return (default 20).
+     */
+    list(limit = 20) {
+        const all = this.readAll();
+        return all
+            .sort((a, b) => b.step - a.step)
+            .slice(0, limit)
+            .map((c) => ({
+            checkpointId: c.checkpointId,
+            swarmId: c.swarmId,
+            sessionId: c.sessionId,
+            step: c.step,
+            trigger: c.trigger,
+            agentCount: c.agentStates.length,
+            stateHash: c.stateHash,
+            createdAt: c.createdAt,
+        }));
+    }
+    /**
+     * Return the most recent checkpoint, or `null` if none exist.
+     */
+    latest() {
+        const all = this.readAll();
+        if (all.length === 0)
+            return null;
+        return all.reduce((best, c) => (c.step > best.step ? c : best), all[0]);
+    }
+    /**
+     * Compute the difference between two checkpoints in terms of agents.
+     */
+    diff(fromId, toId) {
+        const from = this.load(fromId);
+        const to = this.load(toId);
+        const fromIds = new Set((from?.agentStates ?? []).map((a) => a.agentId));
+        const toIds = new Set((to?.agentStates ?? []).map((a) => a.agentId));
+        const addedAgents = [...toIds].filter((id) => !fromIds.has(id));
+        const removedAgents = [...fromIds].filter((id) => !toIds.has(id));
+        const changedAgents = [];
+        if (from && to) {
+            for (const toAgent of to.agentStates) {
+                if (!fromIds.has(toAgent.agentId))
+                    continue; // added, not changed
+                const fromAgent = from.agentStates.find((a) => a.agentId === toAgent.agentId);
+                if (fromAgent && JSON.stringify(fromAgent) !== JSON.stringify(toAgent)) {
+                    changedAgents.push(toAgent.agentId);
+                }
+            }
+        }
+        return { addedAgents, removedAgents, changedAgents };
+    }
+    /**
+     * Purge checkpoints older than the given number of days.
+     *
+     * @returns The number of checkpoints removed.
+     */
+    purge(olderThanDays = 7) {
+        const all = this.readAll();
+        const cutoff = Date.now() - olderThanDays * 86_400_000;
+        const kept = all.filter((c) => new Date(c.createdAt).getTime() > cutoff);
+        const removed = all.length - kept.length;
+        this.writeAll(kept);
+        return removed;
+    }
+}
+//# sourceMappingURL=checkpointer.js.map

package/dist/checkpointer.js.map

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

package/dist/controller-registry.d.ts

@@ -0,0 +1,216 @@
+/**
+ * ControllerRegistry - Central controller lifecycle management for AgentDB v1
+ *
+ * Wraps the AgentDB class and adds CLI-specific controllers from @monomind/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 v1.
+ *
+ * @module @monomind/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 @monomind/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;
+}
+/**
+ * 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 v1 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    private createEmbeddingService;
+    /**
+     * Lightweight in-memory tiered store (fallback when HierarchicalMemory
+     * cannot be initialized from agentdb).
+     * Enforces per-tier size limits to prevent unbounded memory growth.
+     */
+    private createTieredMemoryStub;
+    /**
+     * No-op consolidation stub (fallback when MemoryConsolidation
+     * cannot be initialized from agentdb).
+     */
+    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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"}