sensorium-mcp 2.7.0 → 2.8.1

package/dist/index.js

@@ -33,7 +33,9 @@ import { createRequire } from "module";
 import { homedir } from "os";
 import { basename, join } from "path";
 import { peekThreadMessages, readThreadMessages, startDispatcher } from "./dispatcher.js";
-import { analyzeVoiceEmotion, analyzeVideoFrames, extractVideoFrames, textToSpeech, transcribeAudio, TTS_VOICES } from "./openai.js";
+import { assembleBootstrap, forgetMemory, getMemoryStatus, getRecentEpisodes, getTopicIndex, initMemoryDb, runIntelligentConsolidation, saveEpisode, saveProcedure, saveSemanticNote, saveVoiceSignature, searchProcedures, searchSemanticNotes, supersedeNote, updateProcedure, updateSemanticNote, } from "./memory.js";
+import { analyzeVideoFrames, analyzeVoiceEmotion, extractVideoFrames, textToSpeech, transcribeAudio, TTS_VOICES } from "./openai.js";
+import { addSchedule, checkDueTasks, generateTaskId, listSchedules, purgeSchedules, removeSchedule } from "./scheduler.js";
 import { TelegramClient } from "./telegram.js";
 import { describeADV, errorMessage, errorResult, IMAGE_EXTENSIONS, OPENAI_TTS_MAX_CHARS } from "./utils.js";
 /**
@@ -71,7 +73,6 @@ function buildAnalysisTags(analysis) {
     }
     return tags;
 }
-import { addSchedule, checkDueTasks, generateTaskId, listSchedules, purgeSchedules, removeSchedule } from "./scheduler.js";
 const esmRequire = createRequire(import.meta.url);
 const { version: PKG_VERSION } = esmRequire("../package.json");
 const telegramifyMarkdown = esmRequire("telegramify-markdown");
@@ -155,6 +156,21 @@ const telegram = new TelegramClient(TELEGRAM_TOKEN);
 // ensures no updates are lost between concurrent sessions.
 // ---------------------------------------------------------------------------
 await startDispatcher(telegram, TELEGRAM_CHAT_ID);
+// Dead session detector — runs every 2 minutes
+setInterval(async () => {
+    if (!currentThreadId)
+        return;
+    const elapsed = Date.now() - lastToolCallAt;
+    if (elapsed > DEAD_SESSION_TIMEOUT_MS && !deadSessionAlerted) {
+        deadSessionAlerted = true;
+        try {
+            const tg = new TelegramClient(TELEGRAM_TOKEN);
+            const minutes = Math.round(elapsed / 60000);
+            await tg.sendMessage(TELEGRAM_CHAT_ID, `⚠️ *Session appears down* — no tool calls in ${minutes} minutes\\. The agent may have crashed or the VS Code window compacted the context\\. Please check and restart if needed\\.`, "MarkdownV2", currentThreadId);
+        }
+        catch (_) { /* non-fatal */ }
+    }
+}, 2 * 60 * 1000);
 // Directory for persisting downloaded images and documents to disk.
 const FILES_DIR = join(homedir(), ".remote-copilot-mcp", "files");
 mkdirSync(FILES_DIR, { recursive: true });
@@ -220,6 +236,13 @@ function removeSession(chatId, name) {
         saveSessionMap(map);
     }
 }
+// Memory database — initialized lazily on first use
+let memoryDb = null;
+function getMemoryDb() {
+    if (!memoryDb)
+        memoryDb = initMemoryDb();
+    return memoryDb;
+}
 // Thread ID of the active session's forum topic. Set by start_session.
 // All sends and receives are scoped to this thread so concurrent sessions
 // in different topics never interfere with each other.
@@ -243,11 +266,10 @@ function resolveThreadId(args) {
     }
     return currentThreadId;
 }
