twinclaw 1.3.2 → 1.4.1

package/dist/interfaces/whatsapp_handler.js

@@ -6,20 +6,11 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { logThought } from '../utils/logger.js';
-import { getConfigValue, readConfig, writeConfig } from '../config/json-config.js';
-import { getModelCatalogService } from '../services/model-catalog-service.js';
+import { getWorkspaceDir } from '../config/workspace.js';
+import { getConfigValue } from '../config/json-config.js';
 const { Client, LocalAuth, MessageMedia } = WAWebJS;
 const RATE_LIMIT_MS = 1500;
-const WHATSAPP_COMMANDS = [
-    { cmd: '/start', desc: 'Show welcome message and menu' },
-    { cmd: '/help', desc: 'Show all commands' },
-    { cmd: '/menu', desc: 'Show menu' },
-    { cmd: '/status', desc: 'Show gateway status' },
-    { cmd: '/models', desc: 'Show configured models' },
-    { cmd: '/keys', desc: 'Show API keys status' },
-    { cmd: '/channel', desc: 'Show channel status' },
-    { cmd: '/clear', desc: 'Clear conversation' },
-];
+import { CommandRouter } from '../core/command-router.js';
 /**
  * Create MessageMedia from URL
  */
@@ -39,7 +30,7 @@ async function MessageMediaFromUrl(url, caption, mimeType, filename) {
 export class WhatsAppHandler {
     #client;
     #lastMessageAt = 0;
-    #authDataPath = path.resolve('memory', 'whatsapp_auth');
+    #authDataPath = path.join(getWorkspaceDir(), 'memory', 'whatsapp_auth');
     #pairingBroadcastEnabled = getConfigValue('WHATSAPP_ENABLE_PAIRING_BROADCAST') === 'true';
     // Session recovery
     #connectionState = 'disconnected';
@@ -72,125 +63,9 @@ export class WhatsAppHandler {
     }
     // ── Command Handlers ─────────────────────────────────────────────────────────
     async handleCommand(chatId, command, fullText) {
-        const parts = command.toLowerCase().trim().split(' ');
-        const cmd = parts[0];
-        const args = fullText ? fullText.substring(cmd.length).trim() : '';
-        switch (cmd) {
-            case '/start':
-            case '/menu':
-                const menuText = `🎯 *TwinClaw Menu*
-
-${WHATSAPP_COMMANDS.map(c => `${c.cmd} - ${c.desc}`).join('\n')}
-
-_How can I help you today?_
-`;
-                await this.sendText(chatId, menuText);
-                break;
-            case '/help':
-                await this.sendText(chatId, `📋 *Available Commands:*
-
-${WHATSAPP_COMMANDS.map(c => `${c.cmd} - ${c.desc}`).join('\n')}
-
-_Just send me a message and I'll respond!_
-`);
-                break;
-            case '/status':
-                await this.sendText(chatId, `✅ *Gateway Status:*
-
-• Status: Running
-• Platform: WhatsApp
-• Mode: AI Assistant
-
-_All systems operational_
-`);
-                break;
-            case '/models':
-            case '/model':
-                if (args.startsWith('list')) {
-                    const catalog = getModelCatalogService().getAllModels();
-                    const config = await readConfig();
-                    const currentPrimary = config.models.primaryModel || 'not set';
-                    let modelList = `📦 *Available Models*\n\nCurrent: ${currentPrimary}\n\n`;
-                    const providerGroups = new Map();
-                    for (const model of catalog) {
-                        const models = providerGroups.get(model.provider) || [];
-                        models.push(model);
-                        providerGroups.set(model.provider, models);
-                    }
-                    let num = 1;
-                    for (const [provider, models] of providerGroups) {
-                        modelList += `*${provider.toUpperCase()}:*\n`;
-                        for (const m of models.slice(0, 5)) {
-                            const isCurrent = m.model === currentPrimary || m.id === currentPrimary;
-                            modelList += `${num}. ${m.name}${isCurrent ? ' ✅' : ''}\n`;
-                            num++;
-                        }
-                        if (models.length > 5)
-                            modelList += `  ...and ${models.length - 5} more\n`;
-                        modelList += '\n';
-                    }
-                    modelList += '_To switch: /model set <number>_';
-                    await this.sendText(chatId, modelList);
-                }
-                else if (args.startsWith('set ') && args.length > 4) {
-                    const modelIdOrNum = args.substring(4).trim();
-                    const catalog = getModelCatalogService().getAllModels();
-                    let newModelId = modelIdOrNum;
-                    if (/^\d+$/.test(modelIdOrNum)) {
-                        const idx = parseInt(modelIdOrNum, 10) - 1;
-                        if (idx >= 0 && idx < catalog.length) {
-                            newModelId = `${catalog[idx].provider}/${catalog[idx].model}`;
-                        }
-                        else {
-                            await this.sendText(chatId, '❌ Invalid model number. Use /model list to see available models.');
-                            break;
-                        }
-                    }
-                    const config = await readConfig();
-                    config.models.primaryModel = newModelId;
-                    await writeConfig(config);
-                    await this.sendText(chatId, `✅ *Model updated!*\n\nNew primary model: ${newModelId}\n\nRestart TwinClaw for changes to take effect.`);
-                }
-                else {
-                    const config = await readConfig();
-                    const currentPrimary = config.models.primaryModel || 'not set';
-                    await this.sendText(chatId, `📦 *Models*
-
-Current: ${currentPrimary}
-
-Commands:
-• /model list - List available models
-• /model set <number> - Set primary model
-
-Example: /model set 1
-`);
-                }
-                break;
-            case '/keys':
-            case '/key':
-                await this.sendText(chatId, `🔑 *API Keys*
-
-Use *twinclaw config* to manage API keys.
-
-Or run: *twinclaw config* in terminal
-`);
-                break;
-            case '/channel':
-            case '/channels':
-                await this.sendText(chatId, `📱 *Channels*
-
-WhatsApp: ✅ Connected
-Telegram: Use /channels to check
-
-Run: *twinclaw channels* in terminal
-`);
-                break;
-            case '/clear':
-                await this.sendText(chatId, '🗑️ Conversation cleared! Starting fresh.');
-                break;
-            default:
-                await this.sendText(chatId, `Unknown command: ${command}\nType /menu for available commands.`);
-        }
+        const router = new CommandRouter();
+        const response = await router.dispatch(fullText || command, 'whatsapp', chatId);
+        await this.sendText(chatId, response);
     }
     onMessage;
     async #applyRateLimit() {

package/dist/services/db.js

@@ -1,12 +1,10 @@
 import Database from 'better-sqlite3';
-import * as sqliteVec from 'sqlite-vec';
 import path from 'path';
 import fs from 'fs';
 import { getConfigValue } from '../config/json-config.js';
 import { getDatabasePath, ensureWorkspaceSubdirs } from '../config/workspace.js';
 ensureWorkspaceSubdirs();
 const DB_PATH = getDatabasePath();
-const MEMORY_EMBEDDING_DIM = Number(getConfigValue('MEMORY_EMBEDDING_DIM') ?? '1536') || 1536;
 const DEFAULT_MEMORY_TOP_K = 5;
 const MAX_MEMORY_TOP_K = 50;
 const ALLOW_CROSS_SESSION_MEMORY_FALLBACK = getConfigValue('MEMORY_ALLOW_CROSS_SESSION_FALLBACK')?.trim().toLowerCase() === 'true';
@@ -14,8 +12,6 @@ if (!fs.existsSync(path.dirname(DB_PATH))) {
     fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
 }
 export const db = new Database(DB_PATH);
-// Load sqlite-vec C extension
-sqliteVec.load(db);
 db.pragma('foreign_keys = ON');
 db.exec(`
   CREATE TABLE IF NOT EXISTS sessions (
@@ -58,11 +54,11 @@ db.exec(`
     FOREIGN KEY(session_id) REFERENCES sessions(session_id)
   );
 
-  -- Virtual table for vector search
-  CREATE VIRTUAL TABLE IF NOT EXISTS vec_memory USING vec0(
-    embedding float[${MEMORY_EMBEDDING_DIM}],
-    session_id TEXT,
-    fact_text TEXT
+  -- Virtual table for full-text search (FTS5) memory
+  CREATE VIRTUAL TABLE IF NOT EXISTS semantic_memory_fts USING fts5(
+    session_id UNINDEXED,
+    fact_text,
+    tokenize="porter unicode61"
   );
 
   CREATE TABLE IF NOT EXISTS reasoning_nodes (
@@ -298,13 +294,6 @@ db.exec(`
   CREATE INDEX IF NOT EXISTS idx_runtime_budget_events_created
     ON runtime_budget_events(created_at DESC);
 `);
-function serializeEmbedding(embedding) {
-    const sqliteVecWithSerializer = sqliteVec;
-    if (typeof sqliteVecWithSerializer.serializeFloat32 === 'function') {
-        return sqliteVecWithSerializer.serializeFloat32(embedding);
-    }
-    return Buffer.from(new Float32Array(embedding).buffer);
-}
 function normalizeTopK(topK) {
     if (!Number.isFinite(topK)) {
         return DEFAULT_MEMORY_TOP_K;
@@ -327,55 +316,26 @@ export function getSessionMessages(sessionId) {
     const stmt = db.prepare('SELECT * FROM messages WHERE session_id = ? ORDER BY rowid ASC');
     return stmt.all(sessionId);
 }
-export function saveMemoryEmbedding(sessionId, factText, embedding) {
-    const stmt = db.prepare('INSERT INTO vec_memory (embedding, session_id, fact_text) VALUES (?, ?, ?)');
-    const result = stmt.run(serializeEmbedding(embedding), sessionId, factText);
+export function saveMemoryFact(sessionId, factText) {
+    const stmt = db.prepare('INSERT INTO semantic_memory_fts (session_id, fact_text) VALUES (?, ?)');
+    const result = stmt.run(sessionId, factText);
     return Number(result.lastInsertRowid);
 }
-export function getNearestMemories(queryEmbedding, topK = 5, currentSessionId) {
-    const boundedTopK = normalizeTopK(topK);
-    const matcher = serializeEmbedding(queryEmbedding);
-    const stmt = db.prepare('SELECT rowid AS memory_rowid, session_id, fact_text, distance FROM vec_memory WHERE embedding MATCH ? ORDER BY distance ASC LIMIT ?');
-    const rows = stmt.all(matcher, boundedTopK * 3);
-    if (!currentSessionId) {
-        return rows.slice(0, boundedTopK);
-    }
-    const scoped = rows.filter((row) => row.session_id === currentSessionId);
-    if (!ALLOW_CROSS_SESSION_MEMORY_FALLBACK) {
-        return scoped.slice(0, boundedTopK);
-    }
-    const global = rows.filter((row) => row.session_id !== currentSessionId);
-    return [...scoped, ...global].slice(0, boundedTopK);
-}
-/**
- * Keyword-based fallback search when vector embeddings are unavailable.
- * Uses simple SQL LIKE matching.
- */
-export function keywordSearchMemories(query, topK = 5, currentSessionId) {
+export function searchMemoriesFTS(query, topK = 5, currentSessionId) {
     const boundedTopK = normalizeTopK(topK);
-    // Simple tokenization: remove common punctuation and split by whitespace
-    const tokens = query
+    const words = query
         .toLowerCase()
         .replace(/[^\w\s]/g, ' ')
         .split(/\s+/)
-        .filter((t) => t.length > 2);
-    if (tokens.length === 0) {
+        .filter((w) => w.length > 2);
+    if (words.length === 0) {
         return [];
     }
-    // Build a query with LIKE for each token (OR logic)
-    // Distance is mocked as 1.0 for keyword matches
-    const placeholders = tokens.map(() => 'fact_text LIKE ?').join(' OR ');
-    const sql = `
-    SELECT rowid AS memory_rowid, session_id, fact_text, 1.0 AS distance 
-    FROM vec_memory 
-    WHERE ${placeholders}
-    ORDER BY rowid DESC
-    LIMIT ?
-  `;
+    // Use natural language query format or standard FTS query
+    const ftsQuery = words.map((w) => `"${w}"*`).join(' OR ');
+    const stmt = db.prepare('SELECT rowid AS memory_rowid, session_id, fact_text, rank AS distance FROM semantic_memory_fts WHERE semantic_memory_fts MATCH ? ORDER BY rank ASC LIMIT ?');
     try {
-        const stmt = db.prepare(sql);
-        const values = tokens.map((t) => `%${t}%`);
-        const rows = stmt.all(...values, boundedTopK * 3);
+        const rows = stmt.all(ftsQuery, boundedTopK * 3);
         if (!currentSessionId) {
             return rows.slice(0, boundedTopK);
         }
@@ -386,10 +346,10 @@ export function keywordSearchMemories(query, topK = 5, currentSessionId) {
         const global = rows.filter((row) => row.session_id !== currentSessionId);
         return [...scoped, ...global].slice(0, boundedTopK);
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(`[DB] keywordSearchMemories failed (tokens=${tokens.length}, topK=${boundedTopK}, scoped=${currentSessionId ? 'yes' : 'no'}): ${message}`);
-        throw error;
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[DB] FTS search failed for query '${ftsQuery}': ${message}`);
+        return [];
     }
 }
 // Re-export domain-specific DB helpers for backwards compatibility.

package/dist/services/device-pairing.js

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { logThought } from '../utils/logger.js';
+import { getWorkspaceDir } from '../config/workspace.js';
 const CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
 const CODE_LENGTH = 8;
 const DEFAULT_CODE_TTL_MS = 5 * 60 * 1000; // 5 minutes for device pairing
@@ -33,7 +34,7 @@ export class DevicePairingService {
     constructor(options = {}) {
         this.#credentialsDir = options.credentialsDir
             ? path.resolve(options.credentialsDir)
-            : path.resolve('memory', 'devices');
+            : path.join(getWorkspaceDir(), 'memory', 'devices');
         this.#codeTtlMs = options.codeTtlMs ?? DEFAULT_CODE_TTL_MS;
         this.#maxPending = options.maxPendingPerChannel ?? DEFAULT_MAX_PENDING;
         // Load existing devices

package/dist/services/dm-pairing.js

@@ -1,6 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { getWorkspaceDir } from '../config/workspace.js';
 const CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
 const CODE_LENGTH = 8;
 const DEFAULT_CODE_TTL_MS = 60 * 60 * 1000;
@@ -66,7 +67,7 @@ export class DmPairingService {
     constructor(options = {}) {
         this.#credentialsDir = options.credentialsDir
             ? path.resolve(options.credentialsDir)
-            : path.resolve('memory', 'credentials');
+            : path.join(getWorkspaceDir(), 'memory', 'credentials');
         this.#codeTtlMs =
             Number.isFinite(options.codeTtlMs) && (options.codeTtlMs ?? 0) > 0
                 ? Number(options.codeTtlMs)

package/dist/services/hooks.js

@@ -93,6 +93,18 @@ class HooksService {
         }
         return results;
     }
+    async executeHook(event, data = {}) {
+        const context = {
+            event,
+            timestamp: new Date().toISOString(),
+            data,
+        };
+        // Use the sessionId if provided in the data payload
+        if (typeof data.sessionId === 'string') {
+            context.sessionId = data.sessionId;
+        }
+        return this.runHook(event, context);
+    }
     async #runScript(scriptPath, context) {
         const fullPath = path.isAbsolute(scriptPath)
             ? scriptPath

package/dist/services/job-scheduler.js

@@ -2,6 +2,7 @@ import cron from 'node-cron';
 import { logThought } from '../utils/logger.js';
 import fs from 'node:fs';
 import path from 'node:path';
+import { getWorkspaceDir } from '../config/workspace.js';
 /**
  * Centralized job scheduler for TwinClaw's proactive execution layer.
  *
@@ -30,7 +31,8 @@ export class JobScheduler {
      * @param persistenceDir - Directory to store job persistence files
      */
     constructor(persistenceDir) {
-        this.#persistencePath = path.resolve(persistenceDir || './memory', 'scheduler-jobs.json');
+        const workspaceMemoryDir = path.join(getWorkspaceDir(), 'memory');
+        this.#persistencePath = path.resolve(persistenceDir || workspaceMemoryDir, 'scheduler-jobs.json');
         this.#loadPersistedJobs();
     }
     /** Register a new repeating job. Throws if a job with the same ID already exists. */

package/dist/services/learning-system.js

@@ -69,10 +69,14 @@ class LearningSystem {
         return entry;
     }
     #findSimilar(description) {
+        if (!description)
+            return undefined;
         const searchTerms = description.toLowerCase().split(/\s+/);
         let bestMatch;
         let bestScore = 0;
         for (const memory of this.#memories.values()) {
+            if (!memory.description)
+                continue;
             const memTerms = memory.description.toLowerCase().split(/\s+/);
             let score = 0;
             for (const term of searchTerms) {

package/dist/services/model-router.js

@@ -290,6 +290,7 @@ export class ModelRouter {
             if (lastTriedModelId && lastTriedModelId !== config.id) {
                 this.metrics.failoverCount += 1;
                 this.recordEvent('failover', config, `Automatic fallback ${lastTriedModelId} -> ${config.id}.`);
+                console.warn(`[ModelRouter] ⚠️ Fallback triggered: Switching from ${lastTriedModelId} to ${config.id}`);
             }
             const payload = {
                 model: config.model,
@@ -317,6 +318,7 @@ export class ModelRouter {
                 const retryWaitMs = Math.min(firstAttempt.rateLimitCooldownMs, this.intelligentPacingMaxWaitMs);
                 if (retryWaitMs > 0) {
                     this.recordEvent('cooldown_wait', config, `Intelligent pacing wait ${retryWaitMs}ms before retrying ${config.id}.`);
+                    console.warn(`[ModelRouter] ⏳ Rate limited. Intelligent pacing: waiting ${retryWaitMs}ms before retrying ${config.id}...`);
                     await this.sleepFn(retryWaitMs);
                 }
                 const retryCooldown = this.getModelCooldownState(config.id);
@@ -400,6 +402,7 @@ export class ModelRouter {
             if (lastTriedModelId && lastTriedModelId !== config.id) {
                 this.metrics.failoverCount += 1;
                 this.recordEvent('failover', config, `Automatic fallback ${lastTriedModelId} -> ${config.id}.`);
+                console.warn(`[ModelRouter] ⚠️ Streaming Fallback triggered: Switching from ${lastTriedModelId} to ${config.id}`);
             }
             const payload = {
                 model: config.model,
@@ -865,6 +868,12 @@ export class ModelRouter {
             return 'copilot';
         if (url.includes('api.github.com'))
             return 'github';
+        if (url.includes('groq.com'))
+            return 'groq';
+        if (url.includes('api.openai.com'))
+            return 'openai';
+        if (url.includes('api.anthropic.com'))
+            return 'anthropic';
         return 'unknown';
     }
     getModelCooldownState(modelId) {
@@ -1040,11 +1049,71 @@ export class ModelRouter {
                         return 0;
                     });
                     for (const def of sortedDefinitions) {
+                        // Resolve missing model/apiKeyEnvName from the static catalog and provider info
+                        let resolvedModel = def.model;
+                        let resolvedApiKeyEnvName = def.apiKeyEnvName;
+                        if (!resolvedModel || !resolvedApiKeyEnvName) {
+                            // Try to find the model in the static catalog by ID
+                            const catalogEntry = STATIC_MODEL_CATALOG.find(m => m.id === def.id);
+                            if (catalogEntry) {
+                                if (!resolvedModel)
+                                    resolvedModel = catalogEntry.model;
+                                if (!resolvedApiKeyEnvName) {
+                                    const providerInfo = PROVIDER_INFO[catalogEntry.provider];
+                                    resolvedApiKeyEnvName = providerInfo?.apiKeyEnvName ?? '';
+                                }
+                            }
+                        }
+                        // If still missing, infer provider from baseURL and resolve apiKeyEnvName
+                        if (!resolvedApiKeyEnvName) {
+                            const url = def.baseURL.toLowerCase();
+                            if (url.includes('groq.com'))
+                                resolvedApiKeyEnvName = 'GROQ_API_KEY';
+                            else if (url.includes('openrouter.ai'))
+                                resolvedApiKeyEnvName = 'OPENROUTER_API_KEY';
+                            else if (url.includes('modal.direct'))
+                                resolvedApiKeyEnvName = 'MODAL_API_KEY';
+                            else if (url.includes('api.openai.com'))
+                                resolvedApiKeyEnvName = 'OPENAI_API_KEY';
+                            else if (url.includes('generativelanguage.googleapis.com'))
+                                resolvedApiKeyEnvName = 'GEMINI_API_KEY';
+                            else if (url.includes('githubcopilot.com'))
+                                resolvedApiKeyEnvName = 'GITHUB_TOKEN';
+                            else if (url.includes('api.anthropic.com'))
+                                resolvedApiKeyEnvName = 'ANTHROPIC_API_KEY';
+                        }
+                        // If model is still missing, try to derive from the ID (e.g., groq-qwen-qwen3-32b -> qwen/qwen3-32b)
+                        if (!resolvedModel) {
+                            // Try a fuzzy match against catalog entries by normalizing IDs
+                            const normalizedDefId = def.id.toLowerCase();
+                            const fuzzyMatch = STATIC_MODEL_CATALOG.find(m => {
+                                const normalizedCatalogId = m.id.toLowerCase();
+                                return normalizedDefId === normalizedCatalogId ||
+                                    normalizedDefId.includes(normalizedCatalogId) ||
+                                    normalizedCatalogId.includes(normalizedDefId);
+                            });
+                            if (fuzzyMatch) {
+                                resolvedModel = fuzzyMatch.model;
+                            }
+                            else {
+                                // Last resort: strip provider prefix and use the rest as model name
+                                const parts = def.id.split('-');
+                                if (parts.length > 1) {
+                                    // For IDs like 'groq-qwen-qwen3-32b', try 'qwen/qwen3-32b'
+                                    // For IDs like 'openrouter-z-ai-glm-4-5-air-free', try 'z-ai/glm-4-5-air:free'
+                                    resolvedModel = def.id; // Use ID as-is — the API will reject if wrong, triggering fallback
+                                }
+                            }
+                        }
+                        if (!resolvedModel) {
+                            logThought(`[Router] Skipping definition '${def.id}': unable to resolve model name.`);
+                            continue;
+                        }
                         configModels.push({
                             id: def.id,
-                            model: def.model,
+                            model: resolvedModel,
                             baseURL: def.baseURL,
-                            apiKeyEnvName: def.apiKeyEnvName,
+                            apiKeyEnvName: resolvedApiKeyEnvName || '',
                         });
                     }
                     // Even with definitions, add fallback providers in case primary fails

package/dist/services/semantic-memory.js

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
-import { chunkText, EmbeddingService } from './embedding-service.js';
-import { getNearestMemories, keywordSearchMemories, saveMemoryEmbedding, } from './db.js';
+import { chunkText } from './embedding-service.js';
+import { searchMemoriesFTS, saveMemoryFact, } from './db.js';
 import { getMemoryProvenanceRows, getReasoningEvidenceExpansion, getReasoningNodesByClaimKey, linkMemoryProvenance, upsertReasoningEdge, upsertReasoningNode, } from './db-reasoning.js';
-const embeddingService = new EmbeddingService();
+import { getHooksService } from './hooks.js';
 const NEGATION_PATTERN = /\b(no|not|never|without|cannot|can't|won't|dont|don't|didnt|didn't|isnt|isn't|arent|aren't|wasnt|wasn't|weren't)\b/i;
 const CLAIM_KEY_STOPWORDS = /\b(a|an|the|and|or|to|of|for|in|on|at|with|is|are|was|were|be|been|being|do|does|did|this|that|it|as|by|from|no|not|never|without|cannot|cant|wont)\b/g;
 const TASK_HINT_PATTERN = /\b(todo|task|implement|fix|build|create|refactor|ship|deploy)\b/i;
@@ -20,11 +20,7 @@ export async function indexConversationTurn(sessionId, role, content) {
         const limitedChunks = chunks.slice(0, 2);
         for (const chunk of limitedChunks) {
             const taggedChunk = `${role.toUpperCase()}: ${chunk}`;
-            const embedding = await embeddingService.embedText(taggedChunk);
-            if (!embedding) {
-                continue;
-            }
-            const memoryRowId = saveMemoryEmbedding(sessionId, taggedChunk, embedding);
+            const memoryRowId = saveMemoryFact(sessionId, taggedChunk);
             const node = buildReasoningNode(sessionId, role, taggedChunk);
             upsertReasoningNode(node);
             linkMemoryProvenance(memoryRowId, node.nodeId, sessionId);
@@ -41,6 +37,11 @@ export async function indexConversationTurn(sessionId, role, content) {
             previousNodeId = node.nodeId;
             reconcileClaimRelations(node);
         }
+        // Trigger proactive context alignment hook
+        const hooks = getHooksService();
+        hooks.executeHook('afterIndexTurn', { sessionId, role, content }).catch((err) => {
+            console.warn(`[SemanticMemory] Hook execution failed for afterIndexTurn:`, err);
+        });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -48,24 +49,13 @@ export async function indexConversationTurn(sessionId, role, content) {
     }
 }
 export async function retrieveEvidenceAwareMemoryContext(sessionId, prompt, topK = 5) {
-    const embedding = await embeddingService.embedText(prompt);
     const candidateLimit = Math.max(topK * 3, topK);
-    let nearest;
-    let fallbackUsed = false;
-    if (embedding) {
-        nearest = getNearestMemories(embedding, candidateLimit, sessionId);
-    }
-    else {
-        nearest = keywordSearchMemories(prompt, candidateLimit, sessionId);
-        fallbackUsed = true;
-    }
+    const nearest = searchMemoriesFTS(prompt, candidateLimit, sessionId);
     if (nearest.length === 0) {
         return {
             context: '',
             diagnostics: [
-                fallbackUsed
-                    ? 'Keyword-fallback memory retrieval found no candidates for the active session scope.'
-                    : 'Memory retrieval found no nearest vector candidates for the active session scope.'
+                'Memory retrieval found no FTS candidates for the active session scope.'
             ],
             conflictCount: 0,
             hitCount: 0,
@@ -93,9 +83,7 @@ export async function retrieveEvidenceAwareMemoryContext(sessionId, prompt, topK
     return {
         context: `Retrieved evidence-backed memories:\n${lines.join('\n')}${conflictNote}`,
         diagnostics: [
-            fallbackUsed
-                ? `Keyword-fallback memory retrieval ranked ${nearest.length} candidates down to ${ranked.length} items.`
-                : `Hybrid memory retrieval ranked ${nearest.length} vector candidates down to ${ranked.length} evidence-backed items.`,
+            `FTS memory retrieval ranked ${nearest.length} candidates down to ${ranked.length} evidence-backed items.`,
             `Graph traversal depth=${MAX_GRAPH_TRAVERSAL_DEPTH} collected ${expandedEdges.length} relation edge(s).`,
             conflictCount > 0
                 ? `Detected contradiction signals in ${conflictCount} candidate(s).`
@@ -207,7 +195,9 @@ function buildGraphRelationCounts(edges) {
 }
 function scoreCandidate(sessionId, factText, memoryRowId, distance, options) {
     const provenance = options.provenance;
-    const vectorScore = 1 / (1 + Math.max(0, distance));
+    // SQLite FTS5 bm25 rank is negative. More negative means better match.
+    const ftsRelevance = Math.max(0, -distance);
+    const ftsScore = Math.min(1, ftsRelevance * 0.15); // Scale BM25 to 0.0 - 1.0 range
     const graphCounts = provenance
         ? options.graphRelationCounts.get(provenance.nodeId) ?? {
             supports: 0,
@@ -223,7 +213,7 @@ function scoreCandidate(sessionId, factText, memoryRowId, distance, options) {
     const relationScore = Math.min(1, supports * 0.2 + depends * 0.11 + derived * 0.08);
     const recencyScore = estimateRecencyScore(provenance?.updatedAt);
     const contradictionPenalty = Math.min(0.35, contradicts * 0.08);
-    const score = vectorScore * 0.62 + relationScore * 0.26 + recencyScore * 0.12 - contradictionPenalty;
+    const score = ftsScore * 0.62 + relationScore * 0.26 + recencyScore * 0.12 - contradictionPenalty;
     return {
         sessionId,
         factText,

package/dist/skills/builtin.js

@@ -5,6 +5,7 @@ import { randomUUID } from 'node:crypto';
 import { executeProgram, executeShell } from './shell.js';
 import { logToolCall } from '../utils/logger.js';
 import { validatePathInWorkspace } from '../config/workspace.js';
+import { getPersonaEditorTool } from '../tools/persona-editor.js';
 function buildReadFileSkill() {
     return {
         name: 'fs.read',
@@ -1038,6 +1039,39 @@ function buildVenvSkill() {
         },
     };
 }
+function buildPersonaEditorSkill() {
+    return {
+        name: 'persona.edit',
+        group: 'group:core',
+        aliases: ['edit_persona', 'update_user_profile', 'update_soul'],
+        description: 'Programmatically edit the agent\'s identity (soul.md) or user profile (user.md).',
+        parameters: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', enum: ['user', 'soul'] },
+                operation: { type: 'string', enum: ['append', 'replace', 'clear'] },
+                content: { type: 'string' },
+            },
+            required: ['target', 'operation'],
+        },
+        async execute(input) {
+            if (input.operation !== 'clear' && typeof input.content !== 'string') {
+                return { ok: false, output: 'Content must be provided for append/replace operations' };
+            }
+            const request = input;
+            const editor = getPersonaEditorTool();
+            const result = await editor.editPersona({
+                target: request.target,
+                operation: request.operation,
+                content: request.content || '',
+            });
+            return {
+                ok: result.success,
+                output: result.message,
+            };
+        },
+    };
+}
 export function createBuiltinSkills() {
     return [
         buildReadFileSkill(),
@@ -1073,5 +1107,6 @@ export function createBuiltinSkills() {
         buildDefenderSkill(),
         buildPowerShellISESkill(),
         buildVenvSkill(),
+        buildPersonaEditorSkill(),
     ];
 }