twinclaw 1.4.1 → 1.5.0

package/dist/core/context-assembly.js

@@ -1,9 +1,51 @@
 import fs from 'fs/promises';
 import path from 'path';
+import os from 'node:os';
 import { getIdentityDir } from '../config/workspace.js';
+import { getConfigValue } from '../config/json-config.js';
+/** Build a short runtime context block (OS, time, model). */
+function buildRuntimeContext() {
+    const now = new Date();
+    const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const formattedTime = now.toLocaleString('en-US', {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        timeZoneName: 'short',
+    });
+    const currentModel = getConfigValue('PRIMARY_MODEL') ?? 'unknown';
+    const platform = os.platform();
+    const hostname = os.hostname();
+    const arch = os.arch();
+    const lines = [
+        `- **Current Date & Time:** ${formattedTime} (${timezone})`,
+        `- **Host:** ${hostname}`,
+        `- **OS:** ${platform} (${arch})`,
+        `- **Shell:** ${platform === 'win32' ? 'PowerShell' : 'bash'}`,
+        `- **Primary Model:** ${currentModel}`,
+    ];
+    return lines.join('\n');
+}
+/**
+ * Known messaging tool names. When the model calls any of these,
+ * the assistant's text response should be suppressed to avoid duplicates.
+ */
+export const MESSAGING_TOOL_NAMES = new Set([
+    'send_telegram_message',
+    'send_whatsapp_message',
+    'send_telegram_photo',
+    'send_telegram_document',
+    'send_whatsapp_image',
+    'send_whatsapp_document',
+]);
 export async function assembleContext(additionalRuntimeContext = '') {
     let soul = '';
     let identity = '';
+    let tools = '';
     let user = '';
     const identityDir = getIdentityDir();
     const readOptionalFile = async (fileName) => {
@@ -23,7 +65,9 @@ export async function assembleContext(additionalRuntimeContext = '') {
     };
     soul = await readOptionalFile('soul.md');
     identity = await readOptionalFile('identity.md');
+    tools = await readOptionalFile('tools.md');
     user = await readOptionalFile('user.md');
+    const runtimeBlock = buildRuntimeContext();
     const compiled = `
 You are TwinClaw. Follow your core directives exactly.
 
@@ -31,6 +75,11 @@ ${soul ? `### CORE SOUL & DIRECTIVES\n${soul}` : ''}
 
 ${identity ? `### IDENTITY & PERSONA\n${identity}` : ''}
 
+${tools ? `### TOOL USAGE GUIDE\n${tools}` : ''}
+
+### RUNTIME ENVIRONMENT
+${runtimeBlock}
+
 ${user ? `### USER PREFERENCES\n${user}` : ''}
 
 ${additionalRuntimeContext ? `### ADDITIONAL CONTEXT (RAG MEMORY)\n${additionalRuntimeContext}` : ''}

package/dist/core/gateway.js

@@ -6,14 +6,17 @@ import { ModelRouter } from '../services/model-router.js';
 import { getIdentityDir } from '../config/workspace.js';
 import { indexConversationTurn, retrieveEvidenceAwareMemoryContext, } from '../services/semantic-memory.js';
 import { OrchestrationService } from '../services/orchestration-service.js';
-import { assembleContext } from './context-assembly.js';
+import { assembleContext, MESSAGING_TOOL_NAMES } from './context-assembly.js';
 import { LaneExecutor } from './lane-executor.js';
 import { PolicyEngine } from '../services/policy-engine.js';
 import { logThought } from '../utils/logger.js';
 import { ContextLifecycleOrchestrator } from '../services/context-lifecycle.js';
+import { extractAndStoreMemory } from '../services/memory-extraction.js';
 import { createSelfSetupAgent } from '../agents/self-setup-agent.js';
 const DEFAULT_MAX_TOOL_ROUNDS = 6;
 const DEFAULT_IDENTICAL_TOOL_CALL_LIMIT = 3;
+const DEFAULT_AGENT_TIMEOUT_MS = 300_000; // 5 minutes
+const NO_REPLY_TOKEN = 'NO_REPLY';
 const DEFAULT_DELEGATION_MIN_SCORE = 2;
 const DELEGATION_KEYWORDS = [
     'complex',
@@ -91,6 +94,8 @@ export class Gateway {
     #enableDelegation;
     #delegationMinScore;
     #contextLifecycle;
+    #agentTimeoutMs;
+    #sessionLocks = new Map();
     #toolPolicy;
     #degradationCounts = new Map();
     #selfSetupAgents = new Map();
@@ -111,6 +116,7 @@ export class Gateway {
         this.#enableDelegation = options.enableDelegation ?? true;
         this.#delegationMinScore = Math.max(1, Number(options.delegationMinScore ?? DEFAULT_DELEGATION_MIN_SCORE));
         this.#contextLifecycle = new ContextLifecycleOrchestrator(options.contextBudgetConfig);
+        this.#agentTimeoutMs = options.agentTimeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS;
         this.#toolPolicy = {
             allow: normalizeToolSelectors(options.toolPolicy?.allow),
             deny: normalizeToolSelectors(options.toolPolicy?.deny),
@@ -247,7 +253,43 @@ export class Gateway {
             ...(setupPrompt ? [{ role: 'system', content: setupPrompt }] : []),
             { role: 'user', content: normalizedText },
         ];
-        return this.#runConversationLoop(sessionId, messages);
+        // Session write lock: serialize processText calls per session
+        const existingLock = this.#sessionLocks.get(sessionId) ?? Promise.resolve('');
+        const runLocked = existingLock.then(async () => {
+            return this.#runConversationLoopWithTimeout(sessionId, messages);
+        }).catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[Gateway] Session ${sessionId} error: ${message}`);
+            return `Error: ${message}`;
+        });
+        this.#sessionLocks.set(sessionId, runLocked);
+        // Clean up the lock reference once done
+        void runLocked.finally(() => {
+            if (this.#sessionLocks.get(sessionId) === runLocked) {
+                this.#sessionLocks.delete(sessionId);
+            }
+        });
+        return runLocked;
+    }
+    /** Wrap the conversation loop with a hard timeout + memory extraction. */
+    async #runConversationLoopWithTimeout(sessionId, messages) {
+        const loop = this.#agentTimeoutMs > 0
+            ? Promise.race([
+                this.#runConversationLoop(sessionId, messages),
+                new Promise((_, reject) => {
+                    setTimeout(() => {
+                        reject(new Error(`Agent run timed out after ${Math.round(this.#agentTimeoutMs / 1000)}s. Session: ${sessionId}`));
+                    }, this.#agentTimeoutMs);
+                }),
+            ])
+            : this.#runConversationLoop(sessionId, messages);
+        const result = await loop;
+        // Fire-and-forget memory extraction after successful conversation
+        void extractAndStoreMemory(sessionId, messages, this.#router).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[Gateway] Memory extraction failed for ${sessionId}: ${msg}`);
+        });
+        return result;
     }
     async #runConversationLoop(sessionId, messages) {
         // Refresh tools at the start of each loop to catch newly connected MCP servers
