@psiclawops/hypermem 0.5.0 → 0.5.1

package/dist/dreaming-promoter.js

@@ -0,0 +1,381 @@
+/**
+ * dreaming-promoter.ts
+ *
+ * hypermem-native dreaming promotion pass.
+ *
+ * Unlike the stock memory-core dreaming feature (which appends raw content to
+ * MEMORY.md), this promoter generates pointer-format entries that match the
+ * council's MEMORY.md convention:
+ *
+ *   - **{domain} — {title}:** {summary}
+ *     → `memory_search("{query}")`
+ *
+ * Scoring uses confidence, decay, recency, and domain cluster weight.
+ * Dedup prevents re-promoting topics already covered by existing pointers.
+ *
+ * Dry-run mode returns what would be written without modifying any files.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+export const DEFAULT_DREAMER_CONFIG = {
+    enabled: false,
+    minScore: 0.75,
+    minConfidence: 0.70,
+    maxPromotionsPerRun: 5,
+    tickInterval: 12,
+    dryRun: false,
+    recencyHalfLifeDays: 7,
+    maxAgeDays: 30,
+};
+// ─── Workspace path resolution ───────────────────────────────────────────────
+/**
+ * Resolve the workspace directory for an agent.
+ * Council agents live at ~/.openclaw/workspace-council/{agentId}/
+ * Other agents at ~/.openclaw/workspace/{agentId}/
+ */
+export async function resolveAgentWorkspacePath(agentId) {
+    const home = os.homedir();
+    const councilPath = path.join(home, '.openclaw', 'workspace-council', agentId);
+    const workspacePath = path.join(home, '.openclaw', 'workspace', agentId);
+    try {
+        await fs.access(councilPath);
+        return councilPath;
+    }
+    catch {
+        try {
+            await fs.access(workspacePath);
+            return workspacePath;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ─── Scoring ─────────────────────────────────────────────────────────────────
+/**
+ * Composite promotion score.
+ *
+ * score = confidence_factor × recency_factor × quality_factor
+ *
+ * confidence_factor: 0..1 — the raw confidence, penalized by decay
+ * recency_factor:    0..1 — exponential decay from age (half-life = config)
+ * quality_factor:    0..1 — length/richness proxy (bonus for medium-length facts)
+ */
+function scoreCandidate(fact, config) {
+    const confidenceFactor = fact.confidence * (1 - fact.decayScore * 0.5);
+    const halfLife = config.recencyHalfLifeDays;
+    const recencyFactor = Math.exp(-(Math.LN2 / halfLife) * fact.ageDays);
+    // Quality: medium-length facts (80–180 chars) score best. Very long or very
+    // short get penalized — they're likely fragments or noisy captures.
+    const len = fact.content.length;
+    const qualityFactor = len < 60 ? 0.6 : len > 220 ? 0.75 : 1.0;
+    return confidenceFactor * recencyFactor * qualityFactor;
+}
+// ─── Pointer generation ───────────────────────────────────────────────────────
+/**
+ * Extract a concise title and search query from fact content.
+ * Avoids NLP — purely string heuristics, fast and deterministic.
+ */
+function extractPointerMeta(content, domain) {
+    // Clean up trailing code artifacts
+    const cleaned = content
+        .replace(/['"]\s*\).*$/, '') // strip trailing '); or '),
+        .replace(/',\s*tool_calls:.*$/, '') // strip tool_calls artifacts
+        .replace(/…$/, '') // strip ellipsis
+        .replace(/\s+/g, ' ')
+        .trim();
+    // Title: first meaningful clause (up to first period, comma, or 50 chars)
+    let title = cleaned.split(/[.,;:]/)[0].trim();
+    if (title.length > 55)
+        title = title.slice(0, 52) + '…';
+    // Query: leading noun phrase — first 6-8 significant words, excluding articles/prepositions
+    const stopWords = new Set([
+        'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+        'to', 'of', 'in', 'on', 'at', 'by', 'for', 'with', 'as', 'it', 'its',
+        'this', 'that', 'we', 'i', 'you', 'they', 'and', 'or', 'but', 'so',
+    ]);
+    const words = cleaned
+        .split(/\s+/)
+        .map(w => w.replace(/[^a-zA-Z0-9_-]/g, '').toLowerCase())
+        .filter(w => w.length > 2 && !stopWords.has(w));
+    const queryWords = words.slice(0, 7);
+    // Prepend domain as context anchor so search hits the right agent scope
+    const query = `${domain} ${queryWords.join(' ')}`.slice(0, 60).trim();
+    return { title, query };
+}
+/**
+ * Format a promoted fact as a MEMORY.md pointer entry.
+ */
+function formatPointer(domain, title, summary, query) {
+    // Capitalize domain label for display
+    const domainLabel = domain.charAt(0).toUpperCase() + domain.slice(1);
+    return `- **${domainLabel} — ${title}:** ${summary}\n  → \`memory_search("${query}")\``;
+}
+// ─── Dedup ───────────────────────────────────────────────────────────────────
+/**
+ * Parse existing memory_search() calls from MEMORY.md content.
+ * Returns a set of normalized query strings already indexed.
+ */
+function parseExistingPointers(memoryContent) {
+    const existing = new Set();
+    const re = /memory_search\("([^"]+)"\)/g;
+    let m;
+    while ((m = re.exec(memoryContent)) !== null) {
+        existing.add(m[1].toLowerCase().trim());
+    }
+    return existing;
+}
+/**
+ * Check if a proposed query overlaps significantly with any existing pointer.
+ * Uses word-level Jaccard similarity (threshold 0.4).
+ */
+function isDuplicatePointer(proposedQuery, existing) {
+    if (existing.has(proposedQuery.toLowerCase().trim()))
+        return true;
+    const proposedWords = new Set(proposedQuery.toLowerCase().split(/\s+/).filter(w => w.length > 2));
+    if (proposedWords.size === 0)
+        return false;
+    for (const existingQuery of existing) {
+        const existingWords = new Set(existingQuery.split(/\s+/).filter(w => w.length > 2));
+        const intersection = [...proposedWords].filter(w => existingWords.has(w)).length;
+        const union = new Set([...proposedWords, ...existingWords]).size;
+        const jaccard = union > 0 ? intersection / union : 0;
+        if (jaccard >= 0.4)
+            return true;
+    }
+    return false;
+}
+// ─── MEMORY.md write ─────────────────────────────────────────────────────────
+const PROMOTED_SECTION_HEADER = '## Promoted Facts';
+const PROMOTED_SECTION_MARKER = '<!-- hypermem:dreaming-promoted -->';
+/**
+ * Append promoted pointer entries to MEMORY.md.
+ * Writes into an existing "## Promoted Facts" section, or appends one.
+ * Non-destructive: only appends, never rewrites existing content.
+ */
+async function appendToMemoryFile(memoryPath, entries) {
+    if (entries.length === 0)
+        return;
+    let existing = '';
+    try {
+        existing = await fs.readFile(memoryPath, 'utf-8');
+    }
+    catch {
+        // File doesn't exist — start fresh (unlikely but handle gracefully)
+        existing = `# MEMORY.md\n\n_This is an index, not a store. Use \`memory_search\` for full context on any topic._\n\n`;
+    }
+    const newLines = entries.map(e => e.pointer).join('\n');
+    const timestamp = new Date().toISOString().slice(0, 10);
+    if (existing.includes(PROMOTED_SECTION_HEADER)) {
+        // Inject after the section header line
+        const headerIdx = existing.indexOf(PROMOTED_SECTION_HEADER);
+        const afterHeader = existing.indexOf('\n', headerIdx) + 1;
+        const insertPoint = afterHeader;
+        const updated = existing.slice(0, insertPoint) +
+            `<!-- promoted ${timestamp} -->\n${newLines}\n` +
+            existing.slice(insertPoint);
+        await fs.writeFile(memoryPath, updated, 'utf-8');
+    }
+    else {
+        // Append a new section at end of file
+        const appendBlock = `\n${PROMOTED_SECTION_HEADER}\n${PROMOTED_SECTION_MARKER}\n` +
+            `<!-- promoted ${timestamp} -->\n${newLines}\n`;
+        await fs.writeFile(memoryPath, existing.trimEnd() + '\n' + appendBlock, 'utf-8');
+    }
+}
+// ─── Promotion-time content filter ─────────────────────────────────────────
+/**
+ * Reject facts that are clearly noise at promotion time.
+ * A second line of defense — the indexer's isQualityFact() is the primary filter,
+ * but legacy noise in the DB (pre-TUNE-013) still needs to be caught here.
+ */
+function isPromotable(content) {
+    // Multi-line content — reject both actual newlines AND escaped \n sequences
+    // (some facts stored pre-TUNE-013 have literal \n in the string value)
+    if (content.includes('\n') || content.includes('\\n'))
+        return false;
+    // External content markers
+    if (content.includes('EXTERNAL_UNTRUSTED_CONTENT') || content.includes('<<<'))
+        return false;
+    // Markdown heading fragments
+    if (/^#{1,4}\s/.test(content))
+        return false;
+    // Code/tool artifacts
+    if (/tool_calls:|\)\s*[;,]\s*$|',\s*$/.test(content))
+        return false;
+    // Escaped newlines embedded in content (stored as literal \n in DB)
+    if (/\\n/.test(content))
+        return false;
+    // URL-heavy (external research/docs, not fleet knowledge)
+    const urlCount = (content.match(/https?:\/\//g) || []).length;
+    if (urlCount >= 2)
+        return false;
+    // Fragment starts — no subject (lowercase/article/conjunction lead-ins)
+    if (/^(and |or |but |to |in |of |the |a |an |by |for |at |on |with |\d+\.|\* |\- )/.test(content.trim()))
+        return false;
+    // Context-free references: starts with a possessive/pronoun referencing something outside
+    if (/^(it |its |this |that |these |those |they |their |we |our |i |my )/.test(content.toLowerCase().trim()))
+        return false;
+    // External research noise: benchmark/tool comparison content
+    if (/\b(LOCOMO|LoCoMo|LangMem|SuperMemory|Zep|Honcho|Mem0)\b/i.test(content) &&
+        /\b(study|benchmark|dataset|employed|researchers|similarity|retrieval|accuracy)\b/i.test(content))
+        return false;
+    // Apache license boilerplate
+    if (/AS IS.*BASIS|distributed under the License/i.test(content))
+        return false;
+    // Pure CLI output or file path patterns
+    if (/^(git |npm |node |python3? |bash |echo |cat |ls |curl )/.test(content.trim()))
+        return false;
+    // Templated TODO/example patterns (from docs, not real fleet state)
+    if (/TODO:|implement Z|capture\.py/.test(content))
+        return false;
+    // Must start with a capital letter or number (complete sentences only)
+    if (!/^[A-Z0-9]/.test(content.trim()))
+        return false;
+    // Minimum meaningful length: 50 chars as promotion floor (stricter than indexer's 40)
+    if (content.trim().length < 50)
+        return false;
+    return true;
+}
+/**
+ * Run the dreaming promotion pass for a single agent.
+ *
+ * Reads qualified facts from library.db, scores them, deduplicates against
+ * existing MEMORY.md pointers, and writes new pointer entries.
+ */
+export async function runDreamingPromoter(agentId, libraryDb, config = {}) {
+    const cfg = { ...DEFAULT_DREAMER_CONFIG, ...config };
+    const result = {
+        agentId,
+        candidates: 0,
+        promoted: 0,
+        skippedDuplicate: 0,
+        skippedThreshold: 0,
+        entries: [],
+        memoryPath: null,
+        dryRun: cfg.dryRun,
+    };
+    // 1. Resolve workspace path
+    const wsPath = await resolveAgentWorkspacePath(agentId);
+    if (!wsPath) {
+        return result; // No workspace — skip silently
+    }
+    const memoryPath = path.join(wsPath, 'MEMORY.md');
+    result.memoryPath = memoryPath;
+    // 2. Read existing MEMORY.md (for dedup)
+    let memoryContent = '';
+    try {
+        memoryContent = await fs.readFile(memoryPath, 'utf-8');
+    }
+    catch {
+        // File may not exist — will be created on first promotion
+    }
+    const existingPointers = parseExistingPointers(memoryContent);
+    // 3. Query candidate facts from library.db
+    // Criteria: active (not superseded), has domain, meets confidence floor,
+    // within age window, not null content
+    const cutoffDate = new Date(Date.now() - cfg.maxAgeDays * 86400_000).toISOString();
+    const rawFacts = libraryDb.prepare(`
+    SELECT
+      id,
+      agent_id,
+      domain,
+      content,
+      confidence,
+      decay_score,
+      ROUND((julianday('now') - julianday(created_at)), 2) AS age_days
+    FROM facts
+    WHERE agent_id = ?
+      AND superseded_by IS NULL
+      AND domain IS NOT NULL
+      AND confidence >= ?
+      AND created_at >= ?
+      AND LENGTH(content) >= 40
+      AND LENGTH(content) <= 300
+    ORDER BY confidence DESC, decay_score ASC, created_at DESC
+    LIMIT 200
+  `).all(agentId, cfg.minConfidence, cutoffDate);
+    result.candidates = rawFacts.length;
+    // 4. Score and rank
+    const scored = rawFacts
+        .filter(f => isPromotable(f.content))
+        .map(f => ({
+        id: f.id,
+        agentId: f.agent_id,
+        domain: f.domain,
+        content: f.content,
+        confidence: f.confidence,
+        decayScore: f.decay_score,
+        ageDays: f.age_days,
+        score: scoreCandidate({ confidence: f.confidence, decayScore: f.decay_score, ageDays: f.age_days, content: f.content }, cfg),
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    // 5. Select up to maxPromotionsPerRun entries, with dedup
+    // Track which queries we've already added this run (cross-entry dedup)
+    const addedThisRun = new Set(existingPointers);
+    const toPromote = [];
+    for (const fact of scored) {
+        if (toPromote.length >= cfg.maxPromotionsPerRun)
+            break;
+        // Score threshold
+        if (fact.score < cfg.minScore) {
+            result.skippedThreshold++;
+            continue;
+        }
+        const { title, query } = extractPointerMeta(fact.content, fact.domain);
+        // Dedup check against existing pointers + already-selected entries this run
+        if (isDuplicatePointer(query, addedThisRun)) {
+            result.skippedDuplicate++;
+            continue;
+        }
+        // Trim summary to a clean one-liner (max 120 chars)
+        const rawSummary = fact.content
+            .replace(/['"]\s*\).*$/, '')
+            .replace(/\s+/g, ' ')
+            .trim();
+        const summary = rawSummary.length > 120 ? rawSummary.slice(0, 117) + '…' : rawSummary;
+        const pointer = formatPointer(fact.domain, title, summary, query);
+        const entry = {
+            factId: fact.id,
+            domain: fact.domain,
+            pointer,
+            title,
+            summary,
+            query,
+            score: Math.round(fact.score * 1000) / 1000,
+            dryRun: cfg.dryRun,
+        };
+        toPromote.push(entry);
+        addedThisRun.add(query.toLowerCase().trim());
+    }
+    result.entries = toPromote;
+    result.promoted = toPromote.length;
+    // 6. Write to MEMORY.md (unless dry-run)
+    if (!cfg.dryRun && toPromote.length > 0) {
+        await appendToMemoryFile(memoryPath, toPromote);
+        console.log(`[dreaming] Promoted ${toPromote.length} facts to ${memoryPath} ` +
+            `(${result.skippedDuplicate} dupes, ${result.skippedThreshold} below threshold)`);
+    }
+    return result;
+}
+/**
+ * Run the dreaming promotion pass for all agents in a fleet.
+ * Called from the BackgroundIndexer on every N ticks.
+ */
+export async function runDreamingPassForFleet(agentIds, libraryDb, config = {}) {
+    const results = [];
+    for (const agentId of agentIds) {
+        try {
+            const r = await runDreamingPromoter(agentId, libraryDb, config);
+            if (r.promoted > 0 || r.dryRun) {
+                results.push(r);
+            }
+        }
+        catch (err) {
+            console.warn(`[dreaming] Failed for agent ${agentId} (non-fatal):`, err.message);
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=dreaming-promoter.js.map

package/dist/episode-store.d.ts

@@ -0,0 +1,49 @@
+/**
+ * hypermem Episode Store
+ *
+ * Significant events in an agent's lifetime.
+ * Lives in the central library DB.
+ * Replaces daily log files with structured, queryable episodes.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { Episode, EpisodeType } from './types.js';
+export declare class EpisodeStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Record a new episode.
+     */
+    record(agentId: string, eventType: EpisodeType, summary: string, opts?: {
+        significance?: number;
+        visibility?: string;
+        participants?: string[];
+        sessionKey?: string;
+        sourceMessageId?: number;
+    }): Episode;
+    /**
+     * Get recent episodes for an agent.
+     */
+    getRecent(agentId: string, opts?: {
+        eventType?: EpisodeType;
+        minSignificance?: number;
+        limit?: number;
+        since?: string;
+    }): Episode[];
+    /**
+     * Get the most significant episodes (across all time).
+     */
+    getMostSignificant(agentId: string, limit?: number): Episode[];
+    /**
+     * Decay all episodes.
+     */
+    decay(agentId: string, decayRate?: number): number;
+    /**
+     * Prune fully decayed episodes.
+     */
+    prune(agentId: string): number;
+    /**
+     * Get episode summary for a time range.
+     */
+    getDailySummary(agentId: string, date: string): Episode[];
+}
+//# sourceMappingURL=episode-store.d.ts.map

package/dist/episode-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episode-store.d.ts","sourceRoot":"","sources":["../src/episode-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAsBvD,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,GACA,OAAO;IA2CV;;OAEG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,SAAS,CAAC,EAAE,WAAW,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GACA,OAAO,EAAE;IA4BZ;;OAEG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,OAAO,EAAE;IAWlE;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,MAAM;IAUzD;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQ9B;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE;CAa1D"}

package/dist/episode-store.js

@@ -0,0 +1,135 @@
+/**
+ * hypermem Episode Store
+ *
+ * Significant events in an agent's lifetime.
+ * Lives in the central library DB.
+ * Replaces daily log files with structured, queryable episodes.
+ */
+import { isSafeForSharedVisibility, requiresScan } from './secret-scanner.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+function parseEpisodeRow(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        eventType: row.event_type,
+        summary: row.summary,
+        significance: row.significance,
+        visibility: row.visibility || 'org',
+        participants: row.participants ? JSON.parse(row.participants) : null,
+        sessionKey: row.session_key || null,
+        createdAt: row.created_at,
+        decayScore: row.decay_score,
+    };
+}
+export class EpisodeStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Record a new episode.
+     */
+    record(agentId, eventType, summary, opts) {
+        const now = nowIso();
+        const significance = opts?.significance || 0.5;
+        // Secret gate: if requested visibility is shared, verify content is clean.
+        // Downgrade to 'private' rather than throw — better to lose the share than leak a secret.
+        let resolvedVisibility = opts?.visibility || 'org';
+        if (requiresScan(resolvedVisibility) && !isSafeForSharedVisibility(summary)) {
+            resolvedVisibility = 'private';
+        }
+        const result = this.db.prepare(`
+      INSERT INTO episodes (agent_id, event_type, summary, significance,
+        visibility, participants, session_key, source_message_id, created_at, decay_score)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0.0)
+    `).run(agentId, eventType, summary, significance, resolvedVisibility, opts?.participants ? JSON.stringify(opts.participants) : null, opts?.sessionKey || null, opts?.sourceMessageId ?? null, now);
+        const id = Number(result.lastInsertRowid);
+        return {
+            id,
+            agentId,
+            eventType,
+            summary,
+            significance,
+            visibility: resolvedVisibility,
+            participants: opts?.participants || null,
+            sessionKey: opts?.sessionKey || null,
+            createdAt: now,
+            decayScore: 0,
+        };
+    }
+    /**
+     * Get recent episodes for an agent.
+     */
+    getRecent(agentId, opts) {
+        let sql = 'SELECT * FROM episodes WHERE agent_id = ? AND decay_score < 0.8';
+        const params = [agentId];
+        if (opts?.eventType) {
+            sql += ' AND event_type = ?';
+            params.push(opts.eventType);
+        }
+        if (opts?.minSignificance) {
+            sql += ' AND significance >= ?';
+            params.push(opts.minSignificance);
+        }
+        if (opts?.since) {
+            sql += ' AND created_at > ?';
+            params.push(opts.since);
+        }
+        sql += ' ORDER BY created_at DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseEpisodeRow);
+    }
+    /**
+     * Get the most significant episodes (across all time).
+     */
+    getMostSignificant(agentId, limit = 10) {
+        const rows = this.db.prepare(`
+      SELECT * FROM episodes
+      WHERE agent_id = ? AND decay_score < 0.5
+      ORDER BY significance DESC, created_at DESC
+      LIMIT ?
+    `).all(agentId, limit);
+        return rows.map(parseEpisodeRow);
+    }
+    /**
+     * Decay all episodes.
+     */
+    decay(agentId, decayRate = 0.005) {
+        const result = this.db.prepare(`
+      UPDATE episodes
+      SET decay_score = MIN(decay_score + ?, 1.0)
+      WHERE agent_id = ? AND decay_score < 1.0
+    `).run(decayRate, agentId);
+        return result.changes;
+    }
+    /**
+     * Prune fully decayed episodes.
+     */
+    prune(agentId) {
+        const result = this.db.prepare(`
+      DELETE FROM episodes WHERE agent_id = ? AND decay_score >= 1.0
+    `).run(agentId);
+        return result.changes;
+    }
+    /**
+     * Get episode summary for a time range.
+     */
+    getDailySummary(agentId, date) {
+        const startOfDay = `${date}T00:00:00.000Z`;
+        const endOfDay = `${date}T23:59:59.999Z`;
+        const rows = this.db.prepare(`
+      SELECT * FROM episodes
+      WHERE agent_id = ?
+      AND created_at >= ? AND created_at <= ?
+      ORDER BY significance DESC, created_at ASC
+    `).all(agentId, startOfDay, endOfDay);
+        return rows.map(parseEpisodeRow);
+    }
+}
+//# sourceMappingURL=episode-store.js.map

package/dist/fact-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * hypermem Fact Store
+ *
+ * CRUD operations for facts (extracted knowledge that spans sessions).
+ * Facts live in the central library DB, tagged by agent_id.
+ * Facts have scope (agent/session/user), confidence, and decay.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { Fact, FactScope } from './types.js';
+export declare class FactStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Add a new fact. Checks for duplicates by content.
+     */
+    addFact(agentId: string, content: string, opts?: {
+        scope?: FactScope;
+        domain?: string;
+        confidence?: number;
+        visibility?: string;
+        sourceType?: string;
+        sourceSessionKey?: string;
+        sourceRef?: string;
+        expiresAt?: string;
+    }): Fact;
+    /**
+     * Get active facts for an agent.
+     */
+    getActiveFacts(agentId: string, opts?: {
+        scope?: FactScope;
+        domain?: string;
+        limit?: number;
+        minConfidence?: number;
+    }): Fact[];
+    /**
+     * Full-text search facts.
+     */
+    searchFacts(query: string, opts?: {
+        agentId?: string;
+        domain?: string;
+        visibility?: string;
+        limit?: number;
+    }): Fact[];
+    /**
+     * Mark an old fact as superseded by a new one.
+     *
+     * Sets `superseded_by` on the old fact row so it is excluded from active
+     * retrieval queries (both FTS and KNN paths check `superseded_by IS NULL`).
+     * Returns false if the fact is already superseded or does not exist.
+     */
+    markSuperseded(oldFactId: number, newFactId: number): boolean;
+    /**
+     * Find the most recent active fact for an agent whose content is a near-duplicate
+     * of the given content (same first 100 chars, different suffix, or same domain+topic).
+     * Used by the background indexer to detect supersedes relationships.
+     *
+     * Returns the existing fact id if a candidate is found, otherwise null.
+     */
+    findSupersedableByContent(agentId: string, content: string, opts?: {
+        domain?: string;
+    }): number | null;
+    /**
+     * Decay all facts by a fixed rate.
+     */
+    decayFacts(agentId: string, decayRate?: number): number;
+    /**
+     * Remove expired and fully decayed facts.
+     */
+    pruneFacts(agentId: string): number;
+    /**
+     * Get fact count for an agent.
+     */
+    getFactCount(agentId: string): number;
+}
+//# sourceMappingURL=fact-store.d.ts.map

package/dist/fact-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-store.d.ts","sourceRoot":"","sources":["../src/fact-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA2BlD,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,OAAO,CACL,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,IAAI;IA4EP;;OAEG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,IAAI,EAAE;IAkCT;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI,EAAE;IAoCV;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAY7D;;;;;;OAMG;IACH,yBAAyB,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzB,MAAM,GAAG,IAAI;IA0BhB;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM;IAU7D;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAanC;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAMtC"}