@monoes/monomindcli 1.15.5 → 1.15.7

package/dist/src/mcp-tools/memory-tools.js

@@ -1,548 +1,596 @@
 /**
- * Memory MCP Tools for CLI - V1 with sql.js/HNSW Backend
+ * Memory MCP Tools — Phase 6 of ADR-053
  *
- * UPGRADED: Now uses the advanced sql.js + HNSW backend for:
- * - 150x-12,500x faster semantic search
- * - Vector embeddings with cosine similarity
- * - Persistent SQLite storage (WASM)
- * - Backward compatible with legacy JSON storage (auto-migrates)
+ * Exposes Memory backend operations as MCP tools.
+ * Provides direct access to ReasoningBank, CausalGraph, SkillLibrary,
+ * AttestationLog, and bridge health through the MCP protocol.
+ *
+ * Security: All handlers validate input types, enforce length bounds,
+ * and sanitize error messages before returning to MCP callers.
  *
  * @module v1/cli/mcp-tools/memory-tools
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'fs';
-import { join } from 'path';
-import { getMonomindDataRoot } from './types.js';
-// Paths — relative to the git-safe data root
-const MEMORY_SUBDIR = 'memory';
-const LEGACY_MEMORY_FILE = 'store.json';
-const MIGRATION_MARKER = '.migrated-to-sqlite';
-function getMemoryDir() {
-    return join(getMonomindDataRoot(), MEMORY_SUBDIR);
+// ===== Shared validation helpers =====
+const MAX_STRING_LENGTH = 100_000; // 100KB max for any string input
+const MAX_BATCH_SIZE = 500; // Max entries per batch operation
+const MAX_TOP_K = 100; // Max results per query
+// Reject NUL and C0 control chars except \t \n \r. NUL truncates strings at
+// the C-API boundary in some bridge backends (key collision); ANSI/control
+// chars enable terminal injection when values are echoed back; \r/\n in
+// values fed to log files breaks log-line integrity.
+const CONTROL_CHAR_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F]/;
+function validateString(value, name, maxLen = MAX_STRING_LENGTH) {
+    if (typeof value !== 'string' || value.length === 0)
+        return null;
+    if (value.length > maxLen)
+        return null;
+    if (CONTROL_CHAR_RE.test(value))
+        return null;
+    return value;
 }
-function getLegacyPath() {
-    return join(getMonomindDataRoot(), MEMORY_SUBDIR, LEGACY_MEMORY_FILE);
+function validatePositiveInt(value, defaultVal, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return defaultVal;
+    const n = Math.floor(value);
+    return n > 0 ? Math.min(n, max) : defaultVal;
 }
-function getMigrationMarkerPath() {
-    return join(getMonomindDataRoot(), MEMORY_SUBDIR, MIGRATION_MARKER);
+function validateScore(value, defaultVal) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return defaultVal;
+    return Math.max(0, Math.min(1, value));
 }
-function ensureMemoryDir() {
-    const dir = getMemoryDir();
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
+function sanitizeError(error) {
+    if (error instanceof Error) {
+        // Strip filesystem paths from error messages — match path components even
+        // when no trailing slash (path at end of message before whitespace, colon, EOL)
+        return error.message
+            .replace(/\/[^\s:]+(\/|(?=\s|:|$))/g, '<path>/')
+            .substring(0, 500);
     }
+    return 'Internal error';
 }
-// D-2: Input bounds for memory parameters
-const MAX_KEY_LENGTH = 1024;
-const MAX_VALUE_SIZE = 1024 * 1024; // 1MB
-const MAX_QUERY_LENGTH = 4096;
-const MAX_NAMESPACE_LENGTH = 256;
-const MAX_AGENT_ID_LENGTH = 256;
-const MAX_TAGS_COUNT = 50;
-const MAX_TAG_LENGTH = 256;
-function validateMemoryInput(key, value, query) {
-    if (key && key.length > MAX_KEY_LENGTH) {
-        throw new Error(`Key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);
-    }
-    if (value && value.length > MAX_VALUE_SIZE) {
-        throw new Error(`Value exceeds maximum size of ${MAX_VALUE_SIZE} bytes`);
+// Lazy-cached bridge module
+let bridgeModule = null;
+async function getBridge() {
+    if (!bridgeModule) {
+        bridgeModule = await import('../memory/memory-bridge.js');
     }
-    if (query && query.length > MAX_QUERY_LENGTH) {
-        throw new Error(`Query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`);
-    }
-}
-/**
- * Check if legacy JSON store exists and needs migration
- */
-function hasLegacyStore() {
-    const legacyPath = getLegacyPath();
-    const migrationMarker = getMigrationMarkerPath();
-    return existsSync(legacyPath) && !existsSync(migrationMarker);
+    return bridgeModule;
 }
