@psiclawops/hypermem 0.9.1 → 0.9.3

package/dist/spawn-context.js

@@ -0,0 +1,159 @@
+/**
+ * hypermem Spawn Context — Subagent Context Inheritance
+ *
+ * Provides tools to snapshot a parent session's working context and make it
+ * available to a spawned subagent at compose time.
+ *
+ * Usage:
+ *   const ctx = await buildSpawnContext(messageStore, docChunkStore, agentId, {
+ *     parentSessionKey: 'agent:agent1:webchat:main',
+ *     workingSnapshot: 10,
+ *     documents: ['/path/to/spec.md'],
+ *   });
+ *   // Inject ctx.parentContextBlock into the subagent task prompt.
+ *   // Pass ctx.sessionKey as ComposeRequest.parentSessionKey for doc chunk retrieval.
+ *   // When done: docChunkStore.clearSessionChunks(ctx.sessionKey);
+ */
+import { readFile } from 'node:fs/promises';
+// ─── Constants ──────────────────────────────────────────────────
+const DEFAULT_WORKING_SNAPSHOT = 25;
+const MAX_WORKING_SNAPSHOT = 50;
+const DEFAULT_BUDGET_TOKENS = 4000;
+const MAX_CHUNK_CHARS = 500;
+const CHUNK_OVERLAP_CHARS = 50;
+// ─── Helpers ────────────────────────────────────────────────────
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Split text on double-newlines, max 500 chars per chunk, with overlap.
+ */
+function chunkText(text) {
+    const paragraphs = text.split(/\n\n+/);
+    const chunks = [];
+    let current = '';
+    for (const para of paragraphs) {
+        const trimmed = para.trim();
+        if (!trimmed)
+            continue;
+        if (current.length === 0) {
+            current = trimmed;
+        }
+        else if (current.length + trimmed.length + 2 <= MAX_CHUNK_CHARS) {
+            current += '\n\n' + trimmed;
+        }
+        else {
+            // Flush current chunk
+            chunks.push(current);
+            // Start new chunk with overlap from end of previous chunk
+            const overlap = current.slice(-CHUNK_OVERLAP_CHARS);
+            current = (overlap.trim() ? overlap.trim() + '\n\n' : '') + trimmed;
+        }
+    }
+    if (current.trim()) {
+        chunks.push(current.trim());
+    }
+    // If text had no double-newlines or a single large paragraph, split by chars
+    if (chunks.length === 0 && text.trim()) {
+        let pos = 0;
+        const raw = text.trim();
+        while (pos < raw.length) {
+            const end = Math.min(pos + MAX_CHUNK_CHARS, raw.length);
+            chunks.push(raw.slice(pos, end));
+            pos += MAX_CHUNK_CHARS - CHUNK_OVERLAP_CHARS;
+        }
+    }
+    return chunks;
+}
+// ─── Main Function ───────────────────────────────────────────────
+/**
+ * Build a spawn context for a subagent by snapshotting the parent session.
+ *
+ * 1. Generates a unique session key for this spawn.
+ * 2. Pulls recent turns from the parent session (L2 messages).
+ * 3. Formats them into a compact block for injection into the task prompt.
+ * 4. Optionally chunks and indexes documents as session-scoped doc chunks.
+ * 5. Returns the context block, spawn session key, and a summary.
+ *
+ * Errors are handled gracefully — this function never throws.
+ */
+export async function buildSpawnContext(messageStore, docChunkStore, agentId, options) {
+    const sessionKey = `spawn:${agentId}:${Date.now()}`;
+    const budgetTokens = options.budgetTokens ?? DEFAULT_BUDGET_TOKENS;
+    const snapshotN = Math.min(options.workingSnapshot ?? DEFAULT_WORKING_SNAPSHOT, MAX_WORKING_SNAPSHOT);
+    const summary = {
+        turnsIncluded: 0,
+        documentsIndexed: 0,
+        documentsSkipped: [],
+        tokenEstimate: 0,
+    };
+    // ── Step 1: Get recent turns from parent session ─────────────
+    let parentContextBlock = null;
+    try {
+        let turns = messageStore.getRecentTurns(options.parentSessionKey, snapshotN);
+        if (turns.length > 0) {
+            // Format turns into compact block
+            const formatBlock = (ts) => {
+                const lines = [
+                    `## Parent Session Context`,
+                    `[Last ${ts.length} turns from session ${options.parentSessionKey}]`,
+                    '',
+                ];
+                for (const turn of ts) {
+                    const roleLabel = turn.role === 'user' ? 'User' : 'Assistant';
+                    const content = turn.content?.trim() || '(empty)';
+                    lines.push(`${roleLabel}: ${content}`);
+                }
+                return lines.join('\n');
+            };
+            let block = formatBlock(turns);
+            let tokenEst = estimateTokens(block);
+            // If over 60% of budget, truncate from oldest end
+            const maxContextTokens = Math.floor(budgetTokens * 0.6);
+            if (tokenEst > maxContextTokens) {
+                // Binary-ish approach: drop turns from the front until we fit
+                while (turns.length > 1 && estimateTokens(formatBlock(turns)) > maxContextTokens) {
+                    turns = turns.slice(1);
+                }
+                block = formatBlock(turns);
+                tokenEst = estimateTokens(block);
+            }
+            if (turns.length > 0) {
+                parentContextBlock = block;
+                summary.turnsIncluded = turns.length;
+                summary.tokenEstimate += tokenEst;
+            }
+        }
+    }
+    catch (err) {
+        console.warn('[hypermem:spawn-context] Failed to get recent turns:', err.message);
+    }
+    // ── Step 2: Index documents as session-scoped doc chunks ─────
+    const documents = options.documents ?? [];
+    for (const docPath of documents) {
+        try {
+            const content = await readFile(docPath, 'utf8');
+            const chunks = chunkText(content);
+            if (chunks.length === 0) {
+                summary.documentsSkipped.push(docPath);
+                continue;
+            }
+            docChunkStore.indexDocChunks(agentId, docPath, chunks, { sessionKey });
+            summary.documentsIndexed++;
+            // Add rough token estimate for documents
+            summary.tokenEstimate += estimateTokens(content);
+        }
+        catch (err) {
+            // File not found or unreadable — skip gracefully
+            const msg = err.message;
+            console.warn(`[hypermem:spawn-context] Skipping document "${docPath}": ${msg}`);
+            summary.documentsSkipped.push(docPath);
+        }
+    }
+    return {
+        parentContextBlock,
+        sessionKey,
+        summary,
+    };
+}
+//# sourceMappingURL=spawn-context.js.map

