@psiclawops/hypermem 0.5.0 → 0.5.2

package/dist/session-topic-map.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SessionTopicMap (P3.3)
+ *
+ * Manages per-session topic state in messages.db.
+ * Topics table: id(TEXT), session_key, name, created_at, last_active_at,
+ *               message_count, metadata
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export declare class SessionTopicMap {
+    private db;
+    constructor(db: DatabaseSync);
+    /**
+     * Get the active topic for a session (most recently active).
+     */
+    getActiveTopic(sessionKey: string): {
+        id: string;
+        name: string;
+    } | null;
+    /**
+     * Activate a topic: update last_active_at to now.
+     */
+    activateTopic(sessionKey: string, topicId: string): void;
+    /**
+     * Create a new topic and activate it. Returns the new topicId.
+     */
+    createTopic(sessionKey: string, name: string): string;
+    /**
+     * List all topics for a session, ordered by last_active_at DESC.
+     */
+    listTopics(sessionKey: string): Array<{
+        id: string;
+        name: string;
+        messageCount: number;
+        lastActiveAt: number;
+    }>;
+    /**
+     * Increment message count for the given topic.
+     */
+    incrementMessageCount(topicId: string): void;
+}
+//# sourceMappingURL=session-topic-map.d.ts.map

package/dist/session-topic-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-topic-map.d.ts","sourceRoot":"","sources":["../src/session-topic-map.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,qBAAa,eAAe;IACd,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAEpC;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAYvE;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAQxD;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAUrD;;OAEG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC;QACpC,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IAqBF;;OAEG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAO7C"}

package/dist/session-topic-map.js

@@ -0,0 +1,77 @@
+/**
+ * SessionTopicMap (P3.3)
+ *
+ * Manages per-session topic state in messages.db.
+ * Topics table: id(TEXT), session_key, name, created_at, last_active_at,
+ *               message_count, metadata
+ */
+import { randomUUID } from 'node:crypto';
+export class SessionTopicMap {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Get the active topic for a session (most recently active).
+     */
+    getActiveTopic(sessionKey) {
+        const row = this.db.prepare(`
+      SELECT id, name
+      FROM topics
+      WHERE session_key = ?
+      ORDER BY last_active_at DESC
+      LIMIT 1
+    `).get(sessionKey);
+        return row ?? null;
+    }
+    /**
+     * Activate a topic: update last_active_at to now.
+     */
+    activateTopic(sessionKey, topicId) {
+        this.db.prepare(`
+      UPDATE topics
+      SET last_active_at = ?
+      WHERE id = ? AND session_key = ?
+    `).run(Date.now(), topicId, sessionKey);
+    }
+    /**
+     * Create a new topic and activate it. Returns the new topicId.
+     */
+    createTopic(sessionKey, name) {
+        const id = randomUUID();
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO topics (id, session_key, name, created_at, last_active_at, message_count, metadata)
+      VALUES (?, ?, ?, ?, ?, 0, NULL)
+    `).run(id, sessionKey, name.slice(0, 40), now, now);
+        return id;
+    }
+    /**
+     * List all topics for a session, ordered by last_active_at DESC.
+     */
+    listTopics(sessionKey) {
+        const rows = this.db.prepare(`
+      SELECT id, name, message_count, last_active_at
+      FROM topics
+      WHERE session_key = ?
+      ORDER BY last_active_at DESC
+    `).all(sessionKey);
+        return rows.map(r => ({
+            id: r.id,
+            name: r.name,
+            messageCount: r.message_count,
+            lastActiveAt: r.last_active_at,
+        }));
+    }
+    /**
+     * Increment message count for the given topic.
+     */
+    incrementMessageCount(topicId) {
+        this.db.prepare(`
+      UPDATE topics
+      SET message_count = message_count + 1
+      WHERE id = ?
+    `).run(topicId);
+    }
+}
+//# sourceMappingURL=session-topic-map.js.map

package/dist/spawn-context.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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:forge: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 type { MessageStore } from './message-store.js';
+import type { DocChunkStore } from './doc-chunk-store.js';
+export interface SpawnContextOptions {
+    /** Parent session key to snapshot working context from */
+    parentSessionKey: string;
+    /** Number of recent turns to include (default 25, max 50) */
+    workingSnapshot?: number;
+    /** File paths to chunk and inject as session-scoped doc chunks */
+    documents?: string[];
+    /** Token budget for the entire spawn context (default 4000) */
+    budgetTokens?: number;
+}
+export interface SpawnContext {
+    /** Formatted parent context block for injection into subagent task prompt */
+    parentContextBlock: string | null;
+    /** Session key to use for querying injected doc chunks at compose time */
+    sessionKey: string;
+    /** Summary of what was injected (for logging) */
+    summary: {
+        turnsIncluded: number;
+        documentsIndexed: number;
+        documentsSkipped: string[];
+        tokenEstimate: number;
+    };
+}
+/**
+ * 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 declare function buildSpawnContext(messageStore: MessageStore, docChunkStore: DocChunkStore, agentId: string, options: SpawnContextOptions): Promise<SpawnContext>;
+//# sourceMappingURL=spawn-context.d.ts.map

package/dist/spawn-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-context.d.ts","sourceRoot":"","sources":["../src/spawn-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,OAAO,EAAE;QACP,aAAa,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;QACzB,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AA6DD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,YAAY,EAC1B,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,CA4FvB"}

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:forge: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,80 @@
+/**
+ * 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;
+    }): 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,CAAA;KAAE,GACpE,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"}