qlogicagent 2.13.4 → 2.13.5

package/dist/skills/memory/local-store.js

@@ -0,0 +1,1022 @@
+/**
+ * Local Memory Store - SQLite-backed persistence for qmemory.
+ *
+ * Ported from Python qmemory's memory_store.py + db.py.
+ * Uses better-sqlite3 for synchronous, fast, single-file persistence.
+ *
+ * Storage location:
+ *   ~/.qlogicagent/profiles/<owner_user_id>/memory/memories.db
+ *
+ * Schema:
+ *   - memories: core fact storage with optional embedding blob
+ *   - memories_fts: FTS5 full-text index for keyword search
+ *   - profiles: user profile KV (future)
+ */
+import { randomUUID } from "node:crypto";
+import { dotProduct, normalizeVector } from "./memory-vector-utils.js";
+import { initializeMemorySchema } from "./sqlite-memory-schema.js";
+import { parseJsonArray, rowToClaimRecord, rowToConflictRecord, rowToRecord } from "./sqlite-memory-mappers.js";
+export { resolveMemoryDbPath } from "./memory-db-path.js";
+// Schema
+// LocalMemoryStore
+export class LocalMemoryStore {
+    db;
+    constructor(db) {
+        this.db = db;
+        this.initSchema();
+    }
+    initSchema() {
+        initializeMemorySchema(this.db);
+    }
+    /**
+     * Insert a new memory record. Returns the generated ID.
+     */
+    insert(input) {
+        const id = `mem_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+        const now = Date.now();
+        const tags = JSON.stringify(input.tags ?? []);
+        const embedding = input.embedding
+            ? Buffer.from(input.embedding.buffer, input.embedding.byteOffset, input.embedding.byteLength)
+            : null;
+        this.db.prepare(`
+      INSERT INTO memories (id, text, user_id, category, importance, confidence, source, session_id, event_date, tags, embedding, created_at, updated_at, last_accessed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.text, input.userId, input.category ?? "general", input.importance ?? 0.5, input.confidence ?? 1.0, input.source ?? "agent", input.sessionId ?? "", input.eventDate ?? "", tags, embedding, now, now, now);
+        return id;
+    }
+    /**
+     * Full-text search using FTS5. Returns ranked results.
+     */
+    searchFts(query, userId, limit = 10) {
+        const escaped = toFtsPhraseQuery(query);
+        if (!escaped)
+            return [];
+        const rows = this.db.prepare(`
+      SELECT m.id, m.text, m.category, m.importance, m.tags, m.created_at,
+             m.access_count, rank * -1.0 AS fts_score
+      FROM memories_fts fts
+      JOIN memories m ON m.id = fts.id
+      WHERE memories_fts MATCH ? AND m.user_id = ? AND m.is_archived = 0
+      ORDER BY rank
+      LIMIT ?
+    `).all(escaped, userId, limit);
+        return rows.map((r) => ({
+            id: r.id,
+            text: r.text,
+            score: Math.min(1.0, r.fts_score * 0.1 + r.importance * 0.5),
+            category: r.category,
+            importance: r.importance,
+            metadata: {
+                tags: JSON.parse(r.tags || "[]"),
+                createdAt: r.created_at,
+                accessCount: r.access_count,
+            },
+        }));
+    }
+    /**
+     * Vector similarity search using pre-computed embeddings.
+     * Performs brute-force cosine similarity (efficient for <100k records per user).
+     */
+    searchVector(queryEmbedding, userId, limit = 10, minScore = 0.3) {
+        const rows = this.db.prepare(`
+      SELECT id, text, category, importance, tags, created_at, access_count, embedding
+      FROM memories
+      WHERE user_id = ? AND is_archived = 0 AND embedding IS NOT NULL
+    `).all(userId);
+        const results = [];
+        const queryNorm = normalizeVector(queryEmbedding);
+        for (const row of rows) {
+            const docEmbedding = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4);
+            const docNorm = normalizeVector(docEmbedding);
+            const similarity = dotProduct(queryNorm, docNorm);
+            if (similarity >= minScore) {
+                results.push({
+                    id: row.id,
+                    text: row.text,
+                    score: similarity * 0.7 + row.importance * 0.3, // Blend similarity with importance
+                    category: row.category,
+                    importance: row.importance,
+                    metadata: {
+                        tags: JSON.parse(row.tags || "[]"),
+                        createdAt: row.created_at,
+                        accessCount: row.access_count,
+                        cosineSimilarity: similarity,
+                    },
+                });
+            }
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, limit);
+    }
+    /**
+     * Hybrid search: FTS5 + vector similarity, de-duplicated and merged.
+     */
+    searchHybrid(query, queryEmbedding, userId, limit = 10) {
+        const ftsResults = this.searchFts(query, userId, limit * 2);
+        if (!queryEmbedding)
+            return ftsResults.slice(0, limit);
+        const vectorResults = this.searchVector(queryEmbedding, userId, limit * 2);
+        // Merge with deduplication. A row found by BOTH signals (lexically AND
+        // semantically relevant) gets a combined score so it ranks above a row found
+        // by only one. Rows found by FTS only (e.g. no embedding) keep their FTS
+        // score and compete fairly — a strong lexical match still outranks a weak
+        // vector match, so non-embedded memories remain searchable, not buried.
+        const merged = new Map();
+        for (const hit of ftsResults) {
+            merged.set(hit.id, hit);
+        }
+        for (const hit of vectorResults) {
+            const existing = merged.get(hit.id);
+            if (!existing) {
+                merged.set(hit.id, hit);
+            }
+            else {
+                // Dual-signal: take the stronger base score plus a fraction of the
+                // weaker one (capped at 1.0). Keep the richer metadata (vector carries
+                // cosineSimilarity).
+                const base = Math.max(existing.score, hit.score);
+                const other = Math.min(existing.score, hit.score);
+                const combined = Math.min(1.0, base + other * 0.25);
+                const richer = hit.metadata?.cosineSimilarity != null ? hit : existing;
+                merged.set(hit.id, { ...richer, score: combined });
+            }
+        }
+        return Array.from(merged.values())
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    /**
+     * Get all memories for a user (paginated).
+     */
+    listByUser(userId, page = 1, pageSize = 50, activeOnly = true) {
+        const offset = (page - 1) * pageSize;
+        const archivedFilter = activeOnly ? "AND is_archived = 0" : "";
+        const rows = this.db.prepare(`
+      SELECT * FROM memories
+      WHERE user_id = ? ${archivedFilter}
+      ORDER BY created_at DESC
+      LIMIT ? OFFSET ?
+    `).all(userId, pageSize, offset);
+        return rows.map(rowToRecord);
+    }
+    /**
+     * Return a windowed atlas payload for large-history visualization.
+     *
+     * `records` are only the interactive window. `buckets` and `clusters` summarize
+     * the whole history so the UI can render distant history as star dust /
+     * aggregate galaxies without loading every memory as an interactive object.
+     */
+    getAtlas(userId, options) {
+        const activeOnly = options?.activeOnly ?? true;
+        const archivedFilter = activeOnly ? "AND is_archived = 0" : "";
+        const total = this.db.prepare(`
+      SELECT COUNT(*) AS count, MIN(created_at) AS startAt, MAX(created_at) AS endAt
+      FROM memories
+      WHERE user_id = ? ${archivedFilter}
+    `).get(userId);
+        const totalCount = Number(total?.count ?? 0);
+        if (totalCount === 0 || total.startAt == null || total.endAt == null) {
+            return {
+                totalCount: 0,
+                records: [],
+                buckets: [],
+                clusters: [],
+                windowCursor: null,
+                timeRange: null,
+            };
+        }
+        const startAt = Number(total.startAt);
+        const endAt = Math.max(startAt, Number(total.endAt));
+        const pageSize = Math.max(1, Math.min(800, Math.floor(options?.pageSize ?? 360)));
+        const requestedCenter = Number.isFinite(options?.windowCenterAt)
+            ? Number(options?.windowCenterAt)
+            : endAt;
+        const centerAt = Math.max(startAt, Math.min(endAt, requestedCenter));
+        const span = Math.max(1, endAt - startAt);
+        const defaultWindowSpan = Math.max(86_400_000, Math.ceil(span / 8));
+        let windowStartAt = Number.isFinite(options?.windowStartAt) ? Number(options?.windowStartAt) : centerAt - defaultWindowSpan / 2;
+        let windowEndAt = Number.isFinite(options?.windowEndAt) ? Number(options?.windowEndAt) : centerAt + defaultWindowSpan / 2;
+        if (windowEndAt < windowStartAt)
+            [windowStartAt, windowEndAt] = [windowEndAt, windowStartAt];
+        windowStartAt = Math.max(startAt, Math.floor(windowStartAt));
+        windowEndAt = Math.min(endAt, Math.ceil(windowEndAt));
+        if (windowEndAt <= windowStartAt) {
+            windowStartAt = Math.max(startAt, centerAt - defaultWindowSpan / 2);
+            windowEndAt = Math.min(endAt, centerAt + defaultWindowSpan / 2);
+        }
+        const records = this.db.prepare(`
+      SELECT id, text, user_id, category, importance, confidence, source, session_id, event_date,
+             tags, NULL AS embedding, created_at, updated_at, access_count, last_accessed_at, is_archived
+      FROM memories
+      WHERE user_id = ? ${archivedFilter}
+        AND created_at >= ?
+        AND created_at <= ?
+      ORDER BY created_at ASC, importance DESC
+      LIMIT ?
+    `).all(userId, windowStartAt, windowEndAt, pageSize);
+        return {
+            totalCount,
+            records: records.map(rowToRecord),
+            buckets: this.getAtlasBuckets(userId, startAt, endAt, options?.bucketCount ?? 96, activeOnly),
+            clusters: this.getAtlasClusters(userId, options?.clusterLimit ?? 48, activeOnly),
+            windowCursor: {
+                startAt: Math.floor(windowStartAt),
+                endAt: Math.ceil(windowEndAt),
+                centerAt: Math.floor(centerAt),
+                pageSize,
+                hasBefore: windowStartAt > startAt,
+                hasAfter: windowEndAt < endAt,
+            },
+            timeRange: { startAt, endAt },
+        };
+    }
+    getAtlasBuckets(userId, startAt, endAt, requestedBucketCount, activeOnly) {
+        const bucketCount = Math.max(12, Math.min(180, Math.floor(requestedBucketCount || 96)));
+        const span = Math.max(1, endAt - startAt + 1);
+        const step = Math.max(1, Math.ceil(span / bucketCount));
+        const archivedFilter = activeOnly ? "AND is_archived = 0" : "";
+        const aggregates = this.db.prepare(`
+      SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket,
+             COUNT(*) AS count,
+             AVG(importance) AS avgImportance,
+             AVG(confidence) AS avgConfidence,
+             MIN(created_at) AS minCreatedAt,
+             MAX(created_at) AS maxCreatedAt
+      FROM memories
+      WHERE user_id = ? ${archivedFilter}
+      GROUP BY bucket
+      ORDER BY bucket ASC
+    `).all(startAt, step, userId);
+        const categories = this.db.prepare(`
+      SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket,
+             category,
+             COUNT(*) AS count
+      FROM memories
+      WHERE user_id = ? ${archivedFilter}
+      GROUP BY bucket, category
+      ORDER BY bucket ASC, count DESC
+    `).all(startAt, step, userId);
+        const topCategory = new Map();
+        for (const row of categories) {
+            const bucket = Number(row.bucket);
+            if (!topCategory.has(bucket))
+                topCategory.set(bucket, String(row.category || "general"));
+        }
+        return aggregates.map((row) => {
+            const bucket = Number(row.bucket);
+            const bucketStart = startAt + bucket * step;
+            return {
+                id: `bucket:${bucket}`,
+                startAt: Number(row.minCreatedAt ?? bucketStart),
+                endAt: Number(row.maxCreatedAt ?? Math.min(endAt, bucketStart + step - 1)),
+                count: Number(row.count ?? 0),
+                avgImportance: Number(row.avgImportance ?? 0),
+                avgConfidence: Number(row.avgConfidence ?? 0),
+                topCategory: topCategory.get(bucket) ?? "general",
+            };
+        });
+    }
+    getAtlasClusters(userId, limit, activeOnly) {
+        const archivedFilter = activeOnly ? "AND is_archived = 0" : "";
+        const clusterLimit = Math.max(8, Math.min(120, Math.floor(limit || 48)));
+        const sourceRows = this.db.prepare(`
+      SELECT source AS label,
+             COUNT(*) AS count,
+             MIN(created_at) AS startAt,
+             MAX(created_at) AS endAt,
+             AVG(importance) AS avgImportance,
+             AVG(confidence) AS avgConfidence
+      FROM memories
+      WHERE user_id = ? ${archivedFilter} AND source != ''
+      GROUP BY source
+      HAVING count > 1
+      ORDER BY count DESC, avgImportance DESC
+      LIMIT ?
+    `).all(userId, clusterLimit);
+        const categoryRows = this.db.prepare(`
+      SELECT category AS label,
+             COUNT(*) AS count,
+             MIN(created_at) AS startAt,
+             MAX(created_at) AS endAt,
+             AVG(importance) AS avgImportance,
+             AVG(confidence) AS avgConfidence
+      FROM memories
+      WHERE user_id = ? ${archivedFilter}
+      GROUP BY category
+      ORDER BY count DESC, avgImportance DESC
+      LIMIT ?
+    `).all(userId, clusterLimit);
+        const clusters = [];
+        const pushRows = (kind, rows) => {
+            for (const row of rows) {
+                const label = String(row.label || "general");
+                clusters.push({
+                    id: `${kind}:${label}`,
+                    label,
+                    kind,
+                    count: Number(row.count ?? 0),
+                    startAt: Number(row.startAt ?? 0),
+                    endAt: Number(row.endAt ?? 0),
+                    avgImportance: Number(row.avgImportance ?? 0),
+                    avgConfidence: Number(row.avgConfidence ?? 0),
+                    topCategory: kind === "category" ? label : "general",
+                });
+            }
+        };
+        pushRows("source", sourceRows);
+        pushRows("category", categoryRows);
+        const tagRows = this.db.prepare(`
+      SELECT tags, category, created_at, importance, confidence
+      FROM memories
+      WHERE user_id = ? ${archivedFilter} AND tags != '[]'
+      ORDER BY importance DESC, created_at DESC
+      LIMIT 50000
+    `).all(userId);
+        const byTag = new Map();
+        for (const row of tagRows) {
+            let tags = [];
+            try {
+                tags = JSON.parse(typeof row.tags === "string" ? row.tags : "[]");
+            }
+            catch {
+                tags = [];
+            }
+            for (const tag of tags) {
+                if (typeof tag !== "string" || tag.startsWith("related:"))
+                    continue;
+                const value = tag.trim();
+                if (!value)
+                    continue;
+                const existing = byTag.get(value) ?? {
+                    count: 0,
+                    startAt: Number(row.created_at ?? 0),
+                    endAt: Number(row.created_at ?? 0),
+                    importance: 0,
+                    confidence: 0,
+                    categories: new Map(),
+                };
+                existing.count += 1;
+                existing.startAt = Math.min(existing.startAt, Number(row.created_at ?? existing.startAt));
+                existing.endAt = Math.max(existing.endAt, Number(row.created_at ?? existing.endAt));
+                existing.importance += Number(row.importance ?? 0);
+                existing.confidence += Number(row.confidence ?? 0);
+                const category = String(row.category || "general");
+                existing.categories.set(category, (existing.categories.get(category) ?? 0) + 1);
+                byTag.set(value, existing);
+            }
+        }
+        for (const [label, value] of Array.from(byTag.entries())
+            .filter(([, item]) => item.count > 1)
+            .sort((a, b) => b[1].count - a[1].count || b[1].importance - a[1].importance)
+            .slice(0, clusterLimit)) {
+            let topCategory = "general";
+            let topCount = 0;
+            for (const [category, count] of value.categories) {
+                if (count > topCount) {
+                    topCategory = category;
+                    topCount = count;
+                }
+            }
+            clusters.push({
+                id: `tag:${label}`,
+                label,
+                kind: "tag",
+                count: value.count,
+                startAt: value.startAt,
+                endAt: value.endAt,
+                avgImportance: value.importance / value.count,
+                avgConfidence: value.confidence / value.count,
+                topCategory,
+            });
+        }
+        return clusters
+            .sort((a, b) => b.count - a.count || b.avgImportance - a.avgImportance)
+            .slice(0, clusterLimit);
+    }
+    /**
+     * Get a single memory by ID.
+     */
+    getById(id) {
+        const row = this.db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
+        return row ? rowToRecord(row) : null;
+    }
+    /**
+     * Update memory text and bump updatedAt.
+     */
+    updateText(id, text, embedding) {
+        const now = Date.now();
+        const embBuf = embedding
+            ? Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength)
+            : undefined;
+        const result = embBuf
+            ? this.db.prepare("UPDATE memories SET text = ?, embedding = ?, updated_at = ? WHERE id = ?").run(text, embBuf, now, id)
+            : this.db.prepare("UPDATE memories SET text = ?, updated_at = ? WHERE id = ?").run(text, now, id);
+        return result.changes > 0;
+    }
+    /**
+     * Update editable memory fields and bump updatedAt.
+     */
+    update(id, input) {
+        const current = this.getById(id);
+        if (!current)
+            return false;
+        const now = Date.now();
+        const embedding = input.embedding === undefined
+            ? current.embedding
+            : input.embedding;
+        const embBuf = embedding
+            ? Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength)
+            : null;
+        const result = this.db.prepare(`
+      UPDATE memories
+      SET text = ?,
+          category = ?,
+          importance = ?,
+          source = ?,
+          event_date = ?,
+          tags = ?,
+          embedding = ?,
+          updated_at = ?
+      WHERE id = ?
+    `).run(input.text?.trim() || current.text, input.category || current.category, typeof input.importance === "number" && Number.isFinite(input.importance) ? input.importance : current.importance, input.source ?? current.source, input.eventDate ?? current.eventDate, JSON.stringify(input.tags ?? current.tags ?? []), embBuf, now, id);
+        return result.changes > 0;
+    }
+    /**
+     * Delete a memory by ID.
+     */
+    delete(id) {
+        const result = this.db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+        return result.changes > 0;
+    }
+    /**
+     * Archive a memory (soft-delete: set is_archived=1).
+     * Used by dedup gate when a similar but newer memory supersedes an older one.
+     */
+    archive(id) {
+        const result = this.db.prepare("UPDATE memories SET is_archived = 1, updated_at = ? WHERE id = ? AND is_archived = 0").run(Date.now(), id);
+        return result.changes > 0;
+    }
+    // Multi-strategy decay
+    /**
+     * Temporal expiry: archive event/plan memories whose event_date has passed
+     * beyond a grace period (e.g., "meeting tomorrow" 3 days after it happened).
+     */
+    decayTemporalExpiry(userId, graceDays = 7) {
+        const now = Date.now();
+        const rows = this.db.prepare(`
+      SELECT id, event_date FROM memories
+      WHERE user_id = ? AND is_archived = 0 AND event_date != ''
+        AND category IN ('event', 'plan', 'reminder', 'general')
+    `).all(userId);
+        let archived = 0;
+        for (const row of rows) {
+            const eventMs = Date.parse(row.event_date);
+            if (isNaN(eventMs))
+                continue;
+            if (now - eventMs > graceDays * 86_400_000) {
+                this.db.prepare("UPDATE memories SET is_archived = 1, updated_at = ? WHERE id = ?").run(now, row.id);
+                archived++;
+            }
+        }
+        return archived;
+    }
+    /**
+     * Staleness decay: reduce importance of memories not accessed in a long time.
+     * Memories accessed recently retain their importance; stale ones degrade.
+     */
+    decayStaleness(userId, staleDays = 30, decayFactor = 0.85) {
+        const cutoff = Date.now() - staleDays * 86_400_000;
+        const now = Date.now();
+        const result = this.db.prepare(`
+      UPDATE memories
+      SET importance = importance * ?,
+          updated_at = ?
+      WHERE user_id = ? AND is_archived = 0
+        AND last_accessed_at < ? AND last_accessed_at > 0
+        AND importance > 0.1
+    `).run(decayFactor, now, userId, cutoff);
+        return result.changes;
+    }
+    /**
+     * Noise archival: archive low-importance memories that never got accessed.
+     * Memories written by the agent but never recalled are likely noise.
+     */
+    decayNoiseArchival(userId, minAgeDays = 14, maxImportance = 0.25) {
+        const cutoff = Date.now() - minAgeDays * 86_400_000;
+        const now = Date.now();
+        const result = this.db.prepare(`
+      UPDATE memories SET is_archived = 1, updated_at = ?
+      WHERE user_id = ? AND is_archived = 0
+        AND created_at < ?
+        AND access_count = 0
+        AND importance <= ?
+    `).run(now, userId, cutoff, maxImportance);
+        return result.changes;
+    }
+    /**
+     * Run all decay strategies. Returns total affected count.
+     */
+    runFullDecay(userId, options) {
+        const temporal = this.decayTemporalExpiry(userId, options?.temporalGraceDays ?? 7);
+        const stale = this.decayStaleness(userId, options?.staleDays ?? 30, options?.staleDecayFactor ?? 0.85);
+        const noise = this.decayNoiseArchival(userId, options?.noiseMinAgeDays ?? 14, options?.noiseMaxImportance ?? 0.25);
+        return { temporal, stale, noise, total: temporal + noise };
+    }
+    // Feedback mechanism
+    /**
+     * Apply feedback signal to a memory, adjusting importance accordingly.
+     *
+     * Signals:
+     *   - "useful" boosts importance by +0.15 (capped at 1.0)
+     *   - "irrelevant" reduces importance by -0.2
+     *   - "outdated" archives immediately
+     *   - "wrong" deletes immediately
+     */
+    applyFeedback(memoryId, signal) {
+        const now = Date.now();
+        switch (signal) {
+            case "useful": {
+                const result = this.db.prepare(`
+          UPDATE memories SET importance = MIN(1.0, importance + 0.15), updated_at = ?, access_count = access_count + 1 WHERE id = ? AND is_archived = 0
+        `).run(now, memoryId);
+                return result.changes > 0;
+            }
+            case "irrelevant": {
+                const result = this.db.prepare(`
+          UPDATE memories SET importance = MAX(0.0, importance - 0.2), updated_at = ? WHERE id = ? AND is_archived = 0
+        `).run(now, memoryId);
+                return result.changes > 0;
+            }
+            case "outdated": {
+                const result = this.db.prepare(`
+          UPDATE memories SET is_archived = 1, updated_at = ? WHERE id = ?
+        `).run(now, memoryId);
+                return result.changes > 0;
+            }
+            case "wrong": {
+                return this.delete(memoryId);
+            }
+        }
+    }
+    // User profile store
+    /**
+     * Get a profile value for a user.
+     */
+    getProfile(userId, key) {
+        this.ensureProfileTable();
+        const row = this.db.prepare("SELECT value FROM user_profiles WHERE user_id = ? AND key = ?").get(userId, key);
+        return row?.value ?? null;
+    }
+    /**
+     * Set a profile value (upsert).
+     */
+    setProfile(userId, key, value) {
+        this.ensureProfileTable();
+        this.db.prepare(`
+      INSERT INTO user_profiles (user_id, key, value, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(user_id, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+    `).run(userId, key, value, Date.now());
+    }
+    /**
+     * Get all profile entries for a user.
+     */
+    getAllProfiles(userId) {
+        this.ensureProfileTable();
+        const rows = this.db.prepare("SELECT key, value FROM user_profiles WHERE user_id = ?").all(userId);
+        const result = {};
+        for (const row of rows)
+            result[row.key] = row.value;
+        return result;
+    }
+    /**
+     * Delete a profile entry.
+     */
+    deleteProfile(userId, key) {
+        this.ensureProfileTable();
+        const result = this.db.prepare("DELETE FROM user_profiles WHERE user_id = ? AND key = ?").run(userId, key);
+        return result.changes > 0;
+    }
+    profileTableCreated = false;
+    ensureProfileTable() {
+        if (this.profileTableCreated)
+            return;
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS user_profiles (
+        user_id TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (user_id, key)
+      );
+    `);
+        this.profileTableCreated = true;
+    }
+    // Temporal synthesis
+    /**
+     * Retrieve memories within a time range, grouped by day.
+     * Used for "what happened last week" type queries and dream synthesis.
+     */
+    getTemporalSlice(userId, startMs, endMs, options) {
+        const categoryFilter = options?.category ? "AND category = ?" : "";
+        const params = [userId, startMs, endMs];
+        if (options?.category)
+            params.push(options.category);
+        params.push(options?.limit ?? 200);
+        const rows = this.db.prepare(`
+      SELECT id, text, category, importance, created_at FROM memories
+      WHERE user_id = ? AND is_archived = 0
+        AND created_at >= ? AND created_at <= ?
+        ${categoryFilter}
+      ORDER BY created_at ASC
+      LIMIT ?
+    `).all(...params);
+        // Group by date
+        const grouped = new Map();
+        for (const row of rows) {
+            const date = new Date(row.created_at).toISOString().slice(0, 10);
+            if (!grouped.has(date))
+                grouped.set(date, []);
+            grouped.get(date).push({ id: row.id, text: row.text, category: row.category, importance: row.importance });
+        }
+        return Array.from(grouped.entries())
+            .map(([date, memories]) => ({ date, memories }))
+            .sort((a, b) => a.date.localeCompare(b.date));
+    }
+    /**
+     * Get memory activity summary over recent N days.
+     * Returns daily counts and high-importance entries used by temporal synthesis.
+     */
+    getActivitySummary(userId, days = 7) {
+        const startMs = Date.now() - days * 86_400_000;
+        const rows = this.db.prepare(`
+      SELECT id, text, category, importance, created_at FROM memories
+      WHERE user_id = ? AND is_archived = 0 AND created_at >= ?
+      ORDER BY created_at ASC
+    `).all(userId, startMs);
+        const dailyMap = new Map();
+        const highlights = [];
+        for (const row of rows) {
+            const date = new Date(row.created_at).toISOString().slice(0, 10);
+            dailyMap.set(date, (dailyMap.get(date) ?? 0) + 1);
+            if (row.importance >= 0.7) {
+                highlights.push({ id: row.id, text: row.text, category: row.category, importance: row.importance, date });
+            }
+        }
+        const dailyCounts = Array.from(dailyMap.entries())
+            .map(([date, count]) => ({ date, count }))
+            .sort((a, b) => a.date.localeCompare(b.date));
+        return { dailyCounts, highlights };
+    }
+    /**
+     * Find memories related to a specific event date (卤tolerance).
+     * Used for temporal context retrieval, such as finding memories around a requested date.
+     */
+    findByEventDate(userId, targetDate, toleranceDays = 1) {
+        const targetMs = Date.parse(targetDate);
+        if (isNaN(targetMs))
+            return [];
+        const startMs = targetMs - toleranceDays * 86_400_000;
+        const endMs = targetMs + toleranceDays * 86_400_000;
+        const rows = this.db.prepare(`
+      SELECT id, text, category, importance, tags, created_at, event_date FROM memories
+      WHERE user_id = ? AND is_archived = 0
+        AND (
+          (event_date != '' AND event_date >= ? AND event_date <= ?)
+          OR (created_at >= ? AND created_at <= ?)
+        )
+      ORDER BY importance DESC
+      LIMIT 20
+    `).all(userId, new Date(startMs).toISOString().slice(0, 10), new Date(endMs).toISOString().slice(0, 10), startMs, endMs);
+        return rows.map((r) => ({
+            id: r.id,
+            text: r.text,
+            score: r.importance,
+            category: r.category,
+            importance: r.importance,
+            metadata: { tags: JSON.parse(r.tags || "[]"), createdAt: r.created_at, eventDate: r.event_date },
+        }));
+    }
+    /**
+     * Record an access (for importance/relevance boosting).
+     */
+    recordAccess(id) {
+        this.db.prepare(`
+      UPDATE memories SET access_count = access_count + 1, last_accessed_at = ? WHERE id = ?
+    `).run(Date.now(), id);
+    }
+    /**
+     * Get total memory count for a user.
+     */
+    count(userId, activeOnly = true) {
+        const filter = activeOnly ? "AND is_archived = 0" : "";
+        const row = this.db.prepare(`SELECT COUNT(*) as cnt FROM memories WHERE user_id = ? ${filter}`).get(userId);
+        return row?.cnt ?? 0;
+    }
+    /**
+     * Delete all memories for a user.
+     */
+    resetUser(userId) {
+        const result = this.db.prepare("DELETE FROM memories WHERE user_id = ?").run(userId);
+        return result.changes;
+    }
+    // Capacity governance
+    /**
+     * Run SQLite VACUUM to reclaim space after deletions/archival.
+     * Should be called periodically (e.g. after decay cycles).
+     */
+    vacuum() {
+        this.db.exec("VACUUM");
+    }
+    /**
+     * Get database size info for capacity monitoring.
+     */
+    getStorageStats() {
+        const pageCount = this.db.pragma("page_count")[0]?.page_count ?? 0;
+        const pageSize = this.db.pragma("page_size")[0]?.page_size ?? 4096;
+        const freePages = this.db.pragma("freelist_count")[0]?.freelist_count ?? 0;
+        return {
+            pageCount,
+            pageSize,
+            totalBytes: pageCount * pageSize,
+            freePages,
+        };
+    }
+    /**
+     * Export archived memories as JSONL (for cold storage / backup).
+     * Deletes exported records from the database to reclaim space.
+     */
+    exportAndPurgeArchived(userId, maxExport = 500) {
+        const rows = this.db.prepare(`
+      SELECT id, text, category, importance, created_at, updated_at, tags
+      FROM memories
+      WHERE user_id = ? AND is_archived = 1
+      ORDER BY updated_at ASC
+      LIMIT ?
+    `).all(userId, maxExport);
+        if (rows.length === 0)
+            return [];
+        const exported = rows.map(r => ({
+            id: r.id,
+            text: r.text,
+            category: r.category,
+            importance: r.importance,
+            createdAt: r.created_at,
+            archivedAt: r.updated_at,
+            tags: JSON.parse(r.tags || "[]"),
+        }));
+        // Delete exported archived records
+        const ids = rows.map(r => r.id);
+        const placeholders = ids.map(() => "?").join(",");
+        this.db.prepare(`DELETE FROM memories WHERE id IN (${placeholders})`).run(...ids);
+        return exported;
+    }
+    /**
+     * Enforce capacity limit: if active memories exceed maxCount,
+     * archive the oldest lowest-importance ones.
+     */
+    enforceCapacityLimit(userId, maxCount = 10000) {
+        const currentCount = this.count(userId, true);
+        if (currentCount <= maxCount)
+            return 0;
+        const excess = currentCount - maxCount;
+        const result = this.db.prepare(`
+      UPDATE memories SET is_archived = 1, updated_at = ?
+      WHERE id IN (
+        SELECT id FROM memories
+        WHERE user_id = ? AND is_archived = 0
+        ORDER BY importance ASC, access_count ASC, created_at ASC
+        LIMIT ?
+      )
+    `).run(Date.now(), userId, excess);
+        return result.changes;
+    }
+    insertObservation(input) {
+        const id = `obs_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO memory_observations
+        (id, user_id, text, source, source_priority, session_id, evidence_type, payload, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.userId, input.text, input.source, input.sourcePriority, input.sessionId ?? "", input.evidenceType ?? "text", JSON.stringify(input.payload ?? {}), now);
+        return id;
+    }
+    insertProposal(input) {
+        const id = `prop_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO memory_proposals
+        (id, user_id, observation_ids, text, category, importance, confidence, source, source_priority,
+         entity, predicate, value_json, valid_time, tags, status, related_claim_ids, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.userId, JSON.stringify(input.observationIds), input.text, input.category, input.importance, input.confidence, input.source, input.sourcePriority, input.entity, input.predicate, JSON.stringify(input.value), input.validTime ?? "", JSON.stringify(input.tags ?? []), input.status ?? "pending", JSON.stringify(input.relatedClaimIds ?? []), now, now);
+        return id;
+    }
+    updateProposalStatus(id, status, relatedClaimIds) {
+        const now = Date.now();
+        const result = relatedClaimIds
+            ? this.db.prepare("UPDATE memory_proposals SET status = ?, related_claim_ids = ?, updated_at = ? WHERE id = ?")
+                .run(status, JSON.stringify(relatedClaimIds), now, id)
+            : this.db.prepare("UPDATE memory_proposals SET status = ?, updated_at = ? WHERE id = ?")
+                .run(status, now, id);
+        return result.changes > 0;
+    }
+    insertClaim(input) {
+        const id = `claim_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO memory_claims
+        (id, memory_id, user_id, entity, predicate, value_json, text, category, importance, confidence,
+         source, source_priority, status, valid_time, evidence_ids, supersedes_claim_id, conflict_group_id, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.memoryId ?? "", input.userId, input.entity, input.predicate, JSON.stringify(input.value), input.text, input.category, input.importance, input.confidence, input.source, input.sourcePriority, input.status, input.validTime ?? "", JSON.stringify(input.evidenceIds), input.supersedesClaimId ?? "", input.conflictGroupId ?? "", now, now);
+        return id;
+    }
+    listClaims(userId, statuses) {
+        const statusList = statuses?.length ? statuses : null;
+        const rows = statusList
+            ? this.db.prepare(`
+          SELECT * FROM memory_claims
+          WHERE user_id = ? AND status IN (${statusList.map(() => "?").join(",")})
+          ORDER BY updated_at DESC
+        `).all(userId, ...statusList)
+            : this.db.prepare(`
+          SELECT * FROM memory_claims
+          WHERE user_id = ?
+          ORDER BY updated_at DESC
+        `).all(userId);
+        return rows.map(rowToClaimRecord);
+    }
+    findClaimsByFact(userId, entity, predicate, validTime = "") {
+        const rows = this.db.prepare(`
+      SELECT * FROM memory_claims
+      WHERE user_id = ? AND entity = ? AND predicate = ? AND valid_time = ?
+        AND status IN ('active', 'pending_confirmation', 'conflicted')
+      ORDER BY updated_at DESC
+    `).all(userId, entity, predicate, validTime);
+        return rows.map(rowToClaimRecord);
+    }
+    mergeClaimEvidence(id, evidenceIds, confidence, importance) {
+        const current = this.db.prepare("SELECT evidence_ids FROM memory_claims WHERE id = ?").get(id);
+        if (!current)
+            return false;
+        const existing = parseJsonArray(current.evidence_ids);
+        const merged = Array.from(new Set([...existing, ...evidenceIds]));
+        const result = this.db.prepare(`
+      UPDATE memory_claims
+      SET evidence_ids = ?, confidence = MAX(confidence, ?), importance = MAX(importance, ?), updated_at = ?
+      WHERE id = ?
+    `).run(JSON.stringify(merged), confidence, importance, Date.now(), id);
+        return result.changes > 0;
+    }
+    updateClaimsByMemoryId(memoryId, status) {
+        const result = this.db.prepare(`
+      UPDATE memory_claims SET status = ?, updated_at = ? WHERE memory_id = ?
+    `).run(status, Date.now(), memoryId);
+        return result.changes;
+    }
+    insertConflict(input) {
+        const id = `conf_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO memory_conflicts (id, user_id, claim_a_id, claim_b_id, reason, status, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, 'open', ?, ?)
+    `).run(id, input.userId, input.claimAId, input.claimBId, input.reason, now, now);
+        return id;
+    }
+    listConflicts(userId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM memory_conflicts
+      WHERE user_id = ?
+      ORDER BY updated_at DESC
+    `).all(userId);
+        return rows.map(rowToConflictRecord);
+    }
+    getClaimById(id) {
+        const row = this.db.prepare("SELECT * FROM memory_claims WHERE id = ?").get(id);
+        return row ? rowToClaimRecord(row) : undefined;
+    }
+    setClaimStatus(id, status) {
+        const result = this.db.prepare("UPDATE memory_claims SET status = ?, updated_at = ? WHERE id = ?").run(status, Date.now(), id);
+        return result.changes > 0;
+    }
+    /** Mark a conflict resolved (the resolver has already updated the claims). */
+    setConflictStatus(id, status) {
+        const result = this.db.prepare("UPDATE memory_conflicts SET status = ?, updated_at = ? WHERE id = ?").run(status, Date.now(), id);
+        return result.changes > 0;
+    }
+    /** Open conflicts only (the ones needing resolution). */
+    listOpenConflicts(userId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM memory_conflicts
+      WHERE user_id = ? AND status = 'open'
+      ORDER BY created_at ASC
+    `).all(userId);
+        return rows.map(rowToConflictRecord);
+    }
+    /**
+     * Promote pending_confirmation claims that have accumulated enough independent
+     * evidence to become active. Returns the number promoted.
+     */
+    promotePendingClaims(userId, minEvidence) {
+        const pending = this.listClaims(userId, ["pending_confirmation"]);
+        let promoted = 0;
+        for (const claim of pending) {
+            if ((claim.evidenceIds?.length ?? 0) >= minEvidence) {
+                if (this.setClaimStatus(claim.id, "active"))
+                    promoted++;
+            }
+        }
+        return promoted;
+    }
+    // Attachments (long-term memory素材) — file bytes live on disk; this is the index.
+    insertAttachment(input) {
+        this.db.prepare(`
+      INSERT INTO memory_attachments
+        (id, memory_id, user_id, kind, filename, mime_type, size, rel_path, extracted_text, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(input.id, input.memoryId ?? "", input.userId, input.kind, input.filename, input.mimeType, input.size, input.relPath, input.extractedText ?? "", Date.now());
+    }
+    getAttachmentById(id) {
+        const row = this.db.prepare("SELECT * FROM memory_attachments WHERE id = ?").get(id);
+        return row ? rowToAttachment(row) : null;
+    }
+    listAttachmentsByMemoryId(memoryId) {
+        if (!memoryId)
+            return [];
+        const rows = this.db.prepare("SELECT * FROM memory_attachments WHERE memory_id = ? ORDER BY created_at ASC").all(memoryId);
+        return rows.map(rowToAttachment);
+    }
+    /** Batch-load attachments for many memories (for atlas windows). */
+    listAttachmentsByMemoryIds(memoryIds) {
+        const map = new Map();
+        if (memoryIds.length === 0)
+            return map;
+        const placeholders = memoryIds.map(() => "?").join(",");
+        const rows = this.db.prepare(`SELECT * FROM memory_attachments WHERE memory_id IN (${placeholders}) ORDER BY created_at ASC`).all(...memoryIds).map(rowToAttachment);
+        for (const row of rows) {
+            const list = map.get(row.memoryId) ?? [];
+            list.push(row);
+            map.set(row.memoryId, list);
+        }
+        return map;
+    }
+    /** Link orphan/owned attachments to a committed memory. Returns linked count. */
+    linkAttachments(memoryId, attachmentIds, userId) {
+        if (!memoryId || attachmentIds.length === 0)
+            return 0;
+        const placeholders = attachmentIds.map(() => "?").join(",");
+        const result = this.db.prepare(`
+      UPDATE memory_attachments
+      SET memory_id = ?
+      WHERE user_id = ? AND (memory_id = '' OR memory_id = ?) AND id IN (${placeholders})
+    `).run(memoryId, userId, memoryId, ...attachmentIds);
+        return result.changes;
+    }
+    setAttachmentExtractedText(id, text) {
+        const result = this.db.prepare("UPDATE memory_attachments SET extracted_text = ? WHERE id = ?").run(text.slice(0, 20_000), id);
+        return result.changes > 0;
+    }
+    /** Delete attachment index rows for a memory; returns their rel paths for file cleanup. */
+    deleteAttachmentsByMemoryId(memoryId) {
+        if (!memoryId)
+            return [];
+        const rows = this.db.prepare("SELECT rel_path FROM memory_attachments WHERE memory_id = ?").all(memoryId);
+        this.db.prepare("DELETE FROM memory_attachments WHERE memory_id = ?").run(memoryId);
+        return rows.map((r) => r.rel_path);
+    }
+    /** Orphan attachments (uploaded but never saved to a memory) older than cutoff. */
+    listOrphanAttachments(cutoff) {
+        const rows = this.db.prepare("SELECT * FROM memory_attachments WHERE memory_id = '' AND created_at < ?").all(cutoff);
+        return rows.map(rowToAttachment);
+    }
+    deleteAttachmentById(id) {
+        this.db.prepare("DELETE FROM memory_attachments WHERE id = ?").run(id);
+    }
+    close() {
+        this.db.close();
+    }
+}
+function rowToAttachment(row) {
+    const r = row;
+    return {
+        id: String(r.id),
+        memoryId: String(r.memory_id ?? ""),
+        userId: String(r.user_id ?? ""),
+        kind: String(r.kind ?? "file"),
+        filename: String(r.filename ?? ""),
+        mimeType: String(r.mime_type ?? ""),
+        size: Number(r.size ?? 0),
+        relPath: String(r.rel_path ?? ""),
+        extractedText: String(r.extracted_text ?? ""),
+        createdAt: Number(r.created_at ?? 0),
+    };
+}
+function toFtsPhraseQuery(query) {
+    const tokens = query
+        .match(/[\p{L}\p{N}_]+/gu)
+        ?.map((token) => token.trim())
+        .filter(Boolean)
+        .slice(0, 32) ?? [];
+    return tokens.map((token) => `"${token.replace(/"/g, "\"\"")}"`).join(" ");
+}