-// Timestamp of the last keep-alive ping sent to Telegram.
-// Used to send periodic "session still alive" messages so the operator knows
-// the agent hasn't silently died.
-let lastKeepAliveSentAt = Date.now();
-const KEEP_ALIVE_INTERVAL_MS = 30 * 60 * 1000; // 30 minutes
+// Dead session detection — tracks when the last tool call was made
+let lastToolCallAt = Date.now();
+let deadSessionAlerted = false;
+const DEAD_SESSION_TIMEOUT_MS = 60 * 60 * 1000; // 60 minutes (2× wait_for_instructions timeout)
 // Timestamp of the last message received from the operator.
 // Used by the scheduler to detect idle periods.
 let lastOperatorMessageAt = Date.now();
@@ -437,6 +459,223 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
             },
         },
+        // ── Memory Tools ──────────────────────────────────────────────────
+        {
+            name: "memory_bootstrap",
+            description: "Load memory briefing for session start. Call this ONCE after start_session. " +
+                "Returns operator profile, recent context, active procedures, and memory health. " +
+                "~2,500 tokens. Essential for crash recovery — restores knowledge from previous sessions.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    threadId: {
+                        type: "number",
+                        description: "Active thread ID.",
+                    },
+                },
+            },
+        },
+        {
+            name: "memory_search",
+            description: "Search across all memory layers for relevant information. " +
+                "Use BEFORE starting any task to recall facts, preferences, past events, or procedures. " +
+                "Returns ranked results with source layer. Do NOT use for info already in your bootstrap briefing.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Natural language search query.",
+                    },
+                    layers: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: 'Filter layers: ["episodic", "semantic", "procedural"]. Default: all.',
+                    },
+                    types: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: 'Filter by type: ["fact", "preference", "pattern", "workflow", ...].',
+                    },
+                    maxTokens: {
+                        type: "number",
+                        description: "Token budget for results. Default: 1500.",
+                    },
+                    threadId: {
+                        type: "number",
+                        description: "Active thread ID.",
+                    },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "memory_save",
+            description: "Save a piece of knowledge to semantic memory (Layer 3). " +
+                "Use when you learn something important that should persist across sessions: " +
+                "operator preferences, corrections, facts, patterns. " +
+                "Do NOT use for routine conversation — episodic memory captures that automatically.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    content: {
+                        type: "string",
+                        description: "The fact/preference/pattern in one clear sentence.",
+                    },
+                    type: {
+                        type: "string",
+                        description: '"fact" | "preference" | "pattern" | "entity" | "relationship".',
+                    },
+                    keywords: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "3-7 keywords for retrieval.",
+                    },
+                    confidence: {
+                        type: "number",
+                        description: "0.0-1.0. Default: 0.8.",
+                    },
+                    threadId: {
+                        type: "number",
+                        description: "Active thread ID.",
+                    },
+                },
+                required: ["content", "type", "keywords"],
+            },
+        },
+        {
+            name: "memory_save_procedure",
+            description: "Save or update a learned workflow/procedure to procedural memory (Layer 4). " +
+                "Use after completing a multi-step task the 2nd+ time, or when the operator teaches a process.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Short name for the procedure.",
+                    },
+                    type: {
+                        type: "string",
+                        description: '"workflow" | "habit" | "tool_pattern" | "template".',
+                    },
+                    description: {
+                        type: "string",
+                        description: "What this procedure accomplishes.",
+                    },
+                    steps: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Ordered steps (for workflows).",
+                    },
+                    triggerConditions: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "When to use this procedure.",
+                    },
+                    procedureId: {
+                        type: "string",
+                        description: "Existing ID to update (omit to create new).",
+                    },
+                    threadId: {
+                        type: "number",
+                        description: "Active thread ID.",
+                    },
+                },
+                required: ["name", "type", "description"],
+            },
+        },
+        {
+            name: "memory_update",
+            description: "Update or supersede an existing semantic note or procedure. " +
+                "Use when operator corrects stored information or when facts have changed.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    memoryId: {
+                        type: "string",
+                        description: "note_id or procedure_id to update.",
+                    },
+                    action: {
+                        type: "string",
+                        description: '"update" (modify in place) | "supersede" (expire old, create new).',
+                    },
+                    newContent: {
+                        type: "string",
+                        description: "New content (required for supersede, optional for update).",
+                    },
+                    newConfidence: {
+                        type: "number",
+                        description: "Updated confidence score.",
+                    },
+                    reason: {
+                        type: "string",
+                        description: "Why this is being updated.",
+                    },
+                    threadId: {
+                        type: "number",
+                        description: "Active thread ID.",
+                    },
+                },
+                required: ["memoryId", "action", "reason"],
+            },
+        },
+        {
+            name: "memory_consolidate",
+            description: "Run memory consolidation cycle (sleep process). Normally triggered automatically during idle. " +
+                "Manually call if memory_status shows many unconsolidated episodes.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    threadId: {
+                        type: "number",
+                        description: "Active thread ID.",
+                    },
+                    phases: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: 'Run specific phases: ["promote", "decay", "meta"]. Default: all.',
+                    },
+                },
+            },
+        },
+        {
+            name: "memory_status",
+            description: "Get memory system health and statistics. Lightweight (~300 tokens). " +
+                "Use when unsure if you have relevant memories, to check if consolidation is needed, " +
+                "or to report memory state to operator.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    threadId: {
+                        type: "number",
+                        description: "Active thread ID.",
+                    },
+                },
+            },
+        },
+        {
+            name: "memory_forget",
+            description: "Mark a memory as expired/forgotten. Use sparingly — most forgetting happens via decay. " +
+                "Use when operator explicitly asks to forget something or info is confirmed wrong.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    memoryId: {
+                        type: "string",
+                        description: "note_id, procedure_id, or episode_id to forget.",
+                    },
+                    reason: {
+                        type: "string",
+                        description: "Why this is being forgotten.",
+                    },
+                    threadId: {
+                        type: "number",
+                        description: "Active thread ID.",
+                    },
+                },
+                required: ["memoryId", "reason"],
+            },
+        },
     ],
 }));
 // ── Tool implementations ────────────────────────────────────────────────────
