@timmeck/brain-core 2.36.85 → 2.36.86

package/dist/memory/retrieval-maintenance.js

@@ -0,0 +1,201 @@
+// ── Retrieval Maintenance Engine ──────────────────────────
+//
+// Offline maintenance for memory retrieval quality.
+// Runs periodically (every 2h) to:
+//   1. Mark cold memories as archive candidates
+//   2. Build pre-computed candidate sets for fast typed retrieval
+//
+// Design principle (ChatGPT): "Retrieval online einfach halten, Struktur offline pflegen."
+import { getLogger } from '../utils/logger.js';
+// ── Intent Definitions ────────────────────────────────────
+const INTENT_DEFINITIONS = {
+    decision_lookup: { categories: ['decision'], minImportance: 3 },
+    project_context: { categories: ['context', 'fact'], minImportance: 3 },
+    user_preference_lookup: { categories: ['preference', 'constraint'], minImportance: 2 },
+    open_problem_lookup: { categories: ['open_question', 'goal'], minImportance: 2 },
+};
+// ── Engine ────────────────────────────────────────────────
+export class RetrievalMaintenanceEngine {
+    db;
+    config;
+    log = getLogger();
+    timer = null;
+    totalRuns = 0;
+    lastRunAt = null;
+    constructor(db, config = {}) {
+        this.db = db;
+        this.config = {
+            coldThresholdDays: config.coldThresholdDays ?? 30,
+            minImportanceForProtection: config.minImportanceForProtection ?? 4,
+            candidateSetSize: config.candidateSetSize ?? 50,
+        };
+        this.ensureTable();
+    }
+    /** Start periodic maintenance (default: every 2h). */
+    start(intervalMs = 2 * 60 * 60 * 1000) {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            try {
+                this.runMaintenance();
+            }
+            catch (err) {
+                this.log.debug(`[retrieval-maintenance] Cycle error: ${err.message}`);
+            }
+        }, intervalMs);
+        this.log.info(`[retrieval-maintenance] Started (interval: ${Math.round(intervalMs / 3600000)}h)`);
+    }
+    /** Stop periodic maintenance. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            this.log.info('[retrieval-maintenance] Stopped');
+        }
+    }
+    /** Main cycle — call periodically (every 2h). */
+    runMaintenance() {
+        const start = Date.now();
+        const archiveCandidatesMarked = this.markArchiveCandidates();
+        const candidateReport = this.refreshCandidateSets();
+        this.totalRuns++;
+        this.lastRunAt = new Date().toISOString();
+        const durationMs = Date.now() - start;
+        this.log.info(`[retrieval-maintenance] Run #${this.totalRuns}: ${archiveCandidatesMarked} archive candidates, ${candidateReport.setsCreated} sets refreshed (${durationMs}ms)`);
+        return {
+            archiveCandidatesMarked,
+            candidateSetsRefreshed: candidateReport.setsCreated,
+            durationMs,
+        };
+    }
+    /**
+     * Cold Memory Detection.
+     * Mark as archive_candidate = 1 when:
+     * - created_at > coldThresholdDays AND
+     * - access_count = 0 AND use_count = 0 AND
+     * - importance < minImportanceForProtection
+     *
+     * Safety: No automatic deletion, only marking.
+     */
+    markArchiveCandidates() {
+        try {
+            // Reset existing candidates that no longer qualify (accessed since last run)
+            this.db.prepare(`
+        UPDATE conversation_memories SET archive_candidate = 0
+        WHERE archive_candidate = 1 AND (access_count > 0 OR use_count > 0 OR importance >= ?)
+      `).run(this.config.minImportanceForProtection);
+            // Mark new cold memories
+            const result = this.db.prepare(`
+        UPDATE conversation_memories SET archive_candidate = 1
+        WHERE active = 1
+          AND archive_candidate = 0
+          AND created_at < datetime('now', '-' || ? || ' days')
+          AND access_count = 0
+          AND use_count = 0
+          AND importance < ?
+      `).run(this.config.coldThresholdDays, this.config.minImportanceForProtection);
+            return result.changes;
+        }
+        catch (err) {
+            this.log.debug(`[retrieval-maintenance] markArchiveCandidates error: ${err.message}`);
+            return 0;
+        }
+    }
+    /** Refresh pre-computed candidate sets for typed retrieval. */
+    refreshCandidateSets() {
+        let setsCreated = 0;
+        let totalMemories = 0;
+        // Per-category sets
+        const categories = ['preference', 'decision', 'context', 'fact', 'goal', 'lesson', 'constraint', 'open_question'];
+        for (const cat of categories) {
+            const count = this.buildCandidateSet('category', cat, [cat]);
+            if (count > 0) {
+                setsCreated++;
+                totalMemories += count;
+            }
+        }
+        // Per-intent sets
+        for (const [intent, def] of Object.entries(INTENT_DEFINITIONS)) {
+            const count = this.buildCandidateSet('intent', intent, def.categories, def.minImportance);
+            if (count > 0) {
+                setsCreated++;
+                totalMemories += count;
+            }
+        }
+        return { setsCreated, totalMemories };
+    }
+    /** Get current status. */
+    getStatus() {
+        let totalArchiveCandidates = 0;
+        let candidateSets = 0;
+        try {
+            const archiveRow = this.db.prepare('SELECT COUNT(*) as cnt FROM conversation_memories WHERE archive_candidate = 1').get();
+            totalArchiveCandidates = archiveRow?.cnt ?? 0;
+        }
+        catch { /* table may not have column yet */ }
+        try {
+            const setsRow = this.db.prepare('SELECT COUNT(*) as cnt FROM retrieval_candidate_sets').get();
+            candidateSets = setsRow?.cnt ?? 0;
+        }
+        catch { /* table may not exist */ }
+        return {
+            lastRunAt: this.lastRunAt,
+            totalRuns: this.totalRuns,
+            totalArchiveCandidates,
+            candidateSets,
+        };
+    }
+    /** Get a candidate set by type and key. Returns memory IDs. */
+    getCandidateSet(setType, setKey) {
+        try {
+            const row = this.db.prepare('SELECT memory_ids FROM retrieval_candidate_sets WHERE set_type = ? AND set_key = ?').get(setType, setKey);
+            if (!row)
+                return [];
+            return JSON.parse(row.memory_ids);
+        }
+        catch {
+            return [];
+        }
+    }
+    // ── Private ─────────────────────────────────────────────
+    ensureTable() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS retrieval_candidate_sets (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        set_type TEXT NOT NULL,
+        set_key TEXT NOT NULL,
+        memory_ids TEXT NOT NULL DEFAULT '[]',
+        set_size INTEGER NOT NULL DEFAULT 0,
+        refreshed_at TEXT DEFAULT (datetime('now')),
+        UNIQUE(set_type, set_key)
+      );
+    `);
+    }
+    buildCandidateSet(setType, setKey, categories, minImportance = 1) {
+        try {
+            const placeholders = categories.map(() => '?').join(',');
+            const rows = this.db.prepare(`
+        SELECT id FROM conversation_memories
+        WHERE active = 1
+          AND archive_candidate = 0
+          AND category IN (${placeholders})
+          AND importance >= ?
+        ORDER BY importance DESC, use_count DESC, access_count DESC
+        LIMIT ?
+      `).all(...categories, minImportance, this.config.candidateSetSize);
+            const ids = rows.map(r => r.id);
+            this.db.prepare(`
+        INSERT INTO retrieval_candidate_sets (set_type, set_key, memory_ids, set_size, refreshed_at)
+        VALUES (?, ?, ?, ?, datetime('now'))
+        ON CONFLICT(set_type, set_key)
+        DO UPDATE SET memory_ids = excluded.memory_ids, set_size = excluded.set_size, refreshed_at = datetime('now')
+      `).run(setType, setKey, JSON.stringify(ids), ids.length);
+            return ids.length;
+        }
+        catch (err) {
+            this.log.debug(`[retrieval-maintenance] buildCandidateSet error for ${setType}/${setKey}: ${err.message}`);
+            return 0;
+        }
+    }
+}
+//# sourceMappingURL=retrieval-maintenance.js.map

package/dist/memory/retrieval-maintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-maintenance.js","sourceRoot":"","sources":["../../src/memory/retrieval-maintenance.ts"],"names":[],"mappings":"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"}

package/dist/memory/types.d.ts

@@ -1,4 +1,4 @@
-export type MemoryCategory = 'preference' | 'decision' | 'context' | 'fact' | 'goal' | 'lesson';
+export type MemoryCategory = 'preference' | 'decision' | 'context' | 'fact' | 'goal' | 'lesson' | 'constraint' | 'open_question';
 export type MemorySource = 'explicit' | 'inferred' | 'hook';
 export type SessionOutcome = 'completed' | 'paused' | 'abandoned';
 export interface MemoryRecord {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmeck/brain-core",
-  "version": "2.36.85",
+  "version": "2.36.86",
   "description": "Shared core infrastructure for the Brain ecosystem — IPC, MCP, CLI, DB connection, and utilities",
   "type": "module",
   "main": "dist/index.js",