@@ -264,6 +306,24 @@ export class Gateway {
                 tool_calls: assistantMessage.tool_calls,
             });
             if (!assistantMessage.tool_calls || assistantMessage.tool_calls.length === 0) {
+                // Empty response guard: detect bare "Done." or trivially empty responses
+                // when the model should have used tools but didn't
+                const trimmedContent = assistantContent.trim().toLowerCase();
+                const isEmptyResponse = !trimmedContent ||
+                    trimmedContent === 'done.' ||
+                    trimmedContent === 'done' ||
+                    trimmedContent === 'ok.' ||
+                    trimmedContent === 'ok';
+                if (isEmptyResponse && round === 0 && this.#tools.length > 0) {
+                    // First round, tools available, but model gave empty/trivial response.
+                    // Nudge it to actually use tools instead of giving up.
+                    console.warn(`[Gateway] Empty response guard triggered: "${assistantContent}" in round ${round}. Nudging model to use tools.`);
+                    messages.push({
+                        role: 'system',
+                        content: 'Your response was empty or trivial. You have tools available — use them to actually perform the task. Do NOT respond with just "Done." unless you have completed concrete actions and shown their results.',
+                    });
+                    continue;
+                }
                 // L6: Index the final assistant response and the user's initial prompt together
                 // this is moved here from the outer processText method
                 const lastUserMsg = [...messages].reverse().find((m) => m.role === 'user');
@@ -273,7 +333,9 @@ export class Gateway {
                     });
                 }
                 await this.#persistTurn(sessionId, 'assistant', assistantContent || '[assistant finished]');