package/dist/system-store.d.ts

@@ -0,0 +1,73 @@
+/**
+ * hypermem System Registry Store
+ *
+ * Server config, service states, operational flags.
+ * Lives in the central library DB.
+ * The source of truth for "what's running and what state is it in."
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface SystemState {
+    id: number;
+    category: string;
+    key: string;
+    value: unknown;
+    updatedAt: string;
+    updatedBy: string | null;
+    ttl: string | null;
+}
+export interface SystemEvent {
+    id: number;
+    category: string;
+    key: string;
+    eventType: string;
+    oldValue: unknown;
+    newValue: unknown;
+    agentId: string | null;
+    createdAt: string;
+    metadata: Record<string, unknown> | null;
+}
+export declare class SystemStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Set a system state value. Records a change event if the value changed.
+     */
+    set(category: string, key: string, value: unknown, opts?: {
+        updatedBy?: string;
+        ttl?: string;
+    }): SystemState;
+    /**
+     * Get a system state value.
+     */
+    get(category: string, key: string): SystemState | null;
+    /**
+     * Get all state in a category.
+     */
+    getCategory(category: string): SystemState[];
+    /**
+     * Delete a system state entry.
+     */
+    delete(category: string, key: string, agentId?: string): boolean;
+    /**
+     * Record an event without changing state (e.g., restart, error, warning).
+     */
+    recordEvent(category: string, key: string, eventType: string, opts?: {
+        agentId?: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Get recent events for a category/key.
+     */
+    getEvents(opts?: {
+        category?: string;
+        key?: string;
+        eventType?: string;
+        since?: string;
+        limit?: number;
+    }): SystemEvent[];
+    /**
+     * Prune expired TTL entries.
+     */
+    pruneExpired(): number;
+}
+//# sourceMappingURL=system-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"system-store.d.ts","sourceRoot":"","sources":["../src/system-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1C;AAqCD,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE;QACL,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GACA,WAAW;IA8Bd;;OAEG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAsBtD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IAW5C;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAmBhE;;OAEG;IACH,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GACA,IAAI;IAcP;;OAEG;IACH,SAAS,CAAC,IAAI,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,WAAW,EAAE;IA4BjB;;OAEG;IACH,YAAY,IAAI,MAAM;CAQvB"}

package/dist/system-store.js

@@ -0,0 +1,182 @@
+/**
+ * hypermem System Registry Store
+ *
+ * Server config, service states, operational flags.
+ * Lives in the central library DB.
+ * The source of truth for "what's running and what state is it in."
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+function parseStateRow(row) {
+    let value;
+    try {
+        value = JSON.parse(row.value);
+    }
+    catch {
+        value = row.value;
+    }
+    return {
+        id: row.id,
+        category: row.category,
+        key: row.key,
+        value,
+        updatedAt: row.updated_at,
+        updatedBy: row.updated_by || null,
+        ttl: row.ttl || null,
+    };
+}
+function parseEventRow(row) {
+    let oldValue;
+    let newValue;
+    let metadata = null;
+    try {
+        oldValue = row.old_value ? JSON.parse(row.old_value) : null;
+    }
+    catch {
+        oldValue = row.old_value;
+    }
+    try {
+        newValue = row.new_value ? JSON.parse(row.new_value) : null;
+    }
+    catch {
+        newValue = row.new_value;
+    }
+    try {
+        metadata = row.metadata ? JSON.parse(row.metadata) : null;
+    }
+    catch { /* ignore */ }
+    return {
+        id: row.id,
+        category: row.category,
+        key: row.key,
+        eventType: row.event_type,
+        oldValue,
+        newValue,
+        agentId: row.agent_id || null,
+        createdAt: row.created_at,
+        metadata,
+    };
+}
+export class SystemStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Set a system state value. Records a change event if the value changed.
+     */
+    set(category, key, value, opts) {
+        const now = nowIso();
+        const valueStr = JSON.stringify(value);
+        // Get old value for change tracking
+        const old = this.db.prepare('SELECT value FROM system_state WHERE category = ? AND key = ?').get(category, key);
+        this.db.prepare(`
+      INSERT INTO system_state (category, key, value, updated_at, updated_by, ttl)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(category, key) DO UPDATE SET
+        value = excluded.value,
+        updated_at = excluded.updated_at,
+        updated_by = excluded.updated_by,
+        ttl = COALESCE(excluded.ttl, ttl)
+    `).run(category, key, valueStr, now, opts?.updatedBy || null, opts?.ttl || null);
+        // Record change event if value actually changed
+        if (!old || old.value !== valueStr) {
+            this.db.prepare(`
+        INSERT INTO system_events (category, key, event_type, old_value, new_value, agent_id, created_at)
+        VALUES (?, ?, 'changed', ?, ?, ?, ?)
+      `).run(category, key, old?.value || null, valueStr, opts?.updatedBy || null, now);
+        }
+        return this.get(category, key);
+    }
+    /**
+     * Get a system state value.
+     */
+    get(category, key) {
+        const row = this.db.prepare('SELECT * FROM system_state WHERE category = ? AND key = ?').get(category, key);
+        if (!row)
+            return null;
+        // Check TTL
+        const state = parseStateRow(row);
+        if (state.ttl) {
+            const ttlDate = new Date(state.ttl);
+            if (ttlDate < new Date()) {
+                // Expired — delete and return null
+                this.db.prepare('DELETE FROM system_state WHERE category = ? AND key = ?')
+                    .run(category, key);
+                return null;
+            }
+        }
+        return state;
+    }
+    /**
+     * Get all state in a category.
+     */
+    getCategory(category) {
+        const rows = this.db.prepare('SELECT * FROM system_state WHERE category = ? ORDER BY key').all(category);
+        return rows.map(parseStateRow).filter(s => {
+            if (s.ttl && new Date(s.ttl) < new Date())
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Delete a system state entry.
+     */
+    delete(category, key, agentId) {
+        const old = this.db.prepare('SELECT value FROM system_state WHERE category = ? AND key = ?').get(category, key);
+        const result = this.db.prepare('DELETE FROM system_state WHERE category = ? AND key = ?').run(category, key);
+        if (old && result.changes > 0) {
+            this.db.prepare(`
+        INSERT INTO system_events (category, key, event_type, old_value, agent_id, created_at)
+        VALUES (?, ?, 'deleted', ?, ?, ?)
+      `).run(category, key, old.value, agentId || null, nowIso());
+        }
+        return result.changes > 0;
+    }
+    /**
+     * Record an event without changing state (e.g., restart, error, warning).
+     */
+    recordEvent(category, key, eventType, opts) {
+        this.db.prepare(`
+      INSERT INTO system_events (category, key, event_type, agent_id, created_at, metadata)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(category, key, eventType, opts?.agentId || null, nowIso(), opts?.metadata ? JSON.stringify(opts.metadata) : null);
+    }
+    /**
+     * Get recent events for a category/key.
+     */
+    getEvents(opts) {
+        let sql = 'SELECT * FROM system_events WHERE 1=1';
+        const params = [];
+        if (opts?.category) {
+            sql += ' AND category = ?';
+            params.push(opts.category);
+        }
+        if (opts?.key) {
+            sql += ' AND key = ?';
+            params.push(opts.key);
+        }
+        if (opts?.eventType) {
+            sql += ' AND event_type = ?';
+            params.push(opts.eventType);
+        }
+        if (opts?.since) {
+            sql += ' AND created_at > ?';
+            params.push(opts.since);
+        }
+        sql += ' ORDER BY created_at DESC LIMIT ?';
+        params.push(opts?.limit || 50);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseEventRow);
+    }
+    /**
+     * Prune expired TTL entries.
+     */
+    pruneExpired() {
+        const now = nowIso();
+        const result = this.db.prepare("DELETE FROM system_state WHERE ttl IS NOT NULL AND ttl < ?").run(now);
+        return result.changes;
+    }
+}
+//# sourceMappingURL=system-store.js.map

package/dist/temporal-store.d.ts

@@ -0,0 +1,81 @@
+/**
+ * hypermem Temporal Store
+ *
+ * Time-range retrieval over indexed facts. Uses the temporal_index table
+ * in library.db to answer LoCoMo-style temporal questions:
+ *   "What happened before X?"
+ *   "What changed between January and March?"
+ *   "What was the most recent thing about Y?"
+ *
+ * occurred_at is initially populated from created_at (ingest time as proxy,
+ * confidence=0.5). Future: date extraction from fact text (confidence=0.9).
+ *
+ * Query path: SQL time-range filter on temporal_index JOIN facts.
+ * No vector search involved — purely temporal ordering.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface TemporalFact {
+    factId: number;
+    agentId: string;
+    content: string;
+    domain: string | null;
+    occurredAt: number;
+    ingestAt: number;
+    timeRef: string | null;
+    confidence: number;
+}
+export interface TemporalQueryOptions {
+    /** Start of time range (unix ms). Omit for open-ended. */
+    fromMs?: number;
+    /** End of time range (unix ms). Omit for open-ended. */
+    toMs?: number;
+    /** Only return facts from this agent. */
+    agentId?: string;
+    /** Only return facts with this domain. */
+    domain?: string;
+    /** Sort order. Default: DESC (most recent first). */
+    order?: 'ASC' | 'DESC';
+    /** Max results. Default: 20. */
+    limit?: number;
+    /** Minimum confidence on temporal placement. Default: 0. */
+    minConfidence?: number;
+}
+/**
+ * Returns true if the query string contains temporal signals.
+ */
+export declare function hasTemporalSignals(query: string): boolean;
+export declare class TemporalStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Index a newly created or updated fact into temporal_index.
+     * Uses created_at as occurred_at proxy (confidence=0.5).
+     * Safe to call multiple times — uses INSERT OR REPLACE.
+     */
+    indexFact(factId: number, agentId: string, createdAt: string, opts?: {
+        timeRef?: string;
+        confidence?: number;
+        occurredAt?: number;
+        validFrom?: string;
+    }): void;
+    /**
+     * Time-range query. Returns facts in temporal order.
+     * Joins temporal_index with facts to get content.
+     */
+    timeRangeQuery(opts?: TemporalQueryOptions): TemporalFact[];
+    /**
+     * Get the most recent N facts for an agent (no time bounds).
+     * Useful for "what was the last thing about X" style queries.
+     */
+    mostRecent(agentId: string, limit?: number): TemporalFact[];
+    /**
+     * Get fact count in the temporal index for an agent.
+     */
+    getIndexedCount(agentId: string): number;
+    /**
+     * Backfill any facts not yet in the temporal index.
+     * Safe to run multiple times. Uses INSERT OR IGNORE.
+     */
+    backfill(): number;
+}
+//# sourceMappingURL=temporal-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-store.d.ts","sourceRoot":"","sources":["../src/temporal-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAeD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;;;OAIG;IACH,SAAS,CACP,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACxF,IAAI;IAkBP;;;OAGG;IACH,cAAc,CAAC,IAAI,GAAE,oBAAyB,GAAG,YAAY,EAAE;IAgE/D;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,YAAY,EAAE;IAIvD;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOxC;;;OAGG;IACH,QAAQ,IAAI,MAAM;CAenB"}

package/dist/temporal-store.js

@@ -0,0 +1,149 @@
+/**
+ * hypermem Temporal Store
+ *
+ * Time-range retrieval over indexed facts. Uses the temporal_index table
+ * in library.db to answer LoCoMo-style temporal questions:
+ *   "What happened before X?"
+ *   "What changed between January and March?"
+ *   "What was the most recent thing about Y?"
+ *
+ * occurred_at is initially populated from created_at (ingest time as proxy,
+ * confidence=0.5). Future: date extraction from fact text (confidence=0.9).
+ *
+ * Query path: SQL time-range filter on temporal_index JOIN facts.
+ * No vector search involved — purely temporal ordering.
+ */
+/**
+ * Temporal signal keywords. If any of these appear in a query string,
+ * the temporal retrieval path fires alongside vector/FTS retrieval.
+ */
+const TEMPORAL_SIGNALS = [
+    'before', 'after', 'when', 'during', 'between', 'since', 'until',
+    'last', 'first', 'recent', 'earlier', 'later', 'previously', 'at the time',
+    'used to', 'now', 'still', 'anymore', 'changed', 'updated', 'latest',
+    'yesterday', 'today', 'week', 'month', 'year', 'january', 'february',
+    'march', 'april', 'may', 'june', 'july', 'august', 'september',
+    'october', 'november', 'december', 'q1', 'q2', 'q3', 'q4',
+];
+/**
+ * Returns true if the query string contains temporal signals.
+ */
+export function hasTemporalSignals(query) {
+    const lower = query.toLowerCase();
+    return TEMPORAL_SIGNALS.some(signal => lower.includes(signal));
+}
+export class TemporalStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Index a newly created or updated fact into temporal_index.
+     * Uses created_at as occurred_at proxy (confidence=0.5).
+     * Safe to call multiple times — uses INSERT OR REPLACE.
+     */
+    indexFact(factId, agentId, createdAt, opts) {
+        const ingestMs = new Date(createdAt).getTime();
+        const occurredMs = opts?.occurredAt ?? ingestMs;
+        this.db.prepare(`
+      INSERT OR REPLACE INTO temporal_index
+        (fact_id, agent_id, occurred_at, ingest_at, time_ref, confidence)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(factId, agentId, occurredMs, ingestMs, opts?.timeRef ?? null, opts?.confidence ?? 0.5);
+    }
+    /**
+     * Time-range query. Returns facts in temporal order.
+     * Joins temporal_index with facts to get content.
+     */
+    timeRangeQuery(opts = {}) {
+        const limit = opts.limit ?? 20;
+        const order = opts.order ?? 'DESC';
+        const minConf = opts.minConfidence ?? 0;
+        const params = [minConf];
+        const conditions = [
+            'f.superseded_by IS NULL',
+            'f.decay_score < 0.8',
+            't.confidence >= ?',
+        ];
+        if (opts.agentId) {
+            conditions.push('t.agent_id = ?');
+            params.push(opts.agentId);
+        }
+        if (opts.domain) {
+            conditions.push('f.domain = ?');
+            params.push(opts.domain);
+        }
+        if (opts.fromMs !== undefined) {
+            conditions.push('t.occurred_at >= ?');
+            params.push(opts.fromMs);
+        }
+        if (opts.toMs !== undefined) {
+            conditions.push('t.occurred_at <= ?');
+            params.push(opts.toMs);
+        }
+        const where = conditions.length > 0
+            ? `WHERE ${conditions.join(' AND ')}`
+            : '';
+        const sql = `
+      SELECT
+        t.fact_id,
+        t.agent_id,
+        f.content,
+        f.domain,
+        t.occurred_at,
+        t.ingest_at,
+        t.time_ref,
+        t.confidence
+      FROM temporal_index t
+      JOIN facts f ON f.id = t.fact_id
+      ${where}
+      ORDER BY t.occurred_at ${order}
+      LIMIT ?
+    `;
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(r => ({
+            factId: r.fact_id,
+            agentId: r.agent_id,
+            content: r.content,
+            domain: r.domain || null,
+            occurredAt: r.occurred_at,
+            ingestAt: r.ingest_at,
+            timeRef: r.time_ref || null,
+            confidence: r.confidence,
+        }));
+    }
+    /**
+     * Get the most recent N facts for an agent (no time bounds).
+     * Useful for "what was the last thing about X" style queries.
+     */
+    mostRecent(agentId, limit = 10) {
+        return this.timeRangeQuery({ agentId, limit, order: 'DESC' });
+    }
+    /**
+     * Get fact count in the temporal index for an agent.
+     */
+    getIndexedCount(agentId) {
+        const row = this.db.prepare('SELECT COUNT(*) AS count FROM temporal_index WHERE agent_id = ?').get(agentId);
+        return row.count;
+    }
+    /**
+     * Backfill any facts not yet in the temporal index.
+     * Safe to run multiple times. Uses INSERT OR IGNORE.
+     */
+    backfill() {
+        const result = this.db.prepare(`
+      INSERT OR IGNORE INTO temporal_index (fact_id, agent_id, occurred_at, ingest_at, confidence)
+      SELECT
+        id,
+        agent_id,
+        CAST((julianday(created_at) - 2440587.5) * 86400000 AS INTEGER),
+        CAST((julianday(created_at) - 2440587.5) * 86400000 AS INTEGER),
+        0.5
+      FROM facts
+      WHERE superseded_by IS NULL
+    `).run();
+        return result.changes;
+    }
+}
+//# sourceMappingURL=temporal-store.js.map