-/**
- * Load legacy JSON store for migration
- */
-const MAX_LEGACY_STORE_BYTES = 50 * 1024 * 1024;
-function loadLegacyStore() {
-    try {
-        const path = getLegacyPath();
-        if (existsSync(path)) {
-            if (statSync(path).size > MAX_LEGACY_STORE_BYTES)
-                return null;
-            const data = readFileSync(path, 'utf-8');
-            const parsed = JSON.parse(data);
-            if (parsed && typeof parsed === 'object' && Object.prototype.hasOwnProperty.call(parsed, '__proto__'))
-                return null;
-            return parsed;
+// ===== memory_health — Controller health check =====
+export const memoryHealth = {
+    name: 'memory_health',
+    description: 'Get Memory backend health status including cache stats and attestation count',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+    handler: async () => {
+        try {
+            const bridge = await getBridge();
+            const health = await bridge.bridgeHealthCheck();
+            if (!health)
+                return { available: false, error: 'Memory bridge not available' };
+            return health;
         }
-    }
-    catch {
-        // Return null on error
-    }
-    return null;
-}
-/**
- * Mark migration as complete
- */
-function markMigrationComplete() {
-    ensureMemoryDir();
-    const dest = getMigrationMarkerPath();
-    const tmp = dest + '.tmp';
-    writeFileSync(tmp, JSON.stringify({
-        migratedAt: new Date().toISOString(),
-        version: '3.0.0',
-    }), 'utf-8');
-    renameSync(tmp, dest);
-}
-/**
- * Lazy-load memory initializer functions to avoid circular deps
- */
-async function getMemoryFunctions() {
-    const { storeEntry, searchEntries, listEntries, getEntry, deleteEntry, initializeMemoryDatabase, checkMemoryInitialization, } = await import('../memory/memory-initializer.js');
-    return {
-        storeEntry,
-        searchEntries,
-        listEntries,
-        getEntry,
-        deleteEntry,
-        initializeMemoryDatabase,
-        checkMemoryInitialization,
-    };
-}
-/**
- * Ensure memory database is initialized and migrate legacy data if needed
- */
-async function ensureInitialized() {
-    const { initializeMemoryDatabase, checkMemoryInitialization, storeEntry } = await getMemoryFunctions();
-    // Check if already initialized
-    const status = await checkMemoryInitialization();
-    if (!status.initialized) {
-        await initializeMemoryDatabase({ force: false, verbose: false });
-    }
-    // Migrate legacy JSON data if exists
-    if (hasLegacyStore()) {
-        const legacyStore = loadLegacyStore();
-        if (legacyStore && Object.keys(legacyStore.entries).length > 0) {
-            console.error('[MCP Memory] Migrating legacy JSON store to sql.js...');
-            let migrated = 0;
-            for (const [key, entry] of Object.entries(legacyStore.entries)) {
-                try {
-                    // Convert value to string for storage
-                    const value = typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value);
-                    await storeEntry({
-                        key,
-                        value,
-                        namespace: 'default',
-                        generateEmbeddingFlag: true,
-                    });
-                    migrated++;
-                }
-                catch (e) {
-                    console.error(`[MCP Memory] Failed to migrate key "${key}":`, e);
-                }
-            }
-            console.error(`[MCP Memory] Migrated ${migrated}/${Object.keys(legacyStore.entries).length} entries`);
-            markMigrationComplete();
+        catch (error) {
+            return { available: false, error: sanitizeError(error) };
         }
-    }
-}
-export const memoryTools = [
-    {
-        name: 'memory_store',
-        description: 'Store a value in memory with vector embedding for semantic search (sql.js + HNSW backend). Use upsert=true to update existing keys.',
-        category: 'memory',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Memory key (unique within namespace)' },
-                value: { description: 'Value to store (string or object)' },
-                namespace: { type: 'string', description: 'Namespace for organization (default: "default")' },
-                tags: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Optional tags for filtering',
-                },
-                ttl: { type: 'number', description: 'Time-to-live in seconds (optional)' },
-                upsert: { type: 'boolean', description: 'If true, update existing key instead of failing (default: false)' },
-            },
-            required: ['key', 'value'],
+    },
+};
+// ===== memory_controllers — List all controllers =====
+export const memoryControllers = {
+    name: 'memory_controllers',
+    description: 'List all Memory backends and their initialization status',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+    handler: async () => {
+        try {
+            const bridge = await getBridge();
+            const controllers = await bridge.bridgeListControllers();
+            if (!controllers)
+                return { available: false, controllers: [], error: 'Memory bridge not available — @monomind/memory not installed or missing controller-registry. Use memory_store/memory_search tools instead.' };
+            return {
+                available: true,
+                controllers,
+                total: controllers.length,
+                active: controllers.filter((c) => c.enabled).length,
+            };
+        }
+        catch (error) {
+            return { available: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_pattern_store — Store via ReasoningBank =====
+export const memoryPatternStore = {
+    name: 'memory_pattern-store',
+    description: 'Store a pattern directly via ReasoningBank controller',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: 'Pattern description' },
+            type: { type: 'string', description: 'Pattern type (e.g., task-routing, error-recovery)' },
+            confidence: { type: 'number', description: 'Confidence score (0-1)' },
         },
-        handler: async (input) => {
-            await ensureInitialized();
-            const { storeEntry } = await getMemoryFunctions();
-            const key = input.key;
-            const rawNamespace = input.namespace || 'default';
-            const namespace = typeof rawNamespace === 'string' && rawNamespace.length > MAX_NAMESPACE_LENGTH
-                ? rawNamespace.slice(0, MAX_NAMESPACE_LENGTH) : rawNamespace;
-            const rawValue = input.value;
-            const value = typeof rawValue === 'string' ? rawValue : (rawValue !== undefined ? JSON.stringify(rawValue) : '');
-            const rawTags = input.tags || [];
-            // Cap tags count and individual tag length to prevent store inflation
-            const tags = rawTags.slice(0, MAX_TAGS_COUNT).map(t => typeof t === 'string' && t.length > MAX_TAG_LENGTH ? t.slice(0, MAX_TAG_LENGTH) : t);
-            const ttl = input.ttl;
-            const upsert = input.upsert || false;
-            if (!value) {
-                return {
-                    success: false,
-                    key,
-                    stored: false,
-                    hasEmbedding: false,
-                    error: 'Value is required and cannot be empty',
-                };
-            }
-            validateMemoryInput(key, value);
-            const startTime = performance.now();
-            try {
-                const result = await storeEntry({
-                    key,
-                    value,
-                    namespace,
-                    generateEmbeddingFlag: true,
-                    tags,
-                    ttl,
-                    upsert,
-                });
-                const duration = performance.now() - startTime;
-                return {
-                    success: result.success,
-                    key,
-                    namespace,
-                    stored: result.success,
-                    storedAt: new Date().toISOString(),
-                    hasEmbedding: !!result.embedding,
-                    embeddingDimensions: result.embedding?.dimensions || null,
-                    backend: 'sql.js + HNSW',
-                    storeTime: `${duration.toFixed(2)}ms`,
-                    error: result.error,
-                };
-            }
-            catch (error) {
-                return {
-                    success: false,
-                    key,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                };
-            }
+        required: ['pattern'],
+    },
+    handler: async (params) => {
+        try {
+            const pattern = validateString(params.pattern, 'pattern');
+            if (!pattern)
+                return { success: false, error: 'pattern is required (non-empty string, max 100KB)' };
+            const bridge = await getBridge();
+            const result = await bridge.bridgeStorePattern({
+                pattern,
+                type: validateString(params.type, 'type', 200) ?? 'general',
+                confidence: validateScore(params.confidence, 0.8),
+            });
+            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_pattern_search — Search via ReasoningBank =====
+export const memoryPatternSearch = {
+    name: 'memory_pattern-search',
+    description: 'Search patterns via ReasoningBank controller with BM25+semantic hybrid',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Search query' },
+            topK: { type: 'number', description: 'Number of results (default: 5)' },
+            minConfidence: { type: 'number', description: 'Minimum score threshold (0-1)' },
         },
+        required: ['query'],
     },
-    {
-        name: 'memory_retrieve',
-        description: 'Retrieve a value from memory by key',
-        category: 'memory',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Memory key' },
-                namespace: { type: 'string', description: 'Namespace (default: "default")' },
-                agentId: { type: 'string', description: 'Caller agent ID (enables collaborative memory promotion)' },
-            },
-            required: ['key'],
+    handler: async (params) => {
+        try {
+            const query = validateString(params.query, 'query', 10_000);
+            if (!query)
+                return { results: [], error: 'query is required (non-empty string, max 10KB)' };
+            const bridge = await getBridge();
+            const result = await bridge.bridgeSearchPatterns({
+                query,
+                topK: validatePositiveInt(params.topK, 5, MAX_TOP_K),
+                minConfidence: validateScore(params.minConfidence, 0.3),
+            });
+            return result ?? { results: [], controller: 'unavailable' };
+        }
+        catch (error) {
+            return { results: [], error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_feedback — Record task feedback =====
+export const memoryFeedback = {
+    name: 'memory_feedback',
+    description: 'Record task feedback for learning via LearningSystem + ReasoningBank controllers',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            taskId: { type: 'string', description: 'Task identifier' },
+            success: { type: 'boolean', description: 'Whether task succeeded' },
+            quality: { type: 'number', description: 'Quality score (0-1)' },
+            agent: { type: 'string', description: 'Agent that performed the task' },
         },
-        handler: async (input) => {
-            await ensureInitialized();
-            const { getEntry } = await getMemoryFunctions();
-            const key = input.key;
-            const rawNs = input.namespace || 'default';
-            const namespace = typeof rawNs === 'string' && rawNs.length > MAX_NAMESPACE_LENGTH
-                ? rawNs.slice(0, MAX_NAMESPACE_LENGTH) : rawNs;
-            const rawAgentId = input.agentId;
-            const agentId = typeof rawAgentId === 'string' && rawAgentId.length > MAX_AGENT_ID_LENGTH
-                ? rawAgentId.slice(0, MAX_AGENT_ID_LENGTH) : rawAgentId;
-            validateMemoryInput(key);
-            try {
-                const result = await getEntry({ key, namespace, agentId });
-                if (result.found && result.entry) {
-                    // Try to parse JSON value
-                    let value = result.entry.content;
-                    try {
-                        value = JSON.parse(result.entry.content);
-                    }
-                    catch {
-                        // Keep as string
-                    }
-                    return {
-                        key,
-                        namespace,
-                        value,
-                        tags: result.entry.tags,
-                        storedAt: result.entry.createdAt,
-                        updatedAt: result.entry.updatedAt,
-                        accessCount: result.entry.accessCount,
-                        hasEmbedding: result.entry.hasEmbedding,
-                        found: true,
-                        backend: 'sql.js + HNSW',
-                    };
-                }
-                return {
-                    key,
-                    namespace,
-                    value: null,
-                    found: false,
-                };
-            }
-            catch (error) {
-                return {
-                    key,
-                    namespace,
-                    value: null,
-                    found: false,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                };
-            }
+        required: ['taskId'],
+    },
+    handler: async (params) => {
+        try {
+            const taskId = validateString(params.taskId, 'taskId', 500);
+            if (!taskId)
+                return { success: false, error: 'taskId is required (non-empty string, max 500 chars)' };
+            const bridge = await getBridge();
+            const result = await bridge.bridgeRecordFeedback({
+                taskId,
+                success: params.success === true,
+                quality: validateScore(params.quality, 0.85),
+                agent: validateString(params.agent, 'agent', 200) ?? undefined,
+            });
+            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_causal_edge — Record causal relationships =====
+export const memoryCausalEdge = {
+    name: 'memory_causal-edge',
+    description: 'Record a causal edge between two memory entries via CausalMemoryGraph',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sourceId: { type: 'string', description: 'Source entry ID' },
+            targetId: { type: 'string', description: 'Target entry ID' },
+            relation: { type: 'string', description: 'Relationship type (e.g., caused, preceded, succeeded)' },
+            weight: { type: 'number', description: 'Edge weight (0-1)' },
         },
+        required: ['sourceId', 'targetId', 'relation'],
     },
-    {
-        name: 'memory_search',
-        description: 'Semantic vector search using HNSW index (150x-12,500x faster than keyword search)',
-        category: 'memory',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                query: { type: 'string', description: 'Search query (semantic similarity)' },
-                namespace: { type: 'string', description: 'Namespace to search (default: "default")' },
-                limit: { type: 'number', description: 'Maximum results (default: 10)' },
-                threshold: { type: 'number', description: 'Minimum similarity threshold 0-1 (default: 0.3)' },
-            },
-            required: ['query'],
+    handler: async (params) => {
+        try {
+            const sourceId = validateString(params.sourceId, 'sourceId', 500);
+            const targetId = validateString(params.targetId, 'targetId', 500);
+            const relation = validateString(params.relation, 'relation', 200);
+            if (!sourceId)
+                return { success: false, error: 'sourceId is required (non-empty string)' };
+            if (!targetId)
+                return { success: false, error: 'targetId is required (non-empty string)' };
+            if (!relation)
+                return { success: false, error: 'relation is required (non-empty string)' };
+            const bridge = await getBridge();
+            const result = await bridge.bridgeRecordCausalEdge({
+                sourceId,
+                targetId,
+                relation,
+                weight: typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined,
+            });
+            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_route — Route via SemanticRouter =====
+export const memoryRoute = {
+    name: 'memory_route',
+    description: 'Route a task via SemanticRouter or LearningSystem recommendAlgorithm',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            task: { type: 'string', description: 'Task description to route' },
+            context: { type: 'string', description: 'Additional context' },
         },
-        handler: async (input) => {
-            await ensureInitialized();
-            const { searchEntries } = await getMemoryFunctions();
-            const query = input.query;
-            const rawSearchNs = input.namespace || 'default';
-            const namespace = typeof rawSearchNs === 'string' && rawSearchNs.length > MAX_NAMESPACE_LENGTH
-                ? rawSearchNs.slice(0, MAX_NAMESPACE_LENGTH) : rawSearchNs;
-            const limit = Math.min(Math.max(input.limit || 10, 1), 1000);
-            const threshold = input.threshold || 0.3;
-            validateMemoryInput(undefined, undefined, query);
-            const startTime = performance.now();
-            try {
-                const result = await searchEntries({
-                    query,
-                    namespace,
-                    limit,
-                    threshold,
-                });
-                const duration = performance.now() - startTime;
-                // Parse JSON values in results
-                const results = result.results.map(r => {
-                    let value = r.content;
-                    try {
-                        value = JSON.parse(r.content);
-                    }
-                    catch {
-                        // Keep as string
-                    }
-                    return {
-                        key: r.key,
-                        namespace: r.namespace,
-                        value,
-                        similarity: r.score,
-                    };
-                });
-                return {
-                    query,
-                    results,
-                    total: results.length,
-                    searchTime: `${duration.toFixed(2)}ms`,
-                    backend: 'HNSW + sql.js',
-                };
-            }
-            catch (error) {
-                return {
-                    query,
-                    results: [],
-                    total: 0,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                };
-            }
+        required: ['task'],
+    },
+    handler: async (params) => {
+        try {
+            const task = validateString(params.task, 'task', 10_000);
+            if (!task)
+                return { route: 'general', confidence: 0.5, agents: ['coder'], controller: 'error', error: 'task is required (non-empty string)' };
+            const bridge = await getBridge();
+            const result = await bridge.bridgeRouteTask({
+                task,
+                context: validateString(params.context, 'context', 10_000) ?? undefined,
+            });
+            return result ?? { route: 'general', confidence: 0.5, agents: ['coder'], controller: 'fallback' };
+        }
+        catch (error) {
+            return { route: 'general', confidence: 0.5, agents: ['coder'], controller: 'error', error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_session_start — Session with ReflexionMemory =====
+export const memorySessionStart = {
+    name: 'memory_session-start',
+    description: 'Start a session with ReflexionMemory episodic replay',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sessionId: { type: 'string', description: 'Session identifier' },
+            context: { type: 'string', description: 'Session context for pattern retrieval' },
+        },
+        required: ['sessionId'],
+    },
+    handler: async (params) => {
+        try {
+            const sessionId = validateString(params.sessionId, 'sessionId', 500);
+            if (!sessionId)
+                return { success: false, error: 'sessionId is required (non-empty string)' };
+            const bridge = await getBridge();
+            const result = await bridge.bridgeSessionStart({
+                sessionId,
+                context: validateString(params.context, 'context', 10_000) ?? undefined,
+            });
+            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_session_end — End session + NightlyLearner =====
+export const memorySessionEnd = {
+    name: 'memory_session-end',
+    description: 'End session, persist to ReflexionMemory, trigger NightlyLearner consolidation',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sessionId: { type: 'string', description: 'Session identifier' },
+            summary: { type: 'string', description: 'Session summary' },
+            tasksCompleted: { type: 'number', description: 'Number of tasks completed' },
         },
+        required: ['sessionId'],
     },
-    {
-        name: 'memory_delete',
-        description: 'Delete a memory entry by key',
-        category: 'memory',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                key: { type: 'string', description: 'Memory key' },
-                namespace: { type: 'string', description: 'Namespace (default: "default")' },
+    handler: async (params) => {
+        try {
+            const sessionId = validateString(params.sessionId, 'sessionId', 500);
+            if (!sessionId)
+                return { success: false, error: 'sessionId is required (non-empty string)' };
+            const bridge = await getBridge();
+            const result = await bridge.bridgeSessionEnd({
+                sessionId,
+                summary: validateString(params.summary, 'summary', 50_000) ?? undefined,
+                tasksCompleted: validatePositiveInt(params.tasksCompleted, 0, 10_000),
+            });
+            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_hierarchical_store — Store to hierarchical memory =====
+export const memoryHierarchicalStore = {
+    name: 'memory_hierarchical-store',
+    description: 'Store to hierarchical memory with tier (working, episodic, semantic)',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            key: { type: 'string', description: 'Memory entry key' },
+            value: { type: 'string', description: 'Memory entry value' },
+            tier: {
+                type: 'string',
+                description: 'Memory tier (working, episodic, semantic)',
+                enum: ['working', 'episodic', 'semantic'],
+                default: 'working',
             },
-            required: ['key'],
         },
-        handler: async (input) => {
-            await ensureInitialized();
-            const { deleteEntry } = await getMemoryFunctions();
-            const key = input.key;
-            const rawDelNs = input.namespace || 'default';
-            const namespace = typeof rawDelNs === 'string' && rawDelNs.length > MAX_NAMESPACE_LENGTH
-                ? rawDelNs.slice(0, MAX_NAMESPACE_LENGTH) : rawDelNs;
-            validateMemoryInput(key);
-            try {
-                const result = await deleteEntry({ key, namespace });
-                return {
-                    success: result.deleted,
-                    key,
-                    namespace,
-                    deleted: result.deleted,
-                    hnswIndexInvalidated: result.deleted,
-                    backend: 'sql.js + HNSW',
-                };
+        required: ['key', 'value'],
+    },
+    handler: async (params) => {
+        try {
+            const key = validateString(params.key, 'key', 1000);
+            const value = validateString(params.value, 'value');
+            if (!key)
+                return { success: false, error: 'key is required (non-empty string, max 1KB)' };
+            if (!value)
+                return { success: false, error: 'value is required (non-empty string, max 100KB)' };
+            const tier = validateString(params.tier, 'tier', 20) ?? 'working';
+            if (!['working', 'episodic', 'semantic'].includes(tier)) {
+                return { success: false, error: `Invalid tier: ${tier}. Must be working, episodic, or semantic` };
             }
-            catch (error) {
-                return {
-                    success: false,
-                    key,
-                    namespace,
-                    deleted: false,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                };
+            const bridge = await getBridge();
+            const result = await bridge.bridgeHierarchicalStore({ key, value, tier });
+            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_hierarchical_recall — Recall from hierarchical memory =====
+export const memoryHierarchicalRecall = {
+    name: 'memory_hierarchical-recall',
+    description: 'Recall from hierarchical memory with optional tier filter',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Recall query' },
+            tier: { type: 'string', description: 'Filter by tier (working, episodic, semantic)' },
+            topK: { type: 'number', description: 'Number of results (default: 5)' },
+        },
+        required: ['query'],
+    },
+    handler: async (params) => {
+        try {
+            const query = validateString(params.query, 'query', 10_000);
+            if (!query)
+                return { results: [], error: 'query is required (non-empty string, max 10KB)' };
+            const tier = validateString(params.tier, 'tier', 20);
+            if (tier && !['working', 'episodic', 'semantic'].includes(tier)) {
+                return { results: [], error: `Invalid tier: ${tier}. Must be working, episodic, or semantic` };
             }
+            const bridge = await getBridge();
+            const result = await bridge.bridgeHierarchicalRecall({
+                query,
+                tier: tier ?? undefined,
+                topK: validatePositiveInt(params.topK, 5, MAX_TOP_K),
+            });
+            return result ?? { results: [], error: 'Memory bridge not available. Use memory_search instead.' };
+        }
+        catch (error) {
+            return { results: [], error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_consolidate — Run memory consolidation =====
+export const memoryConsolidate = {
+    name: 'memory_consolidate',
+    description: 'Run memory consolidation to promote entries across tiers and compress old data',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            minAge: { type: 'number', description: 'Minimum age in hours since store (optional)' },
+            maxEntries: { type: 'number', description: 'Maximum entries to consolidate (optional)' },
         },
     },
-    {
-        name: 'memory_list',
-        description: 'List memory entries with optional filtering',
-        category: 'memory',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                namespace: { type: 'string', description: 'Filter by namespace' },
-                limit: { type: 'number', description: 'Maximum results (default: 50)' },
-                offset: { type: 'number', description: 'Offset for pagination (default: 0)' },
+    handler: async (params) => {
+        try {
+            const bridge = await getBridge();
+            // Reject NaN and Infinity. typeof === 'number' returns true for both.
+            // NaN propagates through arithmetic and corrupts consolidation accounting;
+            // Infinity makes `entry.age >= minAge` always false, silently no-op.
+            const minAge = typeof params.minAge === 'number' && Number.isFinite(params.minAge)
+                ? Math.max(0, Math.min(params.minAge, 24 * 365 * 10))
+                : undefined;
+            const result = await bridge.bridgeConsolidate({
+                minAge,
+                maxEntries: params.maxEntries !== undefined
+                    ? validatePositiveInt(params.maxEntries, 1000, 10_000)
+                    : undefined,
+            });
+            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_batch — Batch operations (insert, update, delete) =====
+export const memoryBatch = {
+    name: 'memory_batch',
+    description: 'Batch operations on memory entries (insert, update, delete)',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            operation: {
+                type: 'string',
+                description: 'Batch operation type',
+                enum: ['insert', 'update', 'delete'],
+            },
+            entries: {
+                type: 'array',
+                description: 'Array of {key, value} entries to operate on',
+                items: {
+                    type: 'object',
+                    properties: {
+                        key: { type: 'string' },
+                        value: { type: 'string' },
+                    },
+                    required: ['key'],
+                },
             },
         },
-        handler: async (input) => {
-            await ensureInitialized();
-            const { listEntries } = await getMemoryFunctions();
-            const rawListNs = input.namespace;
-            const namespace = typeof rawListNs === 'string' && rawListNs.length > MAX_NAMESPACE_LENGTH
-                ? rawListNs.slice(0, MAX_NAMESPACE_LENGTH) : rawListNs;
-            const limit = Math.min(Math.max(input.limit || 50, 1), 1000);
-            const offset = input.offset || 0;
-            try {
-                const result = await listEntries({
-                    namespace,
-                    limit,
-                    offset,
-                });
-                const entries = result.entries.map(e => ({
-                    key: e.key,
-                    namespace: e.namespace,
-                    storedAt: e.createdAt,
-                    updatedAt: e.updatedAt,
-                    accessCount: e.accessCount,
-                    hasEmbedding: e.hasEmbedding,
-                    size: e.size,
-                }));
-                return {
-                    entries,
-                    total: result.total,
-                    limit,
-                    offset,
-                    backend: 'sql.js + HNSW',
-                };
+        required: ['operation', 'entries'],
+    },
+    handler: async (params) => {
+        try {
+            const operation = validateString(params.operation, 'operation', 20);
+            if (!operation)
+                return { success: false, error: 'operation is required (string)' };
+            if (!['insert', 'update', 'delete'].includes(operation)) {
+                return { success: false, error: `Invalid operation: ${operation}. Must be insert, update, or delete` };
             }
-            catch (error) {
-                return {
-                    entries: [],
-                    total: 0,
-                    limit,
-                    offset,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                };
+            if (!Array.isArray(params.entries) || params.entries.length === 0) {
+                return { success: false, error: 'entries is required (non-empty array)' };
             }
-        },
-    },
-    {
-        name: 'memory_stats',
-        description: 'Get memory storage statistics including HNSW index status',
-        category: 'memory',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        handler: async () => {
-            await ensureInitialized();
-            const { checkMemoryInitialization, listEntries } = await getMemoryFunctions();
-            try {
-                const status = await checkMemoryInitialization();
-                // Cap stats sample at 1000 entries — the previous 100000 limit could
-                // load up to 100 GB of resident memory (each entry value capped at 1 MB)
-                // just to compute aggregate counts. Counts above 1000 are reported as
-                // approximate via the dedicated `total` field.
-                const allEntries = await listEntries({ limit: 1000 });
-                // Count by namespace (sample-based for large stores)
-                const namespaces = {};
-                let withEmbeddings = 0;
-                for (const entry of allEntries.entries) {
-                    namespaces[entry.namespace] = (namespaces[entry.namespace] || 0) + 1;
-                    if (entry.hasEmbedding)
-                        withEmbeddings++;
-                }
-                return {
-                    initialized: status.initialized,
-                    totalEntries: allEntries.total,
-                    entriesWithEmbeddings: withEmbeddings,
-                    embeddingCoverage: allEntries.total > 0
-                        ? `${((withEmbeddings / allEntries.total) * 100).toFixed(1)}%`
-                        : '0%',
-                    namespaces,
-                    backend: 'sql.js + HNSW',
-                    version: status.version || '3.0.0',
-                    features: status.features || {
-                        vectorEmbeddings: true,
-                        hnswIndex: true,
-                        semanticSearch: true,
-                    },
-                };
+            if (params.entries.length > MAX_BATCH_SIZE) {
+                return { success: false, error: `Too many entries: ${params.entries.length}. Max is ${MAX_BATCH_SIZE}` };
             }
-            catch (error) {
-                return {
-                    initialized: false,
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                };
+            // Validate each entry. Aggregate-byte cap prevents 500 entries × 100KB
+            // values = 50MB single-call payloads from spiking Node heap to ~200MB
+            // (UTF-16 doubling + downstream copies in the bridge layer).
+            const MAX_BATCH_BYTES = 1_048_576; // 1 MiB total
+            let totalBytes = 0;
+            const validatedEntries = [];
+            for (let i = 0; i < params.entries.length; i++) {
+                const entry = params.entries[i];
+                if (!entry || typeof entry !== 'object') {
+                    return { success: false, error: `entries[${i}] must be an object` };
+                }
+                const key = validateString(entry.key, `entries[${i}].key`, 1000);
+                if (!key)
+                    return { success: false, error: `entries[${i}].key is required (non-empty string)` };
+                const value = validateString(entry.value, `entries[${i}].value`);
+                totalBytes += key.length + (value?.length ?? 0);
+                if (totalBytes > MAX_BATCH_BYTES) {
+                    return { success: false, error: `Batch payload exceeds ${MAX_BATCH_BYTES} bytes` };
+                }
+                validatedEntries.push({ key, value: value ?? undefined });
             }
-        },
+            const bridge = await getBridge();
+            const result = await bridge.bridgeBatchOperation({
+                operation,
+                entries: validatedEntries,
+            });
+            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
     },
-    {
-        name: 'memory_migrate',
-        description: 'Manually trigger migration from legacy JSON store to sql.js',
-        category: 'memory',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                force: { type: 'boolean', description: 'Force re-migration even if already done' },
-            },
+};
+// ===== memory_context_synthesize — Synthesize context from memories =====
+export const memoryContextSynthesize = {
+    name: 'memory_context-synthesize',
+    description: 'Synthesize context from stored memories for a given query',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Query to synthesize context for' },
+            maxEntries: { type: 'number', description: 'Maximum entries to include (default: 10)' },
         },
-        handler: async (input) => {
-            const force = input.force;
-            // Remove migration marker if forcing
-            if (force) {
-                const markerPath = getMigrationMarkerPath();
-                if (existsSync(markerPath)) {
-                    unlinkSync(markerPath);
+        required: ['query'],
+    },
+    handler: async (params) => {
+        try {
+            const query = validateString(params.query, 'query', 10_000);
+            if (!query)
+                return { success: false, error: 'query is required (non-empty string, max 10KB)' };
+            // validateExternalContent: guard against prompt injection in synthesized context
+            // Source: https://arxiv.org/abs/2302.12173, https://arxiv.org/abs/2310.12815
+            try {
+                const secMod = await import('@monomind/security').catch(() => null);
+                const validateExternalContent = secMod?.validateExternalContent;
+                if (validateExternalContent) {
+                    const check = await validateExternalContent(query, 'memory_context-synthesize query');
+                    if (!check.safe) {
+                        return { success: false, error: `Injection guard: ${check.reason}`, injectionDetected: true };
+                    }
                 }
             }
-            // Check if migration was already completed before running it
-            const alreadyMigrated = existsSync(getMigrationMarkerPath());
-            // Check for legacy data
-            const legacyStore = loadLegacyStore();
-            if (!legacyStore || Object.keys(legacyStore.entries).length === 0) {
-                return {
-                    success: true,
-                    message: 'No legacy data to migrate',
-                    migrated: 0,
-                };
-            }
-            // Run migration via ensureInitialized
-            await ensureInitialized();
-            return {
-                success: true,
-                message: alreadyMigrated ? 'Already migrated — use force=true to re-run' : 'Migration completed',
-                migrated: alreadyMigrated ? 0 : Object.keys(legacyStore.entries).length,
-                backend: 'sql.js + HNSW',
-            };
+            catch { /* security module optional */ }
+            const bridge = await getBridge();
+            const result = await bridge.bridgeContextSynthesize({
+                query,
+                maxEntries: validatePositiveInt(params.maxEntries, 10, MAX_TOP_K),
+            });
+            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_semantic_route — Route via SemanticRouter =====
+export const memorySemanticRoute = {
+    name: 'memory_semantic-route',
+    description: 'Route an input via SemanticRouter for intent classification',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            input: { type: 'string', description: 'Input text to route' },
         },
+        required: ['input'],
     },
+    handler: async (params) => {
+        try {
+            const input = validateString(params.input, 'input', 10_000);
+            if (!input)
+                return { route: null, error: 'input is required (non-empty string, max 10KB)' };
+            const bridge = await getBridge();
+            const result = await bridge.bridgeSemanticRoute({ input });
+            return result ?? { route: null, error: 'Memory bridge not available. Use hooks route instead.' };
+        }
+        catch (error) {
+            return { route: null, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== Export all tools =====
+export const memoryTools = [
+    memoryHealth,
+    memoryControllers,
+    memoryPatternStore,
+    memoryPatternSearch,
+    memoryFeedback,
+    memoryCausalEdge,
+    memoryRoute,
+    memorySessionStart,
+    memorySessionEnd,
+    memoryHierarchicalStore,
+    memoryHierarchicalRecall,
+    memoryConsolidate,
+    memoryBatch,
+    memoryContextSynthesize,
+    memorySemanticRoute,
 ];
 //# sourceMappingURL=memory-tools.js.map