-                return assistantContent || 'Done.';
+                // Filter NO_REPLY tokens from final output
+                const finalContent = assistantContent.replace(NO_REPLY_TOKEN, '').trim();
+                return finalContent || 'Done.';
             }
             await this.#persistTurn(sessionId, 'assistant', assistantContent || '[assistant returned tool calls]');
             const pattern = this.#buildToolCallSignature(assistantMessage.tool_calls);
@@ -291,10 +353,23 @@ export class Gateway {
                 return `${diagnostic} Stopping execution to prevent an infinite loop.`;
             }
             const toolResults = await this.#laneExecutor.executeToolCalls(assistantMessage, sessionId, this.#policyEngine);
+            // Track if a messaging tool was used in this round
+            const calledToolNames = (assistantMessage.tool_calls ?? []).map((tc) => tc.function.name);
+            const usedMessagingTool = calledToolNames.some((name) => MESSAGING_TOOL_NAMES.has(name));
             for (const toolMessage of toolResults) {
                 messages.push(toolMessage);
                 await this.#persistTurn(sessionId, 'tool', toolMessage.content ?? '');
             }
+            // NO_REPLY suppression: if a messaging tool was called, inject a
+            // hint telling the model not to also produce a text reply.
+            if (usedMessagingTool) {
+                messages.push({
+                    role: 'system',
+                    content: 'You already sent a message via a messaging tool. ' +
+                        'Do NOT also produce a text reply confirming it — that would duplicate the message. ' +
+                        `If you have nothing else to do, respond with exactly: ${NO_REPLY_TOKEN}`,
+                });
+            }
             // Compact messages to fit within budget after tool results are added
             this.#compactConversationMessages(messages);
         }
@@ -514,58 +589,58 @@ export class Gateway {
         return content;
     }
     #getPersonaSetupPrompt() {
-        return `
-## First Interaction - Persona Setup
-
-This appears to be your first conversation with me. Before we dive into anything, I'd love to take a few minutes to get to know you better so I can be actually helpful (not just generic AI helpful).
-
-Think of this as a quick chat where I learn what makes you tick.
-
-Start by introducing yourself warmly and asking me 2-3 questions about:
-- What do you do? (Role, industry, company)
-- What are you working on right now?
-- How do you like information presented? (Brief vs detailed, casual vs formal)
-- What frustrates you about AI assistants?
-- What platforms or tools do you use that I might integrate with?
-
-After I respond, synthesize what you learn and create/update the user.md file in my identity directory with:
-- User name and how they'd like to be addressed
-- Role/industry/company
-- Communication preferences
-- Current projects or goals
-- Tools and platforms they use
-- Anything they want me to know or avoid
-
-The user.md file should follow this format:
-
-\`\`\`markdown
-# User Profile
-
-## Basic Info
-- **Name:** [what they want to be called]
-- **Role:** [job title/position]
-- **Company/Context:** [where they work/study]
-- **Technical Level:** [beginner/intermediate/expert]
-
-## Communication Preferences
-- **Formality:** [casual/professional/mix]
-- **Detail Level:** [brief/comprehensive/contextual]
-- **Tone:** [direct/exploratory/friendly]
-
-## Current Context
-- **Active Projects:** [what they're working on]
-- **Goals:** [what they're trying to achieve]
-- **Tools:** [daily tech stack, platforms]
-
-## Important to Remember
-- [things they explicitly mention caring about]
-- [frustrations they mention]
-
-## Learned Facts
-- [interesting facts from our conversation]
-\`\`\`
-
-Tell me once you've saved this. Then we'll be ready to dive in!
+        return `
+## First Interaction - Persona Setup
+
+This appears to be your first conversation with me. Before we dive into anything, I'd love to take a few minutes to get to know you better so I can be actually helpful (not just generic AI helpful).
+
+Think of this as a quick chat where I learn what makes you tick.
+
+Start by introducing yourself warmly and asking me 2-3 questions about:
+- What do you do? (Role, industry, company)
+- What are you working on right now?
+- How do you like information presented? (Brief vs detailed, casual vs formal)
+- What frustrates you about AI assistants?
+- What platforms or tools do you use that I might integrate with?
+
+After I respond, synthesize what you learn and create/update the user.md file in my identity directory with:
+- User name and how they'd like to be addressed
+- Role/industry/company
+- Communication preferences
+- Current projects or goals
+- Tools and platforms they use
+- Anything they want me to know or avoid
+
+The user.md file should follow this format:
+
+\`\`\`markdown
+# User Profile
+
+## Basic Info
+- **Name:** [what they want to be called]
+- **Role:** [job title/position]
+- **Company/Context:** [where they work/study]
+- **Technical Level:** [beginner/intermediate/expert]
+
+## Communication Preferences
+- **Formality:** [casual/professional/mix]
+- **Detail Level:** [brief/comprehensive/contextual]
+- **Tone:** [direct/exploratory/friendly]
+
+## Current Context
+- **Active Projects:** [what they're working on]
+- **Goals:** [what they're trying to achieve]
+- **Tools:** [daily tech stack, platforms]
+
+## Important to Remember
+- [things they explicitly mention caring about]
+- [frustrations they mention]
+
+## Learned Facts
+- [interesting facts from our conversation]
+\`\`\`
+
+Tell me once you've saved this. Then we'll be ready to dive in!
 `;
     }
 }