@@ -459,14 +698,18 @@ function getReminders(threadId) {
         : "";
     return ("\n\n## MANDATORY WORKFLOW" +
         "\n1. **Plan**: Use the todo list tool to break work into discrete items BEFORE starting. Non-negotiable." +
-        "\n2. **Subagents**: Use subagents heavily — spin them up for code edits, searches, research, and reviews. Run them in parallel when tasks are independent. You plan and verify; subagents execute." +
+        "\n2. **Subagents**: Use subagents heavily — spin them up for code edits, searches, research, reviews, and terminal commands. Subagents have full access to ALL MCP tools including terminal, file system, and web search. Run them in parallel when tasks are independent. You plan and verify; subagents execute." +
         "\n3. **Reporting**: Call `report_progress` after completing EACH todo item. The operator is remote and CANNOT see your work unless you explicitly report it. Silence = failure." +
         "\n4. **Never stop**: When all work is done, call `remote_copilot_wait_for_instructions` immediately. Never summarize or stop." +
+        "\n5. **Memory**: (a) Call `memory_save` whenever you learn operator preferences, facts, or corrections. (b) Call `memory_search` before starting any task to recall relevant context. (c) Call `memory_status` when reporting progress to include memory health. These tools persist knowledge across sessions." +
         threadHint +
         `\n- Current time: ${timeStr} | Session uptime: ${uptimeMin}m`);
 }
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    // Dead session detection — reset on any tool call
+    lastToolCallAt = Date.now();
+    deadSessionAlerted = false;
     // ── start_session ─────────────────────────────────────────────────────────
     if (name === "start_session") {
         sessionStartedAt = Date.now();
@@ -513,7 +756,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             // Resume mode: verify the thread is still alive by sending a message.
             // If the topic was deleted, drop the cached mapping and fall through to
             // create a new topic.
-            lastKeepAliveSentAt = Date.now();
             try {
                 const msg = convertMarkdown("🔄 **Session resumed.** Continuing in this thread.");
                 await telegram.sendMessage(TELEGRAM_CHAT_ID, msg, "MarkdownV2", currentThreadId);
@@ -555,7 +797,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return errorResult(`Error: Could not create forum topic: ${errorMessage(err)}. ` +
                     "Ensure the Telegram chat is a forum supergroup with the bot as admin with can_manage_topics right.");
             }
-            lastKeepAliveSentAt = Date.now();
             try {
                 const greeting = convertMarkdown("# 🤖 Remote Copilot Ready\n\n" +
                     "Your AI assistant is online and listening.\n\n" +
@@ -570,12 +811,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const threadNote = currentThreadId !== undefined
             ? ` Thread ID: ${currentThreadId} (pass this to start_session as threadId to resume this topic later).`
             : "";
+        // Auto-bootstrap memory
+        let memoryBriefing = "";
+        try {
+            const db = getMemoryDb();
+            if (currentThreadId !== undefined) {
+                memoryBriefing = "\n\n" + assembleBootstrap(db, currentThreadId);
+            }
+        }
+        catch (e) {
+            memoryBriefing = "\n\n_Memory system unavailable._";
+        }
         return {
             content: [
                 {
                     type: "text",
                     text: `Session ${resolvedPreexisting ? "resumed" : "started"}.${threadNote}` +
                         ` Call the remote_copilot_wait_for_instructions tool next.` +
+                        memoryBriefing +
                         getReminders(currentThreadId),
                 },
             ],
@@ -612,6 +865,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 const contentBlocks = [];
                 let hasVoiceMessages = false;
+                let episodeAlreadySaved = false;
                 for (const msg of stored) {
                     // Photos: download the largest size, persist to disk, and embed as base64.
                     if (msg.message.photo && msg.message.photo.length > 0) {
@@ -699,6 +953,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                         ? `[Voice message — ${msg.message.voice.duration}s${analysisTag}, transcribed]: ${transcript}`
                                         : `[Voice message — ${msg.message.voice.duration}s${analysisTag}, transcribed]: (empty — no speech detected)`,
                                 });
+                                // Auto-save voice signature
+                                if (analysis && effectiveThreadId !== undefined) {
+                                    try {
+                                        const db = getMemoryDb();
+                                        const sessionId = `session_${sessionStartedAt}`;
+                                        const epId = saveEpisode(db, {
+                                            sessionId,
+                                            threadId: effectiveThreadId,
+                                            type: "operator_message",
+                                            modality: "voice",
+                                            content: { raw: transcript ?? "", duration: msg.message.voice.duration },
+                                            importance: 0.6,
+                                        });
+                                        saveVoiceSignature(db, {
+                                            episodeId: epId,
+                                            emotion: analysis.emotion ?? undefined,
+                                            arousal: analysis.arousal ?? undefined,
+                                            dominance: analysis.dominance ?? undefined,
+                                            valence: analysis.valence ?? undefined,
+                                            speechRate: analysis.paralinguistics?.speech_rate ?? undefined,
+                                            meanPitchHz: analysis.paralinguistics?.mean_pitch_hz ?? undefined,
+                                            pitchStdHz: analysis.paralinguistics?.pitch_std_hz ?? undefined,
+                                            jitter: analysis.paralinguistics?.jitter ?? undefined,
+                                            shimmer: analysis.paralinguistics?.shimmer ?? undefined,
+                                            hnrDb: analysis.paralinguistics?.hnr_db ?? undefined,
+                                            audioEvents: analysis.audio_events?.map(e => ({ label: e.label, confidence: e.score })),
+                                            durationSec: msg.message.voice.duration,
+                                        });
+                                        episodeAlreadySaved = true;
+                                    }
+                                    catch (_) { /* non-fatal */ }
+                                }
                             }
                             catch (err) {
                                 contentBlocks.push({
@@ -754,6 +1040,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 if (!sceneDescription && !transcript)
                                     parts.push("(no visual or audio content could be extracted)");
                                 contentBlocks.push({ type: "text", text: parts.join("\n") });
+                                // Auto-save voice signature for video notes
+                                if (analysis && effectiveThreadId !== undefined) {
+                                    try {
+                                        const db = getMemoryDb();
+                                        const sessionId = `session_${sessionStartedAt}`;
+                                        const epId = saveEpisode(db, {
+                                            sessionId,
+                                            threadId: effectiveThreadId,
+                                            type: "operator_message",
+                                            modality: "video_note",
+                                            content: { raw: transcript ?? "", scene: sceneDescription ?? "", duration: vn.duration },
+                                            importance: 0.6,
+                                        });
+                                        saveVoiceSignature(db, {
+                                            episodeId: epId,
+                                            emotion: analysis.emotion ?? undefined,
+                                            arousal: analysis.arousal ?? undefined,
+                                            dominance: analysis.dominance ?? undefined,
+                                            valence: analysis.valence ?? undefined,
+                                            speechRate: analysis.paralinguistics?.speech_rate ?? undefined,
+                                            meanPitchHz: analysis.paralinguistics?.mean_pitch_hz ?? undefined,
+                                            pitchStdHz: analysis.paralinguistics?.pitch_std_hz ?? undefined,
+                                            jitter: analysis.paralinguistics?.jitter ?? undefined,
+                                            shimmer: analysis.paralinguistics?.shimmer ?? undefined,
+                                            hnrDb: analysis.paralinguistics?.hnr_db ?? undefined,
+                                            audioEvents: analysis.audio_events?.map(e => ({ label: e.label, confidence: e.score })),
+                                            durationSec: vn.duration,
+                                        });
+                                        episodeAlreadySaved = true;
+                                    }
+                                    catch (_) { /* non-fatal */ }
+                                }
                             }
                             catch (err) {
                                 contentBlocks.push({
@@ -776,6 +1094,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
                     continue;
                 }
+                // Auto-ingest episodes (skip if a modality-specific handler already saved)
+                if (!episodeAlreadySaved) {
+                    try {
+                        const db = getMemoryDb();
+                        const sessionId = `session_${sessionStartedAt}`;
+                        if (effectiveThreadId !== undefined) {
+                            const textContent = contentBlocks
+                                .filter((b) => b.type === "text")
+                                .map(b => b.text)
+                                .join("\n")
+                                .slice(0, 2000);
+                            saveEpisode(db, {
+                                sessionId,
+                                threadId: effectiveThreadId,
+                                type: "operator_message",
+                                modality: hasVoiceMessages ? "voice" : "text",
+                                content: { raw: textContent },
+                                importance: 0.5,
+                            });
+                        }
+                    }
+                    catch (_) { /* memory write failures should never break the main flow */ }
+                }
                 return {
                     content: [
                         {
@@ -837,23 +1178,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
         }
-        // Keep-alive ping: send a periodic heartbeat to Telegram so the operator
-        // knows the session is still alive even with no activity.
-        let keepAliveSent = false;
-        if (Date.now() - lastKeepAliveSentAt >= KEEP_ALIVE_INTERVAL_MS) {
-            lastKeepAliveSentAt = Date.now();
-            try {
-                const ping = convertMarkdown(`🟢 **Session alive** — ${new Date().toLocaleString("en-GB", {
-                    day: "2-digit", month: "short", hour: "2-digit", minute: "2-digit", hour12: false,
-                })}` +
-                    ` (thread ${effectiveThreadId})`);
-                await telegram.sendMessage(TELEGRAM_CHAT_ID, ping, "MarkdownV2", effectiveThreadId);
-                keepAliveSent = true;
-            }
-            catch {
-                // Non-fatal.
-            }
-        }
         const idleMinutes = Math.round((Date.now() - lastOperatorMessageAt) / 60000);
         // Show pending scheduled tasks if any exist.
         let scheduleHint = "";
@@ -876,12 +1200,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 scheduleHint = `\n\n📋 **Pending scheduled tasks:**\n${taskList}`;
             }
         }
+        // ── Auto-consolidation during idle ──────────────────────────────────────
+        try {
+            const idleMs = Date.now() - lastOperatorMessageAt;
+            if (idleMs > 30 * 60 * 1000 && effectiveThreadId !== undefined) {
+                const db = getMemoryDb();
+                const report = await runIntelligentConsolidation(db, effectiveThreadId);
+                if (report.episodesProcessed > 0) {
+                    process.stderr.write(`[memory] Consolidation: ${report.episodesProcessed} episodes → ${report.notesCreated} notes\n`);
+                }
+            }
+        }
+        catch (_) { /* consolidation failure is non-fatal */ }
         return {
             content: [
                 {
                     type: "text",
                     text: `[Poll #${callNumber} — timeout at ${now} — elapsed ${WAIT_TIMEOUT_MINUTES}m — session uptime ${Math.round((Date.now() - sessionStartedAt) / 60000)}m — operator idle ${idleMinutes}m]` +
-                        (keepAliveSent ? ` Keep-alive ping sent.` : "") +
                         ` No new instructions received. ` +
                         `YOU MUST call remote_copilot_wait_for_instructions again RIGHT NOW to continue listening. ` +
                         `Do NOT summarize, stop, or say the session is idle. ` +
@@ -1174,6 +1509,267 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }],
         };
     }
+    // ── memory_bootstrap ────────────────────────────────────────────────────
+    if (name === "memory_bootstrap") {
+        const threadId = resolveThreadId(args);
+        if (threadId === undefined) {
+            return { content: [{ type: "text", text: "Error: No active thread. Call start_session first." + getReminders() }] };
+        }
+        try {
+            const db = getMemoryDb();
+            const briefing = assembleBootstrap(db, threadId);
+            return {
+                content: [{ type: "text", text: `## Memory Briefing\n\n${briefing}` + getReminders(threadId) }],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Memory bootstrap error: ${errorMessage(err)}` + getReminders(threadId) }] };
+        }
+    }
+    // ── memory_search ───────────────────────────────────────────────────────
+    if (name === "memory_search") {
+        const typedArgs = (args ?? {});
+        const threadId = resolveThreadId(typedArgs);
+        const query = String(typedArgs.query ?? "");
+        if (!query) {
+            return { content: [{ type: "text", text: "Error: query is required." + getReminders(threadId) }] };
+        }
+        try {
+            const db = getMemoryDb();
+            const layers = typedArgs.layers ?? ["episodic", "semantic", "procedural"];
+            const types = typedArgs.types;
+            const results = [];
+            if (layers.includes("semantic")) {
+                const notes = searchSemanticNotes(db, query, { types, maxResults: 10 });
+                if (notes.length > 0) {
+                    results.push("### Semantic Memory");
+                    for (const n of notes) {
+                        results.push(`- **[${n.type}]** ${n.content} _(conf: ${n.confidence}, id: ${n.noteId})_`);
+                    }
+                }
+            }
+            if (layers.includes("procedural")) {
+                const procs = searchProcedures(db, query, 5);
+                if (procs.length > 0) {
+                    results.push("### Procedural Memory");
+                    for (const p of procs) {
+                        results.push(`- **${p.name}** (${p.type}): ${p.description} _(success: ${Math.round(p.successRate * 100)}%, id: ${p.procedureId})_`);
+                    }
+                }
+            }
+            if (layers.includes("episodic") && threadId !== undefined) {
+                const episodes = getRecentEpisodes(db, threadId, 10);
+                const filtered = episodes.filter(ep => {
+                    const content = JSON.stringify(ep.content).toLowerCase();
+                    return query.toLowerCase().split(/\s+/).some(word => content.includes(word));
+                });
+                if (filtered.length > 0) {
+                    results.push("### Episodic Memory");
+                    for (const ep of filtered.slice(0, 5)) {
+                        const summary = typeof ep.content === "object" && ep.content !== null
+                            ? ep.content.text ?? JSON.stringify(ep.content).slice(0, 200)
+                            : String(ep.content).slice(0, 200);
+                        results.push(`- [${ep.modality}] ${summary} _(${ep.timestamp}, id: ${ep.episodeId})_`);
+                    }
+                }
+            }
+            const text = results.length > 0
+                ? results.join("\n")
+                : `No memories found for "${query}".`;
+            return { content: [{ type: "text", text: text + getReminders(threadId) }] };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Memory search error: ${errorMessage(err)}` + getReminders(threadId) }] };
+        }
+    }
+    // ── memory_save ─────────────────────────────────────────────────────────
+    if (name === "memory_save") {
+        const typedArgs = (args ?? {});
+        const threadId = resolveThreadId(typedArgs);
+        try {
+            const db = getMemoryDb();
+            const noteId = saveSemanticNote(db, {
+                type: String(typedArgs.type ?? "fact"),
+                content: String(typedArgs.content ?? ""),
+                keywords: typedArgs.keywords ?? [],
+                confidence: typeof typedArgs.confidence === "number" ? typedArgs.confidence : 0.8,
+            });
+            return {
+                content: [{ type: "text", text: `Saved semantic note: ${noteId}` + getReminders(threadId) }],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Memory save error: ${errorMessage(err)}` + getReminders(threadId) }] };
+        }
+    }
+    // ── memory_save_procedure ───────────────────────────────────────────────
+    if (name === "memory_save_procedure") {
+        const typedArgs = (args ?? {});
+        const threadId = resolveThreadId(typedArgs);
+        try {
+            const db = getMemoryDb();
+            const existingId = typedArgs.procedureId;
+            if (existingId) {
+                updateProcedure(db, existingId, {
+                    description: typedArgs.description,
+                    steps: typedArgs.steps,
+                    triggerConditions: typedArgs.triggerConditions,
+                });
+                return {
+                    content: [{ type: "text", text: `Updated procedure: ${existingId}` + getReminders(threadId) }],
+                };
+            }
+            const procId = saveProcedure(db, {
+                name: String(typedArgs.name ?? ""),
+                type: String(typedArgs.type ?? "workflow"),
+                description: String(typedArgs.description ?? ""),
+                steps: typedArgs.steps,
+                triggerConditions: typedArgs.triggerConditions,
+            });
+            return {
+                content: [{ type: "text", text: `Saved procedure: ${procId}` + getReminders(threadId) }],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Procedure save error: ${errorMessage(err)}` + getReminders(threadId) }] };
+        }
+    }
+    // ── memory_update ───────────────────────────────────────────────────────
+    if (name === "memory_update") {
+        const typedArgs = (args ?? {});
+        const threadId = resolveThreadId(typedArgs);
+        try {
+            const db = getMemoryDb();
+            const memId = String(typedArgs.memoryId ?? "");
+            const action = String(typedArgs.action ?? "update");
+            const reason = String(typedArgs.reason ?? "");
+            if (action === "supersede" && memId.startsWith("sn_")) {
+                const origRow = db.prepare("SELECT type, keywords FROM semantic_notes WHERE note_id = ?").get(memId);
+                const newId = supersedeNote(db, memId, {
+                    type: (origRow?.type ?? "fact"),
+                    content: String(typedArgs.newContent ?? ""),
+                    keywords: origRow?.keywords ? JSON.parse(origRow.keywords) : [],
+                    confidence: typeof typedArgs.newConfidence === "number" ? typedArgs.newConfidence : 0.8,
+                });
+                return {
+                    content: [{ type: "text", text: `Superseded ${memId} → ${newId} (reason: ${reason})` + getReminders(threadId) }],
+                };
+            }
+            if (memId.startsWith("sn_")) {
+                const updates = {};
+                if (typedArgs.newContent)
+                    updates.content = String(typedArgs.newContent);
+                if (typeof typedArgs.newConfidence === "number")
+                    updates.confidence = typedArgs.newConfidence;
+                updateSemanticNote(db, memId, updates);
+                return {
+                    content: [{ type: "text", text: `Updated note ${memId} (reason: ${reason})` + getReminders(threadId) }],
+                };
+            }
+            if (memId.startsWith("pr_")) {
+                const updates = {};
+                if (typedArgs.newContent)
+                    updates.description = String(typedArgs.newContent);
+                if (typeof typedArgs.newConfidence === "number")
+                    updates.confidence = typedArgs.newConfidence;
+                updateProcedure(db, memId, updates);
+                return {
+                    content: [{ type: "text", text: `Updated procedure ${memId} (reason: ${reason})` + getReminders(threadId) }],
+                };
+            }
+            return { content: [{ type: "text", text: `Unknown memory ID format: ${memId}` + getReminders(threadId) }] };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Memory update error: ${errorMessage(err)}` + getReminders(threadId) }] };
+        }
+    }
+    // ── memory_consolidate ──────────────────────────────────────────────────
+    if (name === "memory_consolidate") {
+        const typedArgs = (args ?? {});
+        const threadId = resolveThreadId(typedArgs);
+        if (threadId === undefined) {
+            return { content: [{ type: "text", text: "Error: No active thread." + getReminders() }] };
+        }
+        try {
+            const db = getMemoryDb();
+            const report = await runIntelligentConsolidation(db, threadId);
+            if (report.episodesProcessed === 0) {
+                return {
+                    content: [{ type: "text", text: "No unconsolidated episodes. Memory is up to date." + getReminders(threadId) }],
+                };
+            }
+            const reportLines = [
+                "## Consolidation Report",
+                `- Episodes processed: ${report.episodesProcessed}`,
+                `- Notes created: ${report.notesCreated}`,
+                `- Duration: ${report.durationMs}ms`,
+            ];
+            if (report.details.length > 0) {
+                reportLines.push("", "### Extracted Knowledge");
+                for (const d of report.details) {
+                    reportLines.push(`- ${d}`);
+                }
+            }
+            return { content: [{ type: "text", text: reportLines.join("\n") + getReminders(threadId) }] };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Consolidation error: ${errorMessage(err)}` + getReminders(threadId) }] };
+        }
+    }
+    // ── memory_status ───────────────────────────────────────────────────────
+    if (name === "memory_status") {
+        const typedArgs = (args ?? {});
+        const threadId = resolveThreadId(typedArgs);
+        if (threadId === undefined) {
+            return { content: [{ type: "text", text: "Error: No active thread." + getReminders() }] };
+        }
+        try {
+            const db = getMemoryDb();
+            const status = getMemoryStatus(db, threadId);
+            const topics = getTopicIndex(db);
+            const lines = [
+                "## Memory Status",
+                `- Episodes: ${status.totalEpisodes} (${status.unconsolidatedEpisodes} unconsolidated)`,
+                `- Semantic notes: ${status.totalSemanticNotes}`,
+                `- Procedures: ${status.totalProcedures}`,
+                `- Voice signatures: ${status.totalVoiceSignatures}`,
+                `- Last consolidation: ${status.lastConsolidation ?? "never"}`,
+                `- DB size: ${(status.dbSizeBytes / 1024).toFixed(1)} KB`,
+            ];
+            if (topics.length > 0) {
+                lines.push("", "**Topics:**");
+                for (const t of topics.slice(0, 15)) {
+                    lines.push(`- ${t.topic} (${t.semanticCount} notes, ${t.proceduralCount} procs, conf: ${t.avgConfidence.toFixed(2)})`);
+                }
+            }
+            return { content: [{ type: "text", text: lines.join("\n") + getReminders(threadId) }] };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Memory status error: ${errorMessage(err)}` + getReminders(threadId) }] };
+        }
+    }
+    // ── memory_forget ───────────────────────────────────────────────────────
+    if (name === "memory_forget") {
+        const typedArgs = (args ?? {});
+        const threadId = resolveThreadId(typedArgs);
+        try {
+            const db = getMemoryDb();
+            const memId = String(typedArgs.memoryId ?? "");
+            const reason = String(typedArgs.reason ?? "");
+            const result = forgetMemory(db, memId, reason);
+            if (!result.deleted) {
+                return {
+                    content: [{ type: "text", text: `Memory ${memId} not found (layer: ${result.layer}). Nothing was deleted.` + getReminders(threadId) }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Forgot ${result.layer} memory ${memId} (reason: ${reason})` + getReminders(threadId) }],
+            };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Memory forget error: ${errorMessage(err)}` + getReminders(threadId) }] };
+        }
+    }
     // Unknown tool
     return errorResult(`Unknown tool: ${name}`);
 });