@hybridaione/hybridclaw 0.2.2 → 0.2.6

package/dist/db.js

@@ -1,10 +1,60 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
 import Database from 'better-sqlite3';
-import fs from 'fs';
-import path from 'path';
 import { DB_PATH } from './config.js';
 import { logger } from './logger.js';
+import { KnowledgeEntityType, KnowledgeRelationType } from './types.js';
 let db;
-function createSchema(database) {
+const SCHEMA_VERSION = 4;
+function getSchemaVersion(database) {
+    const raw = database.pragma('user_version', { simple: true });
+    const value = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.trunc(value));
+}
+function setSchemaVersion(database, version) {
+    const bounded = Math.max(0, Math.trunc(version));
+    database.pragma(`user_version = ${bounded}`);
+}
+function tableExists(database, table) {
+    const row = database
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(table);
+    return Boolean(row?.name);
+}
+function columnExists(database, table, column) {
+    const cols = database.pragma(`table_info(${table})`);
+    return cols.some((entry) => entry.name === column);
+}
+function addColumnIfMissing(params) {
+    if (!tableExists(params.database, params.table))
+        return;
+    if (columnExists(params.database, params.table, params.column))
+        return;
+    params.database.exec(`ALTER TABLE ${params.table} ADD COLUMN ${params.ddl}`);
+    if (!params.quiet) {
+        logger.info({ table: params.table, column: params.column }, 'Migrated table: added column');
+    }
+}
+function ensureMigrationTable(database) {
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS migrations (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL,
+      description TEXT
+    );
+  `);
+}
+function recordMigration(database, version, description) {
+    ensureMigrationTable(database);
+    database
+        .prepare(`INSERT OR IGNORE INTO migrations (version, applied_at, description)
+       VALUES (?, datetime('now'), ?)`)
+        .run(version, description);
+}
+function migrateV1(database) {
     database.exec(`
     CREATE TABLE IF NOT EXISTS sessions (
       id TEXT PRIMARY KEY,
@@ -33,14 +83,45 @@ function createSchema(database) {
     );
     CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id);
 
+    CREATE TABLE IF NOT EXISTS semantic_memories (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      source TEXT NOT NULL DEFAULT 'conversation',
+      scope TEXT NOT NULL DEFAULT 'episodic',
+      metadata TEXT NOT NULL DEFAULT '{}',
+      content TEXT NOT NULL,
+      confidence REAL NOT NULL DEFAULT 1.0,
+      embedding BLOB,
+      source_message_id INTEGER,
+      created_at TEXT DEFAULT (datetime('now')),
+      accessed_at TEXT DEFAULT (datetime('now')),
+      access_count INTEGER NOT NULL DEFAULT 0,
+      deleted INTEGER NOT NULL DEFAULT 0
+    );
+
+    CREATE TABLE IF NOT EXISTS kv_store (
+      agent_id TEXT NOT NULL,
+      key TEXT NOT NULL,
+      value BLOB NOT NULL,
+      version INTEGER NOT NULL DEFAULT 1,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (agent_id, key)
+    );
+    CREATE INDEX IF NOT EXISTS idx_kv_store_agent ON kv_store(agent_id);
+
     CREATE TABLE IF NOT EXISTS tasks (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       session_id TEXT NOT NULL,
       channel_id TEXT NOT NULL,
       cron_expr TEXT NOT NULL,
+      run_at TEXT,
+      every_ms INTEGER,
       prompt TEXT NOT NULL,
       enabled INTEGER DEFAULT 1,
       last_run TEXT,
+      last_status TEXT,
+      consecutive_errors INTEGER DEFAULT 0,
       created_at TEXT DEFAULT (datetime('now'))
     );
 
@@ -107,67 +188,1015 @@ function createSchema(database) {
       queued_at TEXT DEFAULT (datetime('now'))
     );
     CREATE INDEX IF NOT EXISTS idx_proactive_queue_id ON proactive_message_queue(id);
+
+    CREATE TABLE IF NOT EXISTS migrations (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL,
+      description TEXT
+    );
   `);
+    recordMigration(database, 1, 'Initial schema');
 }
-function migrateSchema(database, opts) {
+function migrateV2(database, opts) {
     const quiet = opts?.quiet === true;
-    const addColumnIfMissing = (table, column, ddl) => {
-        const cols = database.pragma(`table_info(${table})`);
-        if (!cols.some((c) => c.name === column)) {
-            database.exec(`ALTER TABLE ${table} ADD COLUMN ${ddl}`);
-            if (!quiet)
-                logger.info({ table, column }, 'Migrated table: added column');
-        }
-    };
-    // Add session columns if they don't exist
-    const sessionCols = database.pragma('table_info(sessions)');
-    if (!sessionCols.some((c) => c.name === 'model')) {
-        database.exec('ALTER TABLE sessions ADD COLUMN model TEXT');
-        if (!quiet)
-            logger.info('Migrated sessions table: added model column');
-    }
-    addColumnIfMissing('sessions', 'session_summary', 'session_summary TEXT');
-    addColumnIfMissing('sessions', 'summary_updated_at', 'summary_updated_at TEXT');
-    addColumnIfMissing('sessions', 'compaction_count', 'compaction_count INTEGER DEFAULT 0');
-    addColumnIfMissing('sessions', 'memory_flush_at', 'memory_flush_at TEXT');
-    // Add run_at and every_ms columns to tasks if they don't exist
-    const taskCols = database.pragma('table_info(tasks)');
-    if (!taskCols.some((c) => c.name === 'run_at')) {
-        database.exec('ALTER TABLE tasks ADD COLUMN run_at TEXT');
+    addColumnIfMissing({
+        database,
+        table: 'sessions',
+        column: 'model',
+        ddl: 'model TEXT',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'sessions',
+        column: 'session_summary',
+        ddl: 'session_summary TEXT',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'sessions',
+        column: 'summary_updated_at',
+        ddl: 'summary_updated_at TEXT',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'sessions',
+        column: 'compaction_count',
+        ddl: 'compaction_count INTEGER DEFAULT 0',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'sessions',
+        column: 'memory_flush_at',
+        ddl: 'memory_flush_at TEXT',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'tasks',
+        column: 'run_at',
+        ddl: 'run_at TEXT',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'tasks',
+        column: 'every_ms',
+        ddl: 'every_ms INTEGER',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'tasks',
+        column: 'last_status',
+        ddl: 'last_status TEXT',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'tasks',
+        column: 'consecutive_errors',
+        ddl: 'consecutive_errors INTEGER DEFAULT 0',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'semantic_memories',
+        column: 'embedding',
+        ddl: 'embedding BLOB',
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'semantic_memories',
+        column: 'source',
+        ddl: "source TEXT NOT NULL DEFAULT 'conversation'",
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'semantic_memories',
+        column: 'scope',
+        ddl: "scope TEXT NOT NULL DEFAULT 'episodic'",
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'semantic_memories',
+        column: 'metadata',
+        ddl: "metadata TEXT NOT NULL DEFAULT '{}'",
+        quiet,
+    });
+    addColumnIfMissing({
+        database,
+        table: 'semantic_memories',
+        column: 'deleted',
+        ddl: 'deleted INTEGER NOT NULL DEFAULT 0',
+        quiet,
+    });
+    // Semantic indexes are created after column migrations so older DBs can boot.
+    database.exec(`
+    CREATE INDEX IF NOT EXISTS idx_semantic_memories_session ON semantic_memories(session_id);
+    CREATE INDEX IF NOT EXISTS idx_semantic_memories_scope ON semantic_memories(scope);
+    CREATE INDEX IF NOT EXISTS idx_semantic_memories_confidence ON semantic_memories(confidence);
+    CREATE INDEX IF NOT EXISTS idx_semantic_memories_accessed ON semantic_memories(accessed_at);
+    CREATE INDEX IF NOT EXISTS idx_semantic_memories_deleted ON semantic_memories(deleted);
+  `);
+    if (tableExists(database, 'memory_kv')) {
+        database.exec(`INSERT OR IGNORE INTO kv_store (agent_id, key, value, version, updated_at)
+       SELECT session_id,
+              mem_key,
+              CAST(value_json AS BLOB),
+              1,
+              COALESCE(updated_at, datetime('now'))
+       FROM memory_kv`);
         if (!quiet)
-            logger.info('Migrated tasks table: added run_at column');
+            logger.info('Migrated legacy memory_kv rows into kv_store');
     }
-    if (!taskCols.some((c) => c.name === 'every_ms')) {
-        database.exec('ALTER TABLE tasks ADD COLUMN every_ms INTEGER');
-        if (!quiet)
-            logger.info('Migrated tasks table: added every_ms column');
+    recordMigration(database, 2, 'Backfill legacy columns/indexes and migrate memory_kv to kv_store');
+}
+function migrateV3(database) {
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS entities (
+      id TEXT PRIMARY KEY,
+      entity_type TEXT NOT NULL,
+      name TEXT NOT NULL,
+      properties TEXT NOT NULL DEFAULT '{}',
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS relations (
+      id TEXT PRIMARY KEY,
+      source_entity TEXT NOT NULL,
+      relation_type TEXT NOT NULL,
+      target_entity TEXT NOT NULL,
+      properties TEXT NOT NULL DEFAULT '{}',
+      confidence REAL NOT NULL DEFAULT 1.0,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_relations_source ON relations(source_entity);
+    CREATE INDEX IF NOT EXISTS idx_relations_target ON relations(target_entity);
+    CREATE INDEX IF NOT EXISTS idx_relations_type ON relations(relation_type);
+  `);
+    recordMigration(database, 3, 'Add knowledge graph entities/relations tables and indexes');
+}
+function migrateV4(database) {
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS canonical_sessions (
+      canonical_id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      messages TEXT NOT NULL DEFAULT '[]',
+      compaction_cursor INTEGER NOT NULL DEFAULT 0,
+      compacted_summary TEXT,
+      message_count INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      UNIQUE(agent_id, user_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_canonical_sessions_agent_user ON canonical_sessions(agent_id, user_id);
+    CREATE INDEX IF NOT EXISTS idx_canonical_sessions_updated ON canonical_sessions(updated_at);
+
+    CREATE TABLE IF NOT EXISTS usage_events (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      agent_id TEXT NOT NULL,
+      timestamp TEXT NOT NULL,
+      model TEXT NOT NULL,
+      input_tokens INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      total_tokens INTEGER NOT NULL DEFAULT 0,
+      cost_usd REAL NOT NULL DEFAULT 0.0,
+      tool_calls INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE INDEX IF NOT EXISTS idx_usage_events_agent_time ON usage_events(agent_id, timestamp);
+    CREATE INDEX IF NOT EXISTS idx_usage_events_time ON usage_events(timestamp);
+    CREATE INDEX IF NOT EXISTS idx_usage_events_model_time ON usage_events(model, timestamp);
+    CREATE INDEX IF NOT EXISTS idx_usage_events_session_time ON usage_events(session_id, timestamp);
+  `);
+    recordMigration(database, 4, 'Add canonical_sessions and usage_events tables');
+}
+function runMigrations(database, opts) {
+    const currentVersion = getSchemaVersion(database);
+    const quiet = opts?.quiet === true;
+    if (currentVersion > SCHEMA_VERSION) {
+        if (!quiet) {
+            logger.warn({ currentVersion, supportedVersion: SCHEMA_VERSION }, 'Database schema version is newer than this binary supports; skipping migrations');
+        }
+        return;
+    }
+    if (currentVersion < 1)
+        migrateV1(database);
+    if (currentVersion < 2)
+        migrateV2(database, opts);
+    if (currentVersion < 3)
+        migrateV3(database);
+    if (currentVersion < 4)
+        migrateV4(database);
+    setSchemaVersion(database, SCHEMA_VERSION);
+    if (!quiet && currentVersion < SCHEMA_VERSION) {
+        logger.info({ fromVersion: currentVersion, toVersion: SCHEMA_VERSION }, 'Database schema migrated');
     }
 }
 export function initDatabase(opts) {
     const quiet = opts?.quiet === true;
-    const dbPath = path.resolve(DB_PATH);
+    const dbPath = path.resolve(opts?.dbPath || DB_PATH);
     fs.mkdirSync(path.dirname(dbPath), { recursive: true });
     db = new Database(dbPath);
     db.pragma('journal_mode = WAL');
-    createSchema(db);
-    migrateSchema(db, opts);
+    db.pragma('busy_timeout = 5000');
+    runMigrations(db, opts);
     if (!quiet)
         logger.info({ path: dbPath }, 'Database initialized');
 }
+function normalizeMemoryKvKey(key) {
+    return key.trim();
+}
+function serializeMemoryKvValue(value) {
+    if (typeof value === 'undefined')
+        return Buffer.from('null', 'utf8');
+    try {
+        const serialized = JSON.stringify(value);
+        return Buffer.from(typeof serialized === 'string' ? serialized : 'null', 'utf8');
+    }
+    catch {
+        return Buffer.from('null', 'utf8');
+    }
+}
+function parseMemoryKvValue(raw) {
+    const text = Buffer.isBuffer(raw)
+        ? raw.toString('utf8')
+        : raw instanceof Uint8Array
+            ? Buffer.from(raw).toString('utf8')
+            : typeof raw === 'string'
+                ? raw
+                : null;
+    if (text == null)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export function getMemoryValue(sessionId, key) {
+    const normalizedKey = normalizeMemoryKvKey(key);
+    if (!normalizedKey)
+        return null;
+    const row = db
+        .prepare(`SELECT value
+       FROM kv_store
+       WHERE agent_id = ?
+         AND key = ?`)
+        .get(sessionId, normalizedKey);
+    if (!row)
+        return null;
+    return parseMemoryKvValue(row.value);
+}
+export function setMemoryValue(sessionId, key, value) {
+    const normalizedKey = normalizeMemoryKvKey(key);
+    if (!normalizedKey)
+        return;
+    const valueBlob = serializeMemoryKvValue(value);
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO kv_store (agent_id, key, value, version, updated_at)
+     VALUES (?, ?, ?, 1, ?)
+     ON CONFLICT(agent_id, key)
+     DO UPDATE SET value = excluded.value, version = version + 1, updated_at = excluded.updated_at`).run(sessionId, normalizedKey, valueBlob, now);
+}
+export function deleteMemoryValue(sessionId, key) {
+    const normalizedKey = normalizeMemoryKvKey(key);
+    if (!normalizedKey)
+        return false;
+    const result = db
+        .prepare(`DELETE FROM kv_store
+       WHERE agent_id = ?
+         AND key = ?`)
+        .run(sessionId, normalizedKey);
+    return result.changes > 0;
+}
+export function listMemoryValues(sessionId, prefix) {
+    const normalizedPrefix = (prefix || '').trim();
+    const rows = normalizedPrefix
+        ? db
+            .prepare(`SELECT agent_id, key, value, version, updated_at
+           FROM kv_store
+           WHERE agent_id = ?
+             AND key LIKE ?
+           ORDER BY key ASC`)
+            .all(sessionId, `${normalizedPrefix}%`)
+        : db
+            .prepare(`SELECT agent_id, key, value, version, updated_at
+           FROM kv_store
+           WHERE agent_id = ?
+           ORDER BY key ASC`)
+            .all(sessionId);
+    return rows.map((row) => ({
+        agent_id: row.agent_id,
+        key: row.key,
+        value: parseMemoryKvValue(row.value),
+        version: row.version,
+        updated_at: row.updated_at,
+    }));
+}
+// --- Canonical Sessions (Cross-Channel Memory) ---
+const DEFAULT_CANONICAL_WINDOW = 50;
+const DEFAULT_CANONICAL_COMPACTION_THRESHOLD = 100;
+const CANONICAL_SUMMARY_MAX_CHARS = 4_000;
+const CANONICAL_MESSAGE_MAX_CHARS = 220;
+function canonicalSessionId(agentId, userId) {
+    return `${agentId}:${userId}`;
+}
+function normalizeCanonicalRole(role) {
+    const normalized = role.trim().toLowerCase();
+    if (normalized === 'user' ||
+        normalized === 'assistant' ||
+        normalized === 'system' ||
+        normalized === 'tool') {
+        return normalized;
+    }
+    return 'user';
+}
+function truncateCanonicalContent(content) {
+    const compact = content.replace(/\s+/g, ' ').trim();
+    if (compact.length <= CANONICAL_MESSAGE_MAX_CHARS)
+        return compact;
+    return `${compact.slice(0, CANONICAL_MESSAGE_MAX_CHARS)}...`;
+}
+function parseCanonicalMessages(raw) {
+    const text = typeof raw === 'string' ? raw.trim() : '';
+    if (!text)
+        return [];
+    try {
+        const parsed = JSON.parse(text);
+        if (!Array.isArray(parsed))
+            return [];
+        const messages = [];
+        for (const item of parsed) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const row = item;
+            const content = typeof row.content === 'string' ? row.content.trim() : '';
+            if (!content)
+                continue;
+            const sessionId = typeof row.session_id === 'string' ? row.session_id.trim() : '';
+            if (!sessionId)
+                continue;
+            const createdAt = typeof row.created_at === 'string' && row.created_at.trim()
+                ? row.created_at.trim()
+                : new Date().toISOString();
+            messages.push({
+                role: normalizeCanonicalRole(typeof row.role === 'string' ? row.role : 'user'),
+                content,
+                session_id: sessionId,
+                channel_id: typeof row.channel_id === 'string' && row.channel_id.trim()
+                    ? row.channel_id.trim()
+                    : null,
+                created_at: createdAt,
+            });
+        }
+        return messages;
+    }
+    catch {
+        return [];
+    }
+}
+function serializeCanonicalMessages(messages) {
+    try {
+        return JSON.stringify(messages);
+    }
+    catch {
+        return '[]';
+    }
+}
+function buildCanonicalSummary(params) {
+    const lines = [];
+    const previous = (params.previousSummary || '').trim();
+    if (previous)
+        lines.push(previous);
+    for (const message of params.compactingMessages) {
+        const role = message.role === 'assistant'
+            ? 'Assistant'
+            : message.role === 'system'
+                ? 'System'
+                : message.role === 'tool'
+                    ? 'Tool'
+                    : 'User';
+        const compact = truncateCanonicalContent(message.content);
+        if (!compact)
+            continue;
+        lines.push(`${role}: ${compact}`);
+    }
+    if (lines.length === 0)
+        return previous || null;
+    const merged = lines.join('\n');
+    if (merged.length <= CANONICAL_SUMMARY_MAX_CHARS)
+        return merged;
+    return merged.slice(Math.max(0, merged.length - CANONICAL_SUMMARY_MAX_CHARS));
+}
+function saveCanonicalSession(session) {
+    db.prepare(`INSERT INTO canonical_sessions
+      (canonical_id, agent_id, user_id, messages, compaction_cursor, compacted_summary, message_count, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(canonical_id) DO UPDATE SET
+       messages = excluded.messages,
+       compaction_cursor = excluded.compaction_cursor,
+       compacted_summary = excluded.compacted_summary,
+       message_count = excluded.message_count,
+       updated_at = excluded.updated_at`).run(session.canonical_id, session.agent_id, session.user_id, serializeCanonicalMessages(session.messages), Math.max(0, Math.floor(session.compaction_cursor)), session.compacted_summary, Math.max(0, Math.floor(session.message_count)), session.created_at, session.updated_at);
+}
+export function loadCanonicalSession(agentId, userId) {
+    const normalizedAgentId = agentId.trim();
+    const normalizedUserId = userId.trim();
+    if (!normalizedAgentId) {
+        throw new Error('Canonical session agentId is required');
+    }
+    if (!normalizedUserId) {
+        throw new Error('Canonical session userId is required');
+    }
+    const row = db
+        .prepare(`SELECT canonical_id, agent_id, user_id, messages, compaction_cursor, compacted_summary, message_count, created_at, updated_at
+       FROM canonical_sessions
+       WHERE agent_id = ?
+         AND user_id = ?
+       LIMIT 1`)
+        .get(normalizedAgentId, normalizedUserId);
+    const now = new Date().toISOString();
+    if (!row) {
+        return {
+            canonical_id: canonicalSessionId(normalizedAgentId, normalizedUserId),
+            agent_id: normalizedAgentId,
+            user_id: normalizedUserId,
+            messages: [],
+            compaction_cursor: 0,
+            compacted_summary: null,
+            message_count: 0,
+            created_at: now,
+            updated_at: now,
+        };
+    }
+    return {
+        canonical_id: row.canonical_id,
+        agent_id: row.agent_id,
+        user_id: row.user_id,
+        messages: parseCanonicalMessages(row.messages),
+        compaction_cursor: Math.max(0, Math.floor(row.compaction_cursor || 0)),
+        compacted_summary: row.compacted_summary,
+        message_count: Math.max(0, Math.floor(row.message_count || 0)),
+        created_at: row.created_at || now,
+        updated_at: row.updated_at || now,
+    };
+}
+export function appendCanonicalMessages(params) {
+    const canonical = loadCanonicalSession(params.agentId, params.userId);
+    const normalizedMessages = params.newMessages
+        .map((entry) => {
+        const content = entry.content.trim();
+        const sessionId = entry.sessionId.trim();
+        if (!content || !sessionId)
+            return null;
+        return {
+            role: normalizeCanonicalRole(entry.role),
+            content,
+            session_id: sessionId,
+            channel_id: typeof entry.channelId === 'string' && entry.channelId.trim()
+                ? entry.channelId.trim()
+                : null,
+            created_at: typeof entry.createdAt === 'string' && entry.createdAt.trim()
+                ? entry.createdAt.trim()
+                : new Date().toISOString(),
+        };
+    })
+        .filter((entry) => Boolean(entry));
+    if (normalizedMessages.length === 0)
+        return canonical;
+    canonical.messages.push(...normalizedMessages);
+    canonical.message_count += normalizedMessages.length;
+    const windowSize = Math.max(1, Math.floor(params.windowSize || DEFAULT_CANONICAL_WINDOW));
+    const compactionThreshold = Math.max(windowSize + 1, Math.floor(params.compactionThreshold || DEFAULT_CANONICAL_COMPACTION_THRESHOLD));
+    if (canonical.messages.length > compactionThreshold) {
+        const toCompact = canonical.messages.length - windowSize;
+        if (toCompact > canonical.compaction_cursor) {
+            const compacting = canonical.messages.slice(canonical.compaction_cursor, toCompact);
+            canonical.compacted_summary = buildCanonicalSummary({
+                previousSummary: canonical.compacted_summary,
+                compactingMessages: compacting,
+            });
+            canonical.compaction_cursor = toCompact;
+            canonical.messages = canonical.messages.slice(toCompact);
+            canonical.compaction_cursor = 0;
+        }
+    }
+    canonical.updated_at = new Date().toISOString();
+    saveCanonicalSession(canonical);
+    return canonical;
+}
+export function getCanonicalContext(params) {
+    const canonical = loadCanonicalSession(params.agentId, params.userId);
+    const windowSize = Math.max(1, Math.floor(params.windowSize || DEFAULT_CANONICAL_WINDOW));
+    const start = Math.max(0, canonical.messages.length - windowSize);
+    const recent = canonical.messages.slice(start);
+    const excludeSessionId = typeof params.excludeSessionId === 'string'
+        ? params.excludeSessionId.trim()
+        : '';
+    const filtered = excludeSessionId
+        ? recent.filter((message) => message.session_id !== excludeSessionId)
+        : recent;
+    return {
+        summary: canonical.compacted_summary,
+        recent_messages: filtered,
+    };
+}
+// --- Usage Tracking / Aggregation ---
+function normalizeUsageWindow(window) {
+    if (window === 'daily' || window === 'monthly' || window === 'all') {
+        return window;
+    }
+    return 'all';
+}
+function usageWindowWhereClause(window) {
+    if (window === 'daily') {
+        return "timestamp >= datetime('now', 'start of day')";
+    }
+    if (window === 'monthly') {
+        return "timestamp >= datetime('now', 'start of month')";
+    }
+    return null;
+}
+function normalizeUsageNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.max(0, Math.floor(value));
+    }
+    return 0;
+}
+function normalizeUsageCost(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.max(0, value);
+    }
+    return 0;
+}
+function applyUsageFilters(params) {
+    const agentId = params.agentId?.trim();
+    if (agentId) {
+        params.whereClauses.push('agent_id = ?');
+        params.args.push(agentId);
+    }
+    const window = normalizeUsageWindow(params.window);
+    const windowClause = usageWindowWhereClause(window);
+    if (windowClause)
+        params.whereClauses.push(windowClause);
+}
+export function recordUsageEvent(params) {
+    const sessionId = params.sessionId.trim();
+    const agentId = params.agentId.trim();
+    const model = params.model.trim() || 'unknown';
+    if (!sessionId || !agentId)
+        return;
+    const inputTokens = normalizeUsageNumber(params.inputTokens);
+    const outputTokens = normalizeUsageNumber(params.outputTokens);
+    const totalTokens = normalizeUsageNumber(params.totalTokens ?? inputTokens + outputTokens);
+    const toolCalls = normalizeUsageNumber(params.toolCalls);
+    const costUsd = normalizeUsageCost(params.costUsd);
+    const timestamp = typeof params.timestamp === 'string' && params.timestamp.trim()
+        ? params.timestamp.trim()
+        : new Date().toISOString();
+    db.prepare(`INSERT INTO usage_events
+      (id, session_id, agent_id, timestamp, model, input_tokens, output_tokens, total_tokens, cost_usd, tool_calls)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(randomUUID(), sessionId, agentId, timestamp, model, inputTokens, outputTokens, totalTokens, costUsd, toolCalls);
+}
+export function getUsageTotals(params) {
+    const whereClauses = [];
+    const args = [];
+    applyUsageFilters({
+        whereClauses,
+        args,
+        agentId: params?.agentId,
+        window: params?.window,
+    });
+    const where = whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : '';
+    const row = db
+        .prepare(`SELECT
+         COALESCE(SUM(input_tokens), 0) AS total_input_tokens,
+         COALESCE(SUM(output_tokens), 0) AS total_output_tokens,
+         COALESCE(SUM(total_tokens), 0) AS total_tokens,
+         COALESCE(SUM(cost_usd), 0.0) AS total_cost_usd,
+         COUNT(*) AS call_count,
+         COALESCE(SUM(tool_calls), 0) AS total_tool_calls
+       FROM usage_events
+       ${where}`)
+        .get(...args);
+    return {
+        total_input_tokens: normalizeUsageNumber(row.total_input_tokens),
+        total_output_tokens: normalizeUsageNumber(row.total_output_tokens),
+        total_tokens: normalizeUsageNumber(row.total_tokens),
+        total_cost_usd: normalizeUsageCost(row.total_cost_usd),
+        call_count: normalizeUsageNumber(row.call_count),
+        total_tool_calls: normalizeUsageNumber(row.total_tool_calls),
+    };
+}
+export function listUsageByModel(params) {
+    const whereClauses = [];
+    const args = [];
+    applyUsageFilters({
+        whereClauses,
+        args,
+        agentId: params?.agentId,
+        window: params?.window,
+    });
+    const where = whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : '';
+    const rows = db
+        .prepare(`SELECT
+         model,
+         COALESCE(SUM(input_tokens), 0) AS total_input_tokens,
+         COALESCE(SUM(output_tokens), 0) AS total_output_tokens,
+         COALESCE(SUM(total_tokens), 0) AS total_tokens,
+         COALESCE(SUM(cost_usd), 0.0) AS total_cost_usd,
+         COUNT(*) AS call_count,
+         COALESCE(SUM(tool_calls), 0) AS total_tool_calls
+       FROM usage_events
+       ${where}
+       GROUP BY model
+       ORDER BY total_cost_usd DESC, total_tokens DESC, call_count DESC`)
+        .all(...args);
+    return rows.map((row) => ({
+        model: row.model,
+        total_input_tokens: normalizeUsageNumber(row.total_input_tokens),
+        total_output_tokens: normalizeUsageNumber(row.total_output_tokens),
+        total_tokens: normalizeUsageNumber(row.total_tokens),
+        total_cost_usd: normalizeUsageCost(row.total_cost_usd),
+        call_count: normalizeUsageNumber(row.call_count),
+        total_tool_calls: normalizeUsageNumber(row.total_tool_calls),
+    }));
+}
+export function listUsageByAgent(params) {
+    const whereClauses = [];
+    const args = [];
+    applyUsageFilters({
+        whereClauses,
+        args,
+        window: params?.window,
+    });
+    const where = whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : '';
+    const rows = db
+        .prepare(`SELECT
+         agent_id,
+         COALESCE(SUM(input_tokens), 0) AS total_input_tokens,
+         COALESCE(SUM(output_tokens), 0) AS total_output_tokens,
+         COALESCE(SUM(total_tokens), 0) AS total_tokens,
+         COALESCE(SUM(cost_usd), 0.0) AS total_cost_usd,
+         COUNT(*) AS call_count,
+         COALESCE(SUM(tool_calls), 0) AS total_tool_calls
+       FROM usage_events
+       ${where}
+       GROUP BY agent_id
+       ORDER BY total_cost_usd DESC, total_tokens DESC, call_count DESC`)
+        .all(...args);
+    return rows.map((row) => ({
+        agent_id: row.agent_id,
+        total_input_tokens: normalizeUsageNumber(row.total_input_tokens),
+        total_output_tokens: normalizeUsageNumber(row.total_output_tokens),
+        total_tokens: normalizeUsageNumber(row.total_tokens),
+        total_cost_usd: normalizeUsageCost(row.total_cost_usd),
+        call_count: normalizeUsageNumber(row.call_count),
+        total_tool_calls: normalizeUsageNumber(row.total_tool_calls),
+    }));
+}
+export function listUsageDailyBreakdown(params) {
+    const days = Math.max(1, Math.min(365, Math.floor(params?.days || 30)));
+    const whereClauses = [
+        `timestamp >= datetime('now', '-${days} days')`,
+    ];
+    const args = [];
+    const agentId = params?.agentId?.trim();
+    if (agentId) {
+        whereClauses.push('agent_id = ?');
+        args.push(agentId);
+    }
+    const rows = db
+        .prepare(`SELECT
+         date(timestamp) AS day,
+         COALESCE(SUM(input_tokens), 0) AS total_input_tokens,
+         COALESCE(SUM(output_tokens), 0) AS total_output_tokens,
+         COALESCE(SUM(total_tokens), 0) AS total_tokens,
+         COALESCE(SUM(cost_usd), 0.0) AS total_cost_usd,
+         COUNT(*) AS call_count,
+         COALESCE(SUM(tool_calls), 0) AS total_tool_calls
+       FROM usage_events
+       WHERE ${whereClauses.join(' AND ')}
+       GROUP BY day
+       ORDER BY day ASC`)
+        .all(...args);
+    return rows.map((row) => ({
+        day: row.day,
+        total_input_tokens: normalizeUsageNumber(row.total_input_tokens),
+        total_output_tokens: normalizeUsageNumber(row.total_output_tokens),
+        total_tokens: normalizeUsageNumber(row.total_tokens),
+        total_cost_usd: normalizeUsageCost(row.total_cost_usd),
+        call_count: normalizeUsageNumber(row.call_count),
+        total_tool_calls: normalizeUsageNumber(row.total_tool_calls),
+    }));
+}
+function normalizeKnowledgeCustomValue(raw) {
+    const value = raw.trim().toLowerCase();
+    return value || 'unknown';
+}
+function normalizeEntityType(entityType) {
+    if (typeof entityType === 'object' && entityType) {
+        if (typeof entityType.custom === 'string') {
+            return { custom: normalizeKnowledgeCustomValue(entityType.custom) };
+        }
+        return { custom: 'unknown' };
+    }
+    const normalized = normalizeKnowledgeCustomValue(entityType);
+    switch (normalized) {
+        case 'person':
+            return KnowledgeEntityType.Person;
+        case 'organization':
+        case 'org':
+            return KnowledgeEntityType.Organization;
+        case 'project':
+            return KnowledgeEntityType.Project;
+        case 'concept':
+            return KnowledgeEntityType.Concept;
+        case 'event':
+            return KnowledgeEntityType.Event;
+        case 'location':
+            return KnowledgeEntityType.Location;
+        case 'document':
+        case 'doc':
+            return KnowledgeEntityType.Document;
+        case 'tool':
+            return KnowledgeEntityType.Tool;
+        default:
+            return { custom: normalized };
+    }
+}
+function normalizeRelationType(relation) {
+    if (typeof relation === 'object' && relation) {
+        if (typeof relation.custom === 'string') {
+            return { custom: normalizeKnowledgeCustomValue(relation.custom) };
+        }
+        return { custom: 'unknown' };
+    }
+    const normalized = normalizeKnowledgeCustomValue(relation)
+        .replace(/[\s-]+/g, '_')
+        .replace(/_+/g, '_');
+    switch (normalized) {
+        case 'works_at':
+        case 'worksat':
+            return KnowledgeRelationType.WorksAt;
+        case 'knows_about':
+        case 'knowsabout':
+        case 'knows':
+            return KnowledgeRelationType.KnowsAbout;
+        case 'related_to':
+        case 'relatedto':
+        case 'related':
+            return KnowledgeRelationType.RelatedTo;
+        case 'depends_on':
+        case 'dependson':
+        case 'depends':
+            return KnowledgeRelationType.DependsOn;
+        case 'owned_by':
+        case 'ownedby':
+            return KnowledgeRelationType.OwnedBy;
+        case 'created_by':
+        case 'createdby':
+            return KnowledgeRelationType.CreatedBy;
+        case 'located_in':
+        case 'locatedin':
+            return KnowledgeRelationType.LocatedIn;
+        case 'part_of':
+        case 'partof':
+            return KnowledgeRelationType.PartOf;
+        case 'uses':
+            return KnowledgeRelationType.Uses;
+        case 'produces':
+            return KnowledgeRelationType.Produces;
+        default:
+            return { custom: normalized };
+    }
+}
+function serializeEntityType(entityType) {
+    const normalized = normalizeEntityType(entityType);
+    return typeof normalized === 'string'
+        ? JSON.stringify(normalized)
+        : JSON.stringify({ custom: normalized.custom });
+}
+function serializeRelationType(relation) {
+    const normalized = normalizeRelationType(relation);
+    return typeof normalized === 'string'
+        ? JSON.stringify(normalized)
+        : JSON.stringify({ custom: normalized.custom });
+}
+function parseEntityType(raw) {
+    const value = (raw || '').trim();
+    if (!value)
+        return { custom: 'unknown' };
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed === 'string')
+            return normalizeEntityType(parsed);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            typeof parsed.custom === 'string') {
+            return normalizeEntityType({
+                custom: parsed.custom,
+            });
+        }
+    }
+    catch {
+        return normalizeEntityType(value);
+    }
+    return { custom: 'unknown' };
+}
+function parseRelationType(raw) {
+    const value = (raw || '').trim();
+    if (!value)
+        return { custom: 'unknown' };
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed === 'string')
+            return normalizeRelationType(parsed);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            typeof parsed.custom === 'string') {
+            return normalizeRelationType({
+                custom: parsed.custom,
+            });
+        }
+    }
+    catch {
+        return normalizeRelationType(value);
+    }
+    return { custom: 'unknown' };
+}
+function serializeKnowledgeProperties(properties) {
+    if (!properties ||
+        typeof properties !== 'object' ||
+        Array.isArray(properties)) {
+        return '{}';
+    }
+    try {
+        return JSON.stringify(properties);
+    }
+    catch {
+        return '{}';
+    }
+}
+function parseKnowledgeProperties(raw) {
+    const text = Buffer.isBuffer(raw)
+        ? raw.toString('utf8')
+        : raw instanceof Uint8Array
+            ? Buffer.from(raw).toString('utf8')
+            : typeof raw === 'string'
+                ? raw
+                : '{}';
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+function mapKnowledgeEntity(params) {
+    return {
+        id: params.id,
+        entity_type: parseEntityType(params.entityTypeRaw),
+        name: params.name,
+        properties: parseKnowledgeProperties(params.propertiesRaw),
+        created_at: params.createdAt,
+        updated_at: params.updatedAt,
+    };
+}
+function mapKnowledgeMatchRow(row) {
+    return {
+        source: mapKnowledgeEntity({
+            id: row.s_id,
+            entityTypeRaw: row.s_type,
+            name: row.s_name,
+            propertiesRaw: row.s_properties,
+            createdAt: row.s_created_at,
+            updatedAt: row.s_updated_at,
+        }),
+        relation: {
+            source: row.r_source,
+            relation: parseRelationType(row.r_type),
+            target: row.r_target,
+            properties: parseKnowledgeProperties(row.r_properties),
+            confidence: Math.max(0, Math.min(1, Number(row.r_confidence) || 0)),
+            created_at: row.r_created_at,
+        },
+        target: mapKnowledgeEntity({
+            id: row.t_id,
+            entityTypeRaw: row.t_type,
+            name: row.t_name,
+            propertiesRaw: row.t_properties,
+            createdAt: row.t_created_at,
+            updatedAt: row.t_updated_at,
+        }),
+    };
+}
+export function addKnowledgeEntity(params) {
+    const name = params.name.trim();
+    if (!name)
+        throw new Error('Knowledge graph entity name is required');
+    const entityId = params.id?.trim() || randomUUID();
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO entities (id, entity_type, name, properties, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       name = excluded.name,
+       properties = excluded.properties,
+       updated_at = excluded.updated_at`).run(entityId, serializeEntityType(params.entityType), name, serializeKnowledgeProperties(params.properties), now, now);
+    return entityId;
+}
+export function addKnowledgeRelation(params) {
+    const source = params.source.trim();
+    const target = params.target.trim();
+    if (!source)
+        throw new Error('Knowledge graph relation source is required');
+    if (!target)
+        throw new Error('Knowledge graph relation target is required');
+    const id = randomUUID();
+    const rawConfidence = typeof params.confidence === 'number' && Number.isFinite(params.confidence)
+        ? params.confidence
+        : 1;
+    const confidence = Math.max(0, Math.min(1, rawConfidence));
+    db.prepare(`INSERT INTO relations
+      (id, source_entity, relation_type, target_entity, properties, confidence, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(id, source, serializeRelationType(params.relation), target, serializeKnowledgeProperties(params.properties), confidence, new Date().toISOString());
+    return id;
+}
+export function queryKnowledgeGraph(pattern = {}) {
+    const sql = [
+        `SELECT
+       s.id AS s_id,
+       s.entity_type AS s_type,
+       s.name AS s_name,
+       s.properties AS s_properties,
+       s.created_at AS s_created_at,
+       s.updated_at AS s_updated_at,
+       r.id AS r_id,
+       r.source_entity AS r_source,
+       r.relation_type AS r_type,
+       r.target_entity AS r_target,
+       r.properties AS r_properties,
+       r.confidence AS r_confidence,
+       r.created_at AS r_created_at,
+       t.id AS t_id,
+       t.entity_type AS t_type,
+       t.name AS t_name,
+       t.properties AS t_properties,
+       t.created_at AS t_created_at,
+       t.updated_at AS t_updated_at
+     FROM relations r
+     JOIN entities s ON r.source_entity = s.id
+     JOIN entities t ON r.target_entity = t.id
+     WHERE 1 = 1`,
+    ];
+    const args = [];
+    const source = pattern.source?.trim();
+    if (source) {
+        sql.push('AND (s.id = ? OR s.name = ?)');
+        args.push(source, source);
+    }
+    if (pattern.relation) {
+        sql.push('AND r.relation_type = ?');
+        args.push(serializeRelationType(pattern.relation));
+    }
+    const target = pattern.target?.trim();
+    if (target) {
+        sql.push('AND (t.id = ? OR t.name = ?)');
+        args.push(target, target);
+    }
+    // OpenFang-compatible v1 query semantics: single-hop relation scan, max 100.
+    sql.push('LIMIT 100');
+    const rows = db
+        .prepare(sql.join('\n'))
+        .all(...args);
+    return rows.map(mapKnowledgeMatchRow);
+}
 // --- Sessions ---
 export function getOrCreateSession(sessionId, guildId, channelId) {
     const existing = getSessionById(sessionId);
     if (existing) {
-        db.prepare('UPDATE sessions SET last_active = datetime(\'now\') WHERE id = ?').run(sessionId);
+        db.prepare("UPDATE sessions SET last_active = datetime('now') WHERE id = ?").run(sessionId);
         return existing;
     }
     db.prepare('INSERT INTO sessions (id, guild_id, channel_id) VALUES (?, ?, ?)').run(sessionId, guildId, channelId);
     return getSessionById(sessionId);
 }
 export function getSessionById(sessionId) {
-    return db
-        .prepare('SELECT * FROM sessions WHERE id = ?')
-        .get(sessionId);
+    return db.prepare('SELECT * FROM sessions WHERE id = ?').get(sessionId);
 }
 export function updateSessionChatbot(sessionId, chatbotId) {
     db.prepare('UPDATE sessions SET chatbot_id = ? WHERE id = ?').run(chatbotId, sessionId);
@@ -179,27 +1208,488 @@ export function updateSessionRag(sessionId, enableRag) {
     db.prepare('UPDATE sessions SET enable_rag = ? WHERE id = ?').run(enableRag ? 1 : 0, sessionId);
 }
 export function getAllSessions() {
-    return db.prepare('SELECT * FROM sessions ORDER BY last_active DESC').all();
+    return db
+        .prepare('SELECT * FROM sessions ORDER BY last_active DESC')
+        .all();
 }
 export function getSessionCount() {
     const row = db.prepare('SELECT COUNT(*) as count FROM sessions').get();
     return row.count;
 }
+export function getMostRecentSessionChannelId() {
+    const row = db
+        .prepare('SELECT channel_id FROM sessions ORDER BY last_active DESC LIMIT 1')
+        .get();
+    if (!row || typeof row.channel_id !== 'string')
+        return null;
+    const channelId = row.channel_id.trim();
+    return channelId || null;
+}
 export function clearSessionHistory(sessionId) {
-    const result = db.prepare('DELETE FROM messages WHERE session_id = ?').run(sessionId);
+    const result = db
+        .prepare('DELETE FROM messages WHERE session_id = ?')
+        .run(sessionId);
+    db.prepare('DELETE FROM semantic_memories WHERE session_id = ?').run(sessionId);
     db.prepare('UPDATE sessions SET message_count = 0, session_summary = NULL, summary_updated_at = NULL, compaction_count = 0, memory_flush_at = NULL WHERE id = ?').run(sessionId);
     return result.changes;
 }
 // --- Messages ---
 export function storeMessage(sessionId, userId, username, role, content) {
-    db.prepare('INSERT INTO messages (session_id, user_id, username, role, content) VALUES (?, ?, ?, ?, ?)').run(sessionId, userId, username, role, content);
-    db.prepare('UPDATE sessions SET message_count = message_count + 1, last_active = datetime(\'now\') WHERE id = ?').run(sessionId);
+    const result = db
+        .prepare('INSERT INTO messages (session_id, user_id, username, role, content) VALUES (?, ?, ?, ?, ?)')
+        .run(sessionId, userId, username, role, content);
+    db.prepare("UPDATE sessions SET message_count = message_count + 1, last_active = datetime('now') WHERE id = ?").run(sessionId);
+    return result.lastInsertRowid;
 }
 export function getConversationHistory(sessionId, limit = 50) {
     return db
         .prepare('SELECT * FROM messages WHERE session_id = ? ORDER BY id DESC LIMIT ?')
         .all(sessionId, limit);
 }
+export function getRecentMessages(sessionId, limit) {
+    const boundedLimit = typeof limit === 'number' && Number.isFinite(limit)
+        ? Math.max(1, Math.floor(limit))
+        : null;
+    if (boundedLimit == null) {
+        return db
+            .prepare('SELECT * FROM messages WHERE session_id = ? ORDER BY id ASC')
+            .all(sessionId);
+    }
+    const rows = db
+        .prepare('SELECT * FROM messages WHERE session_id = ? ORDER BY id DESC LIMIT ?')
+        .all(sessionId, boundedLimit);
+    return rows.reverse();
+}
+function parseTimestamp(raw) {
+    const value = raw.trim();
+    if (!value)
+        return 0;
+    if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value)) {
+        const parsed = Date.parse(`${value.replace(' ', 'T')}Z`);
+        return Number.isNaN(parsed) ? 0 : parsed;
+    }
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function parseQueryTerms(query) {
+    const lower = query
+        .toLowerCase()
+        .split(/[^a-z0-9_-]+/g)
+        .map((term) => term.trim())
+        .filter((term) => term.length >= 2);
+    if (lower.length === 0)
+        return [];
+    const unique = new Set();
+    for (const term of lower) {
+        unique.add(term);
+        if (unique.size >= 8)
+            break;
+    }
+    return [...unique];
+}
+const MAX_EMBEDDING_DIMENSIONS = 2048;
+function normalizeEmbeddingInput(embedding) {
+    if (!Array.isArray(embedding) || embedding.length === 0)
+        return null;
+    if (embedding.length > MAX_EMBEDDING_DIMENSIONS)
+        return null;
+    const values = [];
+    for (const value of embedding) {
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            return null;
+        values.push(value);
+    }
+    if (values.length === 0)
+        return null;
+    return new Float32Array(values);
+}
+function embeddingToBlob(embedding) {
+    const buffer = Buffer.allocUnsafe(embedding.length * 4);
+    for (let i = 0; i < embedding.length; i += 1) {
+        buffer.writeFloatLE(embedding[i], i * 4);
+    }
+    return buffer;
+}
+function embeddingFromBlob(raw) {
+    if (!raw)
+        return null;
+    const bytes = Buffer.isBuffer(raw)
+        ? raw
+        : raw instanceof Uint8Array
+            ? Buffer.from(raw)
+            : null;
+    if (!bytes || bytes.length === 0 || bytes.length % 4 !== 0)
+        return null;
+    const values = [];
+    for (let i = 0; i < bytes.length; i += 4) {
+        values.push(bytes.readFloatLE(i));
+    }
+    return values.length > 0 ? values : null;
+}
+function cosineSimilarity(a, b) {
+    if (a.length === 0 || b.length === 0 || a.length !== b.length)
+        return -1;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        const bv = b[i];
+        if (!Number.isFinite(bv))
+            return -1;
+        dot += a[i] * bv;
+        normA += a[i] * a[i];
+        normB += bv * bv;
+    }
+    if (normA <= Number.EPSILON || normB <= Number.EPSILON)
+        return -1;
+    return dot / Math.sqrt(normA * normB);
+}
+function scoreSemanticLikeCandidate(row, normalizedQuery, queryTerms) {
+    const content = row.content.toLowerCase();
+    let score = 0;
+    if (content.includes(normalizedQuery))
+        score += 8;
+    if (content.startsWith(normalizedQuery))
+        score += 3;
+    let termHits = 0;
+    for (const term of queryTerms) {
+        if (content.includes(term))
+            termHits += 1;
+    }
+    score += termHits * 2;
+    score += Math.max(0, Math.min(1, row.confidence)) * 4;
+    const hoursSinceAccess = Math.max(0, (Date.now() - parseTimestamp(row.accessed_at)) / 3_600_000);
+    if (hoursSinceAccess < 24)
+        score += 1;
+    return score;
+}
+function parseSemanticMetadata(raw) {
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+function serializeSemanticMetadata(metadata) {
+    try {
+        return JSON.stringify(metadata);
+    }
+    catch {
+        return '{}';
+    }
+}
+function mapSemanticMemoryRow(row) {
+    return {
+        id: row.id,
+        session_id: row.session_id,
+        role: row.role,
+        source: (row.source || '').trim() || 'conversation',
+        scope: (row.scope || '').trim() || 'episodic',
+        metadata: parseSemanticMetadata(row.metadata),
+        content: row.content,
+        confidence: row.confidence,
+        embedding: embeddingFromBlob(row.embedding),
+        source_message_id: row.source_message_id,
+        created_at: row.created_at,
+        accessed_at: row.accessed_at,
+        access_count: row.access_count,
+    };
+}
+function touchSemanticMemoryRows(entries) {
+    if (entries.length === 0)
+        return;
+    const touch = db.prepare(`UPDATE semantic_memories
+     SET access_count = access_count + 1,
+         accessed_at = datetime('now')
+     WHERE id = ?
+       AND deleted = 0`);
+    const transaction = db.transaction((rows) => {
+        for (const row of rows) {
+            touch.run(row.id);
+        }
+    });
+    transaction(entries);
+}
+export function touchSemanticMemories(ids) {
+    const uniqueIds = [
+        ...new Set(ids.map((id) => Math.floor(id)).filter((id) => id > 0)),
+    ];
+    if (uniqueIds.length === 0)
+        return;
+    const touch = db.prepare(`UPDATE semantic_memories
+     SET access_count = access_count + 1,
+         accessed_at = datetime('now')
+     WHERE id = ?
+       AND deleted = 0`);
+    const transaction = db.transaction((rowIds) => {
+        for (const id of rowIds) {
+            touch.run(id);
+        }
+    });
+    transaction(uniqueIds);
+}
+function applySemanticRecallFilterClauses(params) {
+    if (!params.filter)
+        return;
+    const role = params.filter.role?.trim();
+    if (role) {
+        params.whereClauses.push('role = ?');
+        params.args.push(role);
+    }
+    const source = params.filter.source?.trim();
+    if (source) {
+        params.whereClauses.push('source = ?');
+        params.args.push(source);
+    }
+    const scope = params.filter.scope?.trim();
+    if (scope) {
+        params.whereClauses.push('scope = ?');
+        params.args.push(scope);
+    }
+    const after = params.filter.after?.trim();
+    if (after) {
+        params.whereClauses.push('created_at >= ?');
+        params.args.push(after);
+    }
+    const before = params.filter.before?.trim();
+    if (before) {
+        params.whereClauses.push('created_at <= ?');
+        params.args.push(before);
+    }
+}
+function recallSemanticMemoriesByLike(params) {
+    if (params.queryTerms.length === 0)
+        return [];
+    const candidateLimit = Math.max(params.limit * 8, 50);
+    const likePatterns = params.queryTerms.map((term) => `%${term}%`);
+    const placeholders = likePatterns
+        .map(() => 'LOWER(content) LIKE ?')
+        .join(' OR ');
+    const whereClauses = [
+        'session_id = ?',
+        'deleted = 0',
+        'confidence >= ?',
+        `(${placeholders})`,
+    ];
+    const args = [
+        params.sessionId,
+        params.minConfidence,
+        ...likePatterns,
+    ];
+    applySemanticRecallFilterClauses({
+        whereClauses,
+        args,
+        filter: params.filter,
+    });
+    args.push(candidateLimit);
+    const rawRows = db
+        .prepare(`SELECT *
+       FROM semantic_memories
+       WHERE ${whereClauses.join('\n         AND ')}
+       ORDER BY confidence DESC, accessed_at DESC
+       LIMIT ?`)
+        .all(...args);
+    if (rawRows.length === 0)
+        return [];
+    const ranked = rawRows
+        .map(mapSemanticMemoryRow)
+        .map((row) => ({
+        row,
+        score: scoreSemanticLikeCandidate(row, params.normalizedQuery, params.queryTerms),
+    }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (b.row.confidence !== a.row.confidence) {
+            return b.row.confidence - a.row.confidence;
+        }
+        return (parseTimestamp(b.row.accessed_at) - parseTimestamp(a.row.accessed_at));
+    })
+        .slice(0, params.limit)
+        .map((entry) => entry.row);
+    touchSemanticMemoryRows(ranked);
+    return ranked;
+}
+function recallSemanticMemoriesByVector(params) {
+    const candidateLimit = Math.max(params.limit * 10, 100);
+    const whereClauses = [
+        'session_id = ?',
+        'deleted = 0',
+        'confidence >= ?',
+    ];
+    const args = [params.sessionId, params.minConfidence];
+    applySemanticRecallFilterClauses({
+        whereClauses,
+        args,
+        filter: params.filter,
+    });
+    args.push(candidateLimit);
+    const rawRows = db
+        .prepare(`SELECT *
+       FROM semantic_memories
+       WHERE ${whereClauses.join('\n         AND ')}
+       ORDER BY accessed_at DESC, confidence DESC
+       LIMIT ?`)
+        .all(...args);
+    if (rawRows.length === 0)
+        return [];
+    const rows = rawRows.map(mapSemanticMemoryRow);
+    const ranked = rows
+        .map((row) => {
+        const similarity = row.embedding
+            ? cosineSimilarity(params.queryEmbedding, row.embedding)
+            : -1;
+        return {
+            row,
+            similarity,
+        };
+    })
+        .sort((a, b) => {
+        if (b.similarity !== a.similarity)
+            return b.similarity - a.similarity;
+        if (b.row.confidence !== a.row.confidence) {
+            return b.row.confidence - a.row.confidence;
+        }
+        return (parseTimestamp(b.row.accessed_at) - parseTimestamp(a.row.accessed_at));
+    })
+        .slice(0, params.limit)
+        .map((entry) => entry.row);
+    touchSemanticMemoryRows(ranked);
+    return ranked;
+}
+function recallSemanticMemoriesByRecent(params) {
+    const whereClauses = [
+        'session_id = ?',
+        'deleted = 0',
+        'confidence >= ?',
+    ];
+    const args = [params.sessionId, params.minConfidence];
+    applySemanticRecallFilterClauses({
+        whereClauses,
+        args,
+        filter: params.filter,
+    });
+    args.push(params.limit);
+    const rows = db
+        .prepare(`SELECT *
+       FROM semantic_memories
+       WHERE ${whereClauses.join('\n         AND ')}
+       ORDER BY accessed_at DESC, confidence DESC
+       LIMIT ?`)
+        .all(...args);
+    const mapped = rows.map(mapSemanticMemoryRow);
+    touchSemanticMemoryRows(mapped);
+    return mapped;
+}
+export function storeSemanticMemory(params) {
+    const normalizedContent = params.content.trim();
+    const source = (params.source || '').trim() || 'conversation';
+    const scope = (params.scope || '').trim() || 'episodic';
+    const metadata = typeof params.metadata === 'string'
+        ? parseSemanticMetadata(params.metadata)
+        : params.metadata && typeof params.metadata === 'object'
+            ? params.metadata
+            : {};
+    const metadataJson = serializeSemanticMetadata(metadata);
+    const deleted = params.deleted === true || params.deleted === 1 ? 1 : 0;
+    const rawConfidence = typeof params.confidence === 'number' && Number.isFinite(params.confidence)
+        ? params.confidence
+        : 1;
+    const boundedConfidence = Math.max(0, Math.min(1, rawConfidence));
+    const normalizedEmbedding = normalizeEmbeddingInput(params.embedding);
+    const embeddingBlob = normalizedEmbedding
+        ? embeddingToBlob(normalizedEmbedding)
+        : null;
+    const createdAt = params.createdAt?.trim() || null;
+    const accessedAt = params.accessedAt?.trim() || createdAt || null;
+    const result = db
+        .prepare(`INSERT INTO semantic_memories
+       (session_id, role, source, scope, metadata, content, confidence, embedding, source_message_id, created_at, accessed_at, access_count, deleted)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, COALESCE(?, datetime('now')), COALESCE(?, datetime('now')), 0, ?)`)
+        .run(params.sessionId, params.role, source, scope, metadataJson, normalizedContent, boundedConfidence, embeddingBlob, params.sourceMessageId ?? null, createdAt, accessedAt, deleted);
+    return result.lastInsertRowid;
+}
+export function recallSemanticMemories(params) {
+    const normalizedQuery = params.query.trim().toLowerCase();
+    const queryTerms = parseQueryTerms(normalizedQuery);
+    const queryEmbedding = normalizeEmbeddingInput(params.queryEmbedding);
+    const limit = Math.max(1, Math.min(Math.floor(params.limit || 5), 50));
+    const rawMinConfidence = typeof params.minConfidence === 'number' &&
+        Number.isFinite(params.minConfidence)
+        ? params.minConfidence
+        : 0.2;
+    const minConfidence = Math.max(0, Math.min(1, rawMinConfidence));
+    if (!queryEmbedding && queryTerms.length === 0) {
+        return recallSemanticMemoriesByRecent({
+            sessionId: params.sessionId,
+            limit,
+            minConfidence,
+            filter: params.filter,
+        });
+    }
+    if (queryEmbedding) {
+        return recallSemanticMemoriesByVector({
+            sessionId: params.sessionId,
+            queryEmbedding,
+            limit,
+            minConfidence,
+            filter: params.filter,
+        });
+    }
+    return recallSemanticMemoriesByLike({
+        sessionId: params.sessionId,
+        normalizedQuery,
+        queryTerms,
+        limit,
+        minConfidence,
+        filter: params.filter,
+    });
+}
+export function forgetSemanticMemory(id) {
+    const normalizedId = Math.floor(id);
+    if (!Number.isFinite(normalizedId) || normalizedId <= 0)
+        return false;
+    const result = db
+        .prepare(`UPDATE semantic_memories
+       SET deleted = 1
+       WHERE id = ?
+         AND deleted = 0`)
+        .run(normalizedId);
+    return result.changes > 0;
+}
+export function decaySemanticMemories(params) {
+    const rawDecayRate = typeof params?.decayRate === 'number' && Number.isFinite(params.decayRate)
+        ? params.decayRate
+        : 0.1;
+    const decayRate = Math.max(0, Math.min(0.95, rawDecayRate));
+    const decayFactor = 1 - decayRate;
+    const rawStaleAfterDays = typeof params?.staleAfterDays === 'number' &&
+        Number.isFinite(params.staleAfterDays)
+        ? params.staleAfterDays
+        : 7;
+    const staleAfterDays = Math.max(1, Math.min(365, Math.floor(rawStaleAfterDays)));
+    const rawMinConfidence = typeof params?.minConfidence === 'number' &&
+        Number.isFinite(params.minConfidence)
+        ? params.minConfidence
+        : 0.1;
+    const minConfidence = Math.max(0, Math.min(0.95, rawMinConfidence));
+    const cutoff = `-${staleAfterDays} days`;
+    const result = db
+        .prepare(`UPDATE semantic_memories
+       SET confidence = MAX(?, confidence * ?)
+       WHERE deleted = 0
+         AND confidence > ?
+         AND accessed_at < datetime('now', ?)`)
+        .run(minConfidence, decayFactor, minConfidence, cutoff);
+    return result.changes;
+}
 export function getCompactionCandidateMessages(sessionId, keepRecent) {
     const keep = Math.max(1, Math.floor(keepRecent));
     const cutoffRow = db
@@ -221,19 +1711,21 @@ export function deleteMessagesBeforeId(sessionId, cutoffId) {
     const result = db
         .prepare('DELETE FROM messages WHERE session_id = ? AND id < ?')
         .run(sessionId, cutoffId);
-    db.prepare('UPDATE sessions SET message_count = (SELECT COUNT(*) FROM messages WHERE session_id = ?), last_active = datetime(\'now\') WHERE id = ?').run(sessionId, sessionId);
+    db.prepare("UPDATE sessions SET message_count = (SELECT COUNT(*) FROM messages WHERE session_id = ?), last_active = datetime('now') WHERE id = ?").run(sessionId, sessionId);
     return result.changes;
 }
 export function updateSessionSummary(sessionId, summary) {
     const normalized = summary.trim();
-    db.prepare('UPDATE sessions SET session_summary = ?, summary_updated_at = datetime(\'now\'), compaction_count = compaction_count + 1 WHERE id = ?').run(normalized || null, sessionId);
+    db.prepare("UPDATE sessions SET session_summary = ?, summary_updated_at = datetime('now'), compaction_count = compaction_count + 1 WHERE id = ?").run(normalized || null, sessionId);
 }
 export function markSessionMemoryFlush(sessionId) {
-    db.prepare('UPDATE sessions SET memory_flush_at = datetime(\'now\') WHERE id = ?').run(sessionId);
+    db.prepare("UPDATE sessions SET memory_flush_at = datetime('now') WHERE id = ?").run(sessionId);
 }
 // --- Tasks ---
 export function createTask(sessionId, channelId, cronExpr, prompt, runAt, everyMs) {
-    const result = db.prepare('INSERT INTO tasks (session_id, channel_id, cron_expr, prompt, run_at, every_ms) VALUES (?, ?, ?, ?, ?, ?)').run(sessionId, channelId, cronExpr, prompt, runAt || null, everyMs || null);
+    const result = db
+        .prepare('INSERT INTO tasks (session_id, channel_id, cron_expr, prompt, run_at, every_ms) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(sessionId, channelId, cronExpr, prompt, runAt || null, everyMs || null);
     return result.lastInsertRowid;
 }
 export function getTasksForSession(sessionId) {
@@ -242,14 +1734,40 @@ export function getTasksForSession(sessionId) {
         .all(sessionId);
 }
 export function getAllEnabledTasks() {
-    return db.prepare('SELECT * FROM tasks WHERE enabled = 1').all();
+    return db
+        .prepare('SELECT * FROM tasks WHERE enabled = 1')
+        .all();
 }
 export function updateTaskLastRun(taskId) {
-    db.prepare('UPDATE tasks SET last_run = datetime(\'now\') WHERE id = ?').run(taskId);
+    db.prepare("UPDATE tasks SET last_run = datetime('now') WHERE id = ?").run(taskId);
+}
+export function markTaskSuccess(taskId) {
+    db.prepare('UPDATE tasks SET last_status = ?, consecutive_errors = 0 WHERE id = ?').run('success', taskId);
+}
+export function markTaskFailure(taskId, maxConsecutiveErrors = 5) {
+    const row = db
+        .prepare('SELECT consecutive_errors FROM tasks WHERE id = ?')
+        .get(taskId);
+    if (!row) {
+        return { disabled: false, consecutiveErrors: 0 };
+    }
+    const nextCount = Math.max(0, Math.floor(row.consecutive_errors || 0)) + 1;
+    const shouldDisable = nextCount >= Math.max(1, Math.floor(maxConsecutiveErrors));
+    db.prepare('UPDATE tasks SET last_status = ?, consecutive_errors = ?, enabled = ? WHERE id = ?').run('error', nextCount, shouldDisable ? 0 : 1, taskId);
+    return {
+        disabled: shouldDisable,
+        consecutiveErrors: nextCount,
+    };
 }
 export function toggleTask(taskId, enabled) {
     db.prepare('UPDATE tasks SET enabled = ? WHERE id = ?').run(enabled ? 1 : 0, taskId);
 }
+export function pauseTask(taskId) {
+    toggleTask(taskId, false);
+}
+export function resumeTask(taskId) {
+    toggleTask(taskId, true);
+}
 export function deleteTask(taskId) {
     db.prepare('DELETE FROM tasks WHERE id = ?').run(taskId);
 }
@@ -397,7 +1915,7 @@ export function deleteObservabilityIngestToken(tokenKey) {
 }
 export function enqueueProactiveMessage(channelId, text, source, maxQueueSize) {
     const boundedMax = Math.max(1, Math.floor(maxQueueSize));
-    db.prepare('INSERT INTO proactive_message_queue (channel_id, text, source, queued_at) VALUES (?, ?, ?, datetime(\'now\'))').run(channelId, text, source);
+    db.prepare("INSERT INTO proactive_message_queue (channel_id, text, source, queued_at) VALUES (?, ?, ?, datetime('now'))").run(channelId, text, source);
     const countRow = db
         .prepare('SELECT COUNT(*) as count FROM proactive_message_queue')
         .get();