package/dist/core/lane-executor.js

@@ -1,6 +1,7 @@
 import { logToolCall, scrubSensitiveText } from '../utils/logger.js';
 import { getLearningSystem } from '../services/learning-system.js';
 import { getSelfHealingService } from '../services/self-healing.js';
+import { getToolEventBus } from './tool-events.js';
 /** Convert a Skill (from the registry) into the internal Tool format used by LaneExecutor. */
 function skillToTool(skill) {
     return {
@@ -18,6 +19,17 @@ function skillToTool(skill) {
         },
     };
 }
+/** Max characters for a single tool result to prevent context budget exhaustion. */
+const MAX_TOOL_RESULT_CHARS = 16_000;
+/** Truncate oversized tool results to prevent context budget exhaustion. */
+function sanitizeToolResult(content, toolName) {
+    if (content.length <= MAX_TOOL_RESULT_CHARS) {
+        return content;
+    }
+    const truncated = content.slice(0, MAX_TOOL_RESULT_CHARS);
+    console.warn(`[LaneExecutor] Tool '${toolName}' result truncated: ${content.length} -> ${MAX_TOOL_RESULT_CHARS} chars`);
+    return `${truncated}\n\n[... truncated ${content.length - MAX_TOOL_RESULT_CHARS} characters. Result was too large for context window.]`;
+}
 export class LaneExecutor {
     tools = new Map();
     constructor(tools = []) {
@@ -51,16 +63,6 @@ export class LaneExecutor {
     syncFromRegistry(registry) {
         this.syncSkills(registry.list());
     }
-    parseArguments(args) {
-        try {
-            return JSON.parse(args);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            console.warn(`[LaneExecutor] Failed to parse arguments: ${scrubSensitiveText(args)} (${scrubSensitiveText(message)})`);
-            return {};
-        }
-    }
     async executeToolCalls(message, sessionId, policyEngine) {
         if (!message.tool_calls || message.tool_calls.length === 0) {
             return [];
@@ -69,10 +71,24 @@ export class LaneExecutor {
         // Lane-Based Execution: Execute tools serially in an await loop
         for (const toolCall of message.tool_calls) {
             const toolName = toolCall.function.name;
-            const args = this.parseArguments(toolCall.function.arguments);
-            const tool = this.tools.get(toolName);
+            let args;
             let content = '';
-            if (!tool) {
+            let parsingFailed = false;
+            try {
+                args = JSON.parse(toolCall.function.arguments);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.warn(`[LaneExecutor] Failed to parse arguments for ${toolName}: ${scrubSensitiveText(errorMessage)}`);
+                content = `Error: Invalid JSON arguments for tool '${toolName}'. Fix syntax.`;
+                parsingFailed = true;
+                args = {};
+            }
+            const tool = this.tools.get(toolName);
+            if (parsingFailed) {
+                await logToolCall(toolName, args, content);
+            }
+            else if (!tool) {
                 console.warn(`[LaneExecutor] Tool not found: ${toolName}`);
                 content = `Error: Tool '${toolName}' is not registered or unavailable.`;
                 await logToolCall(toolName, args, content);
@@ -110,12 +126,31 @@ export class LaneExecutor {
                     await logToolCall(toolName, args, content);
                 }
                 if (allowed) {
+                    const startTime = Date.now();
+                    const eventBus = getToolEventBus();
+                    eventBus.emitStart({
+                        sessionId,
+                        toolName,
+                        toolCallId: toolCall.id,
+                        args,
+                        timestamp: startTime,
+                    });
                     try {
                         console.log(`[LaneExecutor] Executing ${toolName} with args: ${scrubSensitiveText(JSON.stringify(args))}`);
                         const result = await tool.execute(args);
                         content = typeof result === 'string' ? result : JSON.stringify(result);
                         await logToolCall(toolName, args, content);
                         const success = !content.startsWith('Error');
+                        const durationMs = Date.now() - startTime;
+                        eventBus.emitEnd({
+                            sessionId,
+                            toolName,
+                            toolCallId: toolCall.id,
+                            success,
+                            durationMs,
+                            resultPreview: content.slice(0, 200),
+                            timestamp: Date.now(),
+                        });
                         await this.#recordSkillExecution(toolName, args, success, content);
                     }
                     catch (error) {
@@ -124,6 +159,15 @@ export class LaneExecutor {
                         console.error(`[LaneExecutor] Tool ${toolName} failed: ${sanitizedMessage}`);
                         content = `Error executing tool: ${sanitizedMessage}`;
                         await logToolCall(toolName, args, content);
+                        const durationMs = Date.now() - startTime;
+                        eventBus.emitError({
+                            sessionId,
+                            toolName,
+                            toolCallId: toolCall.id,
+                            error: sanitizedMessage,
+                            durationMs,
+                            timestamp: Date.now(),
+                        });
                         await this.#recordSkillExecution(toolName, args, false, sanitizedMessage);
                     }
                 }
@@ -132,7 +176,7 @@ export class LaneExecutor {
                 role: 'tool',
                 tool_call_id: toolCall.id,
                 name: toolName,
-                content: content,
+                content: sanitizeToolResult(content, toolName),
             });
         }
         return results;

package/dist/core/tool-events.js

@@ -0,0 +1,53 @@
+import { EventEmitter } from 'node:events';
+// ── Typed EventEmitter ──────────────────────────────────────────────────────
+class ToolEventBus extends EventEmitter {
+    emitStart(event) {
+        this.emit('tool:start', event);
+    }
+    emitEnd(event) {
+        this.emit('tool:end', event);
+    }
+    emitError(event) {
+        this.emit('tool:error', event);
+    }
+    onStart(listener) {
+        return this.on('tool:start', listener);
+    }
+    onEnd(listener) {
+        return this.on('tool:end', listener);
+    }
+    onError(listener) {
+        return this.on('tool:error', listener);
+    }
+}
+/** Singleton tool event bus — shared between LaneExecutor (producer) and Dispatcher (consumer). */
+let instance = null;
+export function getToolEventBus() {
+    if (!instance) {
+        instance = new ToolEventBus();
+        // Avoid memory-leak warnings for many listeners (one per platform adapter).
+        instance.setMaxListeners(20);
+    }
+    return instance;
+}
+/** Human-friendly tool name for status messages. */
+export function humanizeToolName(toolName) {
+    const map = {
+        'read_file': '📄 Reading file',
+        'write_file': '✏️ Writing file',
+        'edit_file': '✏️ Editing file',
+        'list_directory': '📂 Listing directory',
+        'directory_tree': '📂 Browsing directory tree',
+        'search_files': '🔍 Searching files',
+        'exec': '⚡ Running command',
+        'web_search': '🌐 Searching the web',
+        'web_fetch': '🌐 Fetching webpage',
+        'create_entities': '🧠 Saving to memory',
+        'search_nodes': '🧠 Searching memory',
+        'create_relations': '🧠 Connecting knowledge',
+        'send_telegram_message': '💬 Sending Telegram message',
+        'send_whatsapp_message': '💬 Sending WhatsApp message',
+        'sequentialthinking': '🤔 Thinking step-by-step',
+    };
+    return map[toolName] ?? `🔧 Using ${toolName}`;
+}

package/dist/interfaces/dispatcher.js

@@ -4,6 +4,7 @@ import { getDmPairingService, normalizePairingSenderId, } from '../services/dm-p
 import { InboundDebounceService } from '../services/inbound-debounce.js';
 import { EmbeddedBlockChunker } from '../services/block-chunker.js';
 import { getConfigValue } from '../config/json-config.js';
+import { getToolEventBus, humanizeToolName } from '../core/tool-events.js';
 function parseIntConfig(key, fallback) {
     const value = getConfigValue(key);
     if (value === undefined || value === null || value === '') {
@@ -59,6 +60,8 @@ export class Dispatcher {
     #debounce;
     #chunker;
     #humanDelayMs;
+    /** Maps sessionId → { platform, chatId } for routing tool events to the correct chat. */
+    #activeSessions = new Map();
     constructor(telegram, whatsapp, stt, tts, gateway, queue, options = {}) {
         this.#telegram = telegram;
         this.#whatsapp = whatsapp;
@@ -98,6 +101,8 @@ export class Dispatcher {
             this.#telegram.onMessage = (msg) => this.#handleDebounced(msg);
         if (this.#whatsapp)
             this.#whatsapp.onMessage = (msg) => this.#handleDebounced(msg);
+        // Subscribe to tool events for real-time status messages
+        this.#subscribeToToolEvents();
     }
     /** Expose the queue service for reliability and dead-letter controls. */
     get queue() {
@@ -127,8 +132,16 @@ export class Dispatcher {
                 return;
             }
             const normalized = await this.#resolveAudio(message);
-            const responseText = await this.#gateway.processMessage(normalized);
-            await this.#dispatch(normalized, responseText);
+            // Track session so tool events can route status messages to this chat
+            const sessionId = `${normalized.platform}:${normalized.senderId}`;
+            this.trackSession(sessionId, normalized.platform, normalized.chatId);
+            try {
+                const responseText = await this.#gateway.processMessage(normalized);
+                await this.#dispatch(normalized, responseText);
+            }
+            finally {
+                this.untrackSession(sessionId);
+            }
         }
         catch (err) {
             const errorMessage = err instanceof Error ? err.message : String(err);
@@ -294,7 +307,36 @@ export class Dispatcher {
     /** Tear down all active interface adapters cleanly. */
     shutdown() {
         this.#debounce.clear();
+        this.#activeSessions.clear();
         this.#telegram?.stop();
         this.#whatsapp?.stop();
     }
+    // ── Tool Event Streaming ────────────────────────────────────────────────────
+    /** Subscribe to LaneExecutor tool events and send status messages to the active chat. */
+    #subscribeToToolEvents() {
+        const eventBus = getToolEventBus();
+        eventBus.onStart((event) => {
+            const target = this.#activeSessions.get(event.sessionId);
+            if (!target)
+                return;
+            const statusText = `${humanizeToolName(event.toolName)}...`;
+            // Fire-and-forget status message — don't await to avoid blocking execution
+            this.#queue.enqueue(target.platform, target.chatId, statusText);
+        });
+        eventBus.onError((event) => {
+            const target = this.#activeSessions.get(event.sessionId);
+            if (!target)
+                return;
+            const statusText = `⚠️ ${event.toolName} failed (${Math.round(event.durationMs / 1000)}s): ${event.error.slice(0, 120)}`;
+            this.#queue.enqueue(target.platform, target.chatId, statusText);
+        });
+    }
+    /** Register the active session's routing info so tool events reach the right chat. */
+    trackSession(sessionId, platform, chatId) {
+        this.#activeSessions.set(sessionId, { platform, chatId });
+    }
+    /** Remove session tracking after processing completes. */
+    untrackSession(sessionId) {
+        this.#activeSessions.delete(sessionId);
+    }
 }

package/dist/services/memory-extraction.js

@@ -0,0 +1,111 @@
+import { saveMemoryFact } from './db.js';
+import { logThought } from '../utils/logger.js';
+/**
+ * Extract persistent facts from a completed conversation and store them in the
+ * BM25 FTS5 memory table. Uses a lightweight model call to distill key facts.
+ *
+ * This runs as a fire-and-forget background task after each conversation loop.
+ */
+export async function extractAndStoreMemory(sessionId, messages, router) {
+    try {
+        // Only extract from conversations with meaningful content
+        const userMessages = messages.filter((m) => m.role === 'user');
+        const assistantMessages = messages.filter((m) => m.role === 'assistant');
+        if (userMessages.length === 0 || assistantMessages.length === 0) {
+            return 0;
+        }
+        // Build a compact summary of the conversation for extraction
+        const conversationSummary = buildConversationSummary(messages);
+        if (conversationSummary.length < 50) {
+            // Conversation too short to extract meaningful facts from
+            return 0;
+        }
+        const extractionMessages = [
+            {
+                role: 'system',
+                content: EXTRACTION_PROMPT,
+            },
+            {
+                role: 'user',
+                content: conversationSummary,
+            },
+        ];
+        // Use model to extract facts — no tools, lightweight call
+        const response = await router.createChatCompletion(extractionMessages, [], // no tools
+        { sessionId: `memory-extract:${sessionId}` });
+        const rawContent = response.content?.trim() ?? '';
+        const facts = parseExtractedFacts(rawContent);
+        if (facts.length === 0) {
+            return 0;
+        }
+        // Store each fact in the FTS5 table
+        let stored = 0;
+        for (const fact of facts) {
+            const taggedFact = `MEMORY: ${fact.fact}${fact.tags.length > 0 ? ` [${fact.tags.join(', ')}]` : ''}`;
+            saveMemoryFact(sessionId, taggedFact);
+            stored++;
+        }
+        void logThought(`[MemoryExtraction] Extracted and stored ${stored} facts from session ${sessionId}`);
+        return stored;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[MemoryExtraction] Failed for session ${sessionId}: ${message}`);
+        return 0;
+    }
+}
+// ── Extraction Prompt ──────────────────────────────────────────────────────────
+const EXTRACTION_PROMPT = `You are a memory extraction agent. Your job is to extract 0-5 key facts from a conversation that are worth remembering long-term.
+
+Rules:
+- Only extract genuinely useful, persistent facts (preferences, names, decisions, technical context).
+- Do NOT extract transient information (greetings, "thank you", temporary states).
+- Do NOT extract information the user explicitly marked as private or temporary.
+- Each fact should be self-contained and understandable without the conversation context.
+- Tags should be 1-3 short keywords for categorization.
+
+Respond with ONLY a JSON array. No markdown, no explanation, no code fences.
+Format: [{"fact": "...", "tags": ["..."]}]
+Return [] if nothing notable or the conversation is trivial.`;
+/** Build a compact summary of the conversation for the extraction model. */
+function buildConversationSummary(messages) {
+    const relevant = messages.filter((m) => m.role === 'user' || m.role === 'assistant');
+    // Cap at last 10 messages to keep context small
+    const recent = relevant.slice(-10);
+    return recent
+        .map((m) => `${m.role.toUpperCase()}: ${(m.content ?? '').slice(0, 500)}`)
+        .join('\n\n');
+}
+/** Parse the model's extracted facts from JSON, with lenient error handling. */
+function parseExtractedFacts(raw) {
+    if (!raw || raw === '[]') {
+        return [];
+    }
+    // Strip markdown code fences if present
+    const cleaned = raw
+        .replace(/^```(?:json)?\s*/i, '')
+        .replace(/\s*```$/i, '')
+        .trim();
+    try {
+        const parsed = JSON.parse(cleaned);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed
+            .filter((item) => typeof item === 'object' &&
+            item !== null &&
+            typeof item.fact === 'string' &&
+            item.fact !== '')
+            .map((item) => ({
+            fact: String(item.fact).slice(0, 500),
+            tags: Array.isArray(item.tags)
+                ? item.tags.filter((t) => typeof t === 'string').slice(0, 5)
+                : [],
+        }))
+            .slice(0, 5); // Hard cap at 5 facts per session
+    }
+    catch {
+        console.warn(`[MemoryExtraction] Failed to parse JSON: ${cleaned.slice(0, 100)}`);
+        return [];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twinclaw",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Eagle-eyed agentic AI gateway with multi-modal hooks and proactive memory.",
   "main": "dist/index.js",
   "bin": {