@psiclawops/hypermem 0.1.0 → 0.5.1

package/dist/vector-store.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem Vector Store — Semantic Search via sqlite-vec
+ * hypermem Vector Store — Semantic Search via sqlite-vec
  *
  * Provides embedding-backed KNN search over facts, knowledge, episodes,
  * and session registry entries. Uses Ollama (local) for embeddings,
@@ -9,28 +9,156 @@
  *   - One vec0 virtual table per indexed content type
  *   - Embeddings generated via local Ollama (nomic-embed-text, 768d)
  *   - Vectors stored alongside content in the same agent DB
- *   - Embedding cache to avoid redundant API calls
+ *   - LRU embedding cache (module-level, per-process) to avoid redundant Ollama calls
+ *   - Precomputed embedding passthrough: callers can supply an embedding to skip Ollama
  *   - Batch embedding support for bulk indexing
  */
 import { createHash } from 'node:crypto';
 const DEFAULT_EMBEDDING_CONFIG = {
+    provider: 'ollama',
     ollamaUrl: 'http://localhost:11434',
+    openaiBaseUrl: 'https://api.openai.com/v1',
     model: 'nomic-embed-text',
     dimensions: 768,
     timeout: 10000,
     batchSize: 32,
+    cacheSize: 128,
 };
+/** Provider-specific defaults applied when provider is 'openai' and fields are not set. */
+const OPENAI_DEFAULTS = {
+    model: 'text-embedding-3-small',
+    dimensions: 1536,
+    batchSize: 128,
+};
+const _embeddingCache = new Map();
+/**
+ * Insert an entry into the LRU cache, evicting the oldest if over capacity.
+ */
+function cachePut(key, embedding, maxSize) {
+    if (_embeddingCache.has(key)) {
+        // Update existing entry (refresh timestamp)
+        _embeddingCache.delete(key);
+    }
+    else if (_embeddingCache.size >= maxSize) {
+        // Evict oldest entry by timestamp
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [k, v] of _embeddingCache) {
+            if (v.timestamp < oldestTime) {
+                oldestTime = v.timestamp;
+                oldestKey = k;
+            }
+        }
+        if (oldestKey !== undefined) {
+            _embeddingCache.delete(oldestKey);
+        }
+    }
+    _embeddingCache.set(key, { embedding, timestamp: Date.now() });
+}
+/**
+ * Clear the embedding cache. Primarily for testing.
+ */
+export function clearEmbeddingCache() {
+    _embeddingCache.clear();
+}
+/**
+ * Generate embeddings via OpenAI Embeddings API.
+ * Batches up to batchSize inputs per request.
+ */
+async function generateOpenAIEmbeddings(texts, config) {
+    // Resolve API key: config > environment
+    const apiKey = config.openaiApiKey
+        ?? process.env.OPENROUTER_API_KEY
+        ?? process.env.OPENAI_API_KEY
+        ?? null;
+    if (!apiKey) {
+        throw new Error('[hypermem] OpenAI embedding provider requires an API key. ' +
+            'Set openaiApiKey in hypermem config, or set OPENROUTER_API_KEY / OPENAI_API_KEY env var.');
+    }
+    const baseUrl = config.openaiBaseUrl ?? 'https://api.openai.com/v1';
+    const model = config.model;
+    const results = [];
+    for (let i = 0; i < texts.length; i += config.batchSize) {
+        const batch = texts.slice(i, i + config.batchSize);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.timeout);
+        try {
+            const response = await fetch(`${baseUrl}/embeddings`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({ model, input: batch }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => '');
+                throw new Error(`OpenAI embedding failed: ${response.status} ${response.statusText} — ${body}`);
+            }
+            const data = await response.json();
+            // OpenAI returns results in order by default but may not guarantee it — sort by index.
+            const sorted = data.data.sort((a, b) => a.index - b.index);
+            for (const item of sorted) {
+                if (item.embedding.length !== config.dimensions) {
+                    throw new Error(`OpenAI embedding dimension mismatch: expected ${config.dimensions}, got ${item.embedding.length}. ` +
+                        'If you changed models, re-index via hypermem reindex.');
+                }
+                results.push(new Float32Array(item.embedding));
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return results;
+}
 /**
  * Generate embeddings via Ollama API.
  * Supports single and batch embedding.
+ * Results are cached per text hash — cache hits skip the Ollama call entirely.
  */
 export async function generateEmbeddings(texts, config = DEFAULT_EMBEDDING_CONFIG) {
+    // Apply provider-specific defaults when provider is 'openai' and fields are at Ollama defaults
+    if (config.provider === 'openai') {
+        // Merge: OpenAI defaults fill in any unset fields, user-supplied values always win
+        config = {
+            ...DEFAULT_EMBEDDING_CONFIG,
+            ...config,
+            model: config.model !== DEFAULT_EMBEDDING_CONFIG.model ? config.model : OPENAI_DEFAULTS.model,
+            dimensions: config.dimensions !== DEFAULT_EMBEDDING_CONFIG.dimensions ? config.dimensions : OPENAI_DEFAULTS.dimensions,
+            batchSize: config.batchSize !== DEFAULT_EMBEDDING_CONFIG.batchSize ? config.batchSize : OPENAI_DEFAULTS.batchSize,
+        };
+        // OpenAI path — no LRU cache (responses are billed; caching at this layer
+        // adds complexity without proportional benefit given async background use).
+        return generateOpenAIEmbeddings(texts, config);
+    }
     if (texts.length === 0)
         return [];
-    const results = [];
+    const maxSize = Math.min(config.cacheSize ?? DEFAULT_EMBEDDING_CONFIG.cacheSize ?? 128, 10_000 // Hard cap: prevent unbounded memory growth from operator misconfiguration
+    );
+    const results = new Array(texts.length).fill(null);
+    // Check cache first — build list of texts that need Ollama calls
+    const uncachedIndices = [];
+    for (let i = 0; i < texts.length; i++) {
+        const key = simpleHash(texts[i]);
+        const cached = _embeddingCache.get(key);
+        if (cached) {
+            results[i] = cached.embedding;
+        }
+        else {
+            uncachedIndices.push(i);
+        }
+    }
+    if (uncachedIndices.length === 0) {
+        return results;
+    }
+    // Fetch uncached texts from Ollama in batches
+    const uncachedTexts = uncachedIndices.map(i => texts[i]);
+    const ollamaResults = [];
     // Ollama /api/embed supports batch via `input` array
-    for (let i = 0; i < texts.length; i += config.batchSize) {
-        const batch = texts.slice(i, i + config.batchSize);
+    for (let i = 0; i < uncachedTexts.length; i += config.batchSize) {
+        const batch = uncachedTexts.slice(i, i + config.batchSize);
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), config.timeout);
         try {
@@ -51,13 +179,20 @@ export async function generateEmbeddings(texts, config = DEFAULT_EMBEDDING_CONFI
                 if (embedding.length !== config.dimensions) {
                     throw new Error(`Embedding dimension mismatch: expected ${config.dimensions}, got ${embedding.length}`);
                 }
-                results.push(new Float32Array(embedding));
+                ollamaResults.push(new Float32Array(embedding));
             }
         }
         finally {
             clearTimeout(timer);
         }
     }
+    // Populate cache and fill results array
+    for (let j = 0; j < uncachedIndices.length; j++) {
+        const origIdx = uncachedIndices[j];
+        const embedding = ollamaResults[j];
+        results[origIdx] = embedding;
+        cachePut(simpleHash(texts[origIdx]), embedding, maxSize);
+    }
     return results;
 }
 /**
@@ -233,6 +368,10 @@ export class VectorStore {
     }
     /**
      * Semantic KNN search across one or all vector tables.
+     *
+     * @param precomputedEmbedding — optional pre-computed embedding for the query.
+     *   When provided, skips the Ollama call entirely. The precomputed embedding
+     *   is still inserted into the LRU cache so subsequent identical queries hit.
      */
     async search(query, opts) {
         const limit = opts?.limit || 10;
@@ -241,8 +380,17 @@ export class VectorStore {
         for (const table of tables) {
             this.validateSourceTable(table);
         }
-        // Generate query embedding
-        const [queryEmbedding] = await generateEmbeddings([query], this.config);
+        // Use precomputed embedding if provided, otherwise call Ollama
+        let queryEmbedding;
+        if (opts?.precomputedEmbedding) {
+            queryEmbedding = opts.precomputedEmbedding;
+            // Populate LRU cache so subsequent queries for the same text hit
+            const maxSize = this.config.cacheSize ?? 128;
+            cachePut(simpleHash(query), queryEmbedding, maxSize);
+        }
+        else {
+            [queryEmbedding] = await generateEmbeddings([query], this.config);
+        }
         const queryBytes = vecToBytes(queryEmbedding);
         const results = [];
         for (const table of tables) {
@@ -300,13 +448,13 @@ export class VectorStore {
         switch (table) {
             case 'facts': {
                 const row = sourceDb
-                    .prepare('SELECT content, domain, agent_id FROM facts WHERE id = ?')
+                    .prepare('SELECT content, domain, agent_id FROM facts WHERE id = ? AND superseded_by IS NULL')
                     .get(id);
                 return row ? { content: row.content, domain: row.domain, agentId: row.agent_id } : null;
             }
             case 'knowledge': {
                 const row = sourceDb
-                    .prepare('SELECT content, domain, agent_id, key FROM knowledge WHERE id = ?')
+                    .prepare('SELECT content, domain, agent_id, key FROM knowledge WHERE id = ? AND superseded_by IS NULL')
                     .get(id);
                 return row
                     ? { content: row.content, domain: row.domain, agentId: row.agent_id, metadata: row.key }
@@ -409,6 +557,37 @@ export class VectorStore {
         }
         return pruned;
     }
+    /**
+     * Remove the vector index entry for a single source item.
+     *
+     * Deletes both the vec table row and the vec_index_map entry for the given
+     * (sourceTable, sourceId) pair. Used by the background indexer for immediate
+     * point-in-time removal when a supersedes relationship is detected.
+     *
+     * @returns true if an entry was found and removed, false if nothing was indexed.
+     */
+    removeItem(sourceTable, sourceId) {
+        this.validateSourceTable(sourceTable);
+        const entry = this.db
+            .prepare('SELECT id, vec_table FROM vec_index_map WHERE source_table = ? AND source_id = ?')
+            .get(sourceTable, sourceId);
+        if (!entry)
+            return false;
+        this.db.prepare(`DELETE FROM ${entry.vec_table} WHERE rowid = CAST(? AS INTEGER)`).run(entry.id);
+        this.db.prepare('DELETE FROM vec_index_map WHERE id = ?').run(entry.id);
+        return true;
+    }
+    /**
+     * Check whether a source item already has a vector in the index.
+     * Used by the episode backfill to skip already-vectorized entries.
+     */
+    hasItem(sourceTable, sourceId) {
+        this.validateSourceTable(sourceTable);
+        const row = this.db
+            .prepare('SELECT 1 FROM vec_index_map WHERE source_table = ? AND source_id = ? LIMIT 1')
+            .get(sourceTable, sourceId);
+        return row !== undefined;
+    }
     /**
      * Tombstone vector entries for superseded facts and knowledge.
      *

package/dist/version.d.ts

@@ -0,0 +1,34 @@
+/** Release version — matches package.json and is stamped into library.db on every startup. */
+export declare const ENGINE_VERSION = "0.5.0";
+/** Minimum Node.js version required — matches package.json engines field. */
+export declare const MIN_NODE_VERSION = "22.0.0";
+/** @deprecated No longer used — Redis was replaced with SQLite :memory: CacheLayer. */
+export declare const MIN_REDIS_VERSION = "7.0.0";
+/** sqlite-vec version bundled with this release. */
+export declare const SQLITE_VEC_VERSION = "0.1.9";
+/**
+ * Main DB (hypermem.db) schema version.
+ * Re-exported here for convenience; authoritative value lives in schema.ts.
+ */
+export declare const MAIN_SCHEMA_VERSION = 6;
+/**
+ * Library DB (library.db) schema version.
+ * Re-exported here for convenience; authoritative value lives in library-schema.ts.
+ */
+export declare const LIBRARY_SCHEMA_VERSION_EXPORT = 12;
+/**
+ * Compatibility version — the single number operators and consumers check.
+ * Maps to: main schema v6, library schema v12.
+ * Matches ENGINE_VERSION for the 0.5.0 release.
+ */
+export declare const HYPERMEM_COMPAT_VERSION = "0.5.0";
+/**
+ * Schema compatibility map — machine-readable version requirements.
+ * Use this to verify DB schemas match the running engine.
+ */
+export declare const SCHEMA_COMPAT: {
+    readonly compatVersion: "0.5.0";
+    readonly mainSchema: 6;
+    readonly librarySchema: 12;
+};
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,WAAW,CAAC;AAEzC,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,oDAAoD;AACpD,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAC"}

package/dist/version.js

@@ -0,0 +1,34 @@
+/** Release version — matches package.json and is stamped into library.db on every startup. */
+export const ENGINE_VERSION = '0.5.0';
+/** Minimum Node.js version required — matches package.json engines field. */
+export const MIN_NODE_VERSION = '22.0.0';
+/** @deprecated No longer used — Redis was replaced with SQLite :memory: CacheLayer. */
+export const MIN_REDIS_VERSION = '7.0.0';
+/** sqlite-vec version bundled with this release. */
+export const SQLITE_VEC_VERSION = '0.1.9';
+/**
+ * Main DB (hypermem.db) schema version.
+ * Re-exported here for convenience; authoritative value lives in schema.ts.
+ */
+export const MAIN_SCHEMA_VERSION = 6;
+/**
+ * Library DB (library.db) schema version.
+ * Re-exported here for convenience; authoritative value lives in library-schema.ts.
+ */
+export const LIBRARY_SCHEMA_VERSION_EXPORT = 12;
+/**
+ * Compatibility version — the single number operators and consumers check.
+ * Maps to: main schema v6, library schema v12.
+ * Matches ENGINE_VERSION for the 0.5.0 release.
+ */
+export const HYPERMEM_COMPAT_VERSION = '0.5.0';
+/**
+ * Schema compatibility map — machine-readable version requirements.
+ * Use this to verify DB schemas match the running engine.
+ */
+export const SCHEMA_COMPAT = {
+    compatVersion: '0.5.0',
+    mainSchema: 6,
+    librarySchema: 12,
+};
+//# sourceMappingURL=version.js.map

package/dist/wiki-page-emitter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * wiki-page-emitter.ts
+ *
+ * Query-time API for the hypermem wiki layer.
+ * Retrieves synthesized topic pages, resolves cross-links,
+ * and triggers on-demand synthesis when pages are stale/missing.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import { type SynthesisConfig } from './topic-synthesizer.js';
+export interface WikiPage {
+    topicName: string;
+    content: string;
+    version: number;
+    updatedAt: string;
+    crossLinks: WikiLink[];
+}
+export interface WikiLink {
+    topicName: string;
+    linkType: string;
+    direction: 'from' | 'to';
+}
+export interface WikiPageSummary {
+    topicName: string;
+    updatedAt: string;
+    messageCount: number;
+    version: number;
+}
+export declare class WikiPageEmitter {
+    private readonly libraryDb;
+    private readonly getMessageDb;
+    private readonly synthConfig?;
+    private readonly knowledgeStore;
+    private readonly synthesizer;
+    private readonly regrowthThreshold;
+    constructor(libraryDb: DatabaseSync, getMessageDb: (agentId: string) => DatabaseSync | null, synthConfig?: Partial<SynthesisConfig> | undefined);
+    /**
+     * Fetch the version number for an active knowledge entry.
+     */
+    private getVersion;
+    /**
+     * Get a wiki page for a topic.
+     * If no page exists, or page is stale (topic has grown by >= regrowthThreshold
+     * since last synthesis), trigger a synthesis pass first.
+     * Returns null if topic has no messages or doesn't exist.
+     */
+    getPage(agentId: string, topicName: string): WikiPage | null;
+    /**
+     * List all synthesized pages for an agent — the table of contents.
+     */
+    listPages(agentId: string, opts?: {
+        limit?: number;
+        domain?: string;
+    }): WikiPageSummary[];
+    /**
+     * Get a page's cross-links from knowledge_links table.
+     * Resolves both directions (from and to).
+     */
+    private resolveLinks;
+    /**
+     * Force re-synthesis of a specific topic regardless of staleness.
+     * Returns the new page or null if topic not found.
+     */
+    forceSynthesize(agentId: string, topicName: string): WikiPage | null;
+}
+//# sourceMappingURL=wiki-page-emitter.d.ts.map

package/dist/wiki-page-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-page-emitter.d.ts","sourceRoot":"","sources":["../src/wiki-page-emitter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAoB,KAAK,eAAe,EAAgC,MAAM,wBAAwB,CAAC;AAI9G,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAeD,qBAAa,eAAe;IAMxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAP/B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAGxB,SAAS,EAAE,YAAY,EACvB,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,YAAY,GAAG,IAAI,EACtD,WAAW,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,YAAA;IAOzD;;OAEG;IACH,OAAO,CAAC,UAAU;IAclB;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAgE5D;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,eAAe,EAAE;IAgCzF;;;OAGG;IACH,OAAO,CAAC,YAAY;IAiEpB;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;CAyCrE"}

package/dist/wiki-page-emitter.js

@@ -0,0 +1,258 @@
+/**
+ * wiki-page-emitter.ts
+ *
+ * Query-time API for the hypermem wiki layer.
+ * Retrieves synthesized topic pages, resolves cross-links,
+ * and triggers on-demand synthesis when pages are stale/missing.
+ */
+import { KnowledgeStore } from './knowledge-store.js';
+import { TopicSynthesizer, SYNTHESIS_REGROWTH_THRESHOLD } from './topic-synthesizer.js';
+// ─── Helpers ────────────────────────────────────────────────────
+/**
+ * Parse message_count stored in source_ref ("topic:<id>:mc:<count>").
+ */
+function parseStoredMessageCount(sourceRef) {
+    if (!sourceRef)
+        return 0;
+    const match = sourceRef.match(/:mc:(\d+)$/);
+    return match ? parseInt(match[1], 10) : 0;
+}
+// ─── WikiPageEmitter ────────────────────────────────────────────
+export class WikiPageEmitter {
+    libraryDb;
+    getMessageDb;
+    synthConfig;
+    knowledgeStore;
+    synthesizer;
+    regrowthThreshold;
+    constructor(libraryDb, getMessageDb, synthConfig) {
+        this.libraryDb = libraryDb;
+        this.getMessageDb = getMessageDb;
+        this.synthConfig = synthConfig;
+        this.knowledgeStore = new KnowledgeStore(libraryDb);
+        this.synthesizer = new TopicSynthesizer(libraryDb, getMessageDb, synthConfig);
+        this.regrowthThreshold = synthConfig?.SYNTHESIS_REGROWTH_THRESHOLD ?? SYNTHESIS_REGROWTH_THRESHOLD;
+    }
+    /**
+     * Fetch the version number for an active knowledge entry.
+     */
+    getVersion(agentId, topicName) {
+        try {
+            const row = this.libraryDb.prepare(`
+        SELECT version FROM knowledge
+        WHERE agent_id = ? AND domain = 'topic-synthesis' AND key = ?
+        AND superseded_by IS NULL
+        LIMIT 1
+      `).get(agentId, topicName);
+            return row?.version ?? 1;
+        }
+        catch {
+            return 1;
+        }
+    }
+    /**
+     * Get a wiki page for a topic.
+     * If no page exists, or page is stale (topic has grown by >= regrowthThreshold
+     * since last synthesis), trigger a synthesis pass first.
+     * Returns null if topic has no messages or doesn't exist.
+     */
+    getPage(agentId, topicName) {
+        // Look up topic to check current message_count and existence
+        let topicRow;
+        try {
+            topicRow = this.libraryDb.prepare(`
+        SELECT id, message_count FROM topics
+        WHERE agent_id = ? AND name = ?
+        LIMIT 1
+      `).get(agentId, topicName);
+        }
+        catch {
+            // Topics table may not exist or topic not found
+        }
+        // Check existing synthesis
+        const existing = this.knowledgeStore.get(agentId, 'topic-synthesis', topicName);
+        if (existing) {
+            // Check staleness if we have topic data
+            if (topicRow) {
+                const storedMc = parseStoredMessageCount(existing.sourceRef);
+                const growth = topicRow.message_count - storedMc;
+                if (growth >= this.regrowthThreshold) {
+                    // Stale — re-synthesize by running a targeted tick
+                    // TopicSynthesizer.tick() picks up topics that have grown enough
+                    this.synthesizer.tick(agentId);
+                }
+            }
+        }
+        else {
+            // No page at all — trigger synthesis regardless of staleness threshold
+            if (!topicRow)
+                return null;
+            const messageDb = this.getMessageDb(agentId);
+            if (!messageDb)
+                return null;
+            // Check if there are actually messages for this topic before attempting synthesis
+            let msgCount = 0;
+            try {
+                const row = messageDb.prepare('SELECT COUNT(*) AS cnt FROM messages WHERE topic_id = ?').get(String(topicRow.id));
+                msgCount = row?.cnt ?? 0;
+            }
+            catch {
+                // messages table query failed
+            }
+            if (msgCount === 0)
+                return null;
+            this.synthesizer.tick(agentId);
+        }
+        // Re-fetch after possible synthesis
+        const knowledge = this.knowledgeStore.get(agentId, 'topic-synthesis', topicName);
+        if (!knowledge)
+            return null;
+        const crossLinks = this.resolveLinks(agentId, knowledge.id);
+        return {
+            topicName,
+            content: knowledge.content,
+            version: this.getVersion(agentId, topicName),
+            updatedAt: knowledge.updatedAt,
+            crossLinks,
+        };
+    }
+    /**
+     * List all synthesized pages for an agent — the table of contents.
+     */
+    listPages(agentId, opts) {
+        const domain = opts?.domain ?? 'topic-synthesis';
+        const limit = opts?.limit ?? 100;
+        let rows;
+        try {
+            rows = this.libraryDb.prepare(`
+        SELECT key, updated_at, version, source_ref
+        FROM knowledge
+        WHERE agent_id = ?
+          AND domain = ?
+          AND superseded_by IS NULL
+        ORDER BY updated_at DESC
+        LIMIT ?
+      `).all(agentId, domain, limit);
+        }
+        catch {
+            return [];
+        }
+        return rows.map(row => ({
+            topicName: row.key,
+            updatedAt: row.updated_at,
+            messageCount: parseStoredMessageCount(row.source_ref),
+            version: row.version,
+        }));
+    }
+    /**
+     * Get a page's cross-links from knowledge_links table.
+     * Resolves both directions (from and to).
+     */
+    resolveLinks(agentId, knowledgeId) {
+        const links = [];
+        // Outgoing links (from this knowledge entry to another)
+        let fromRows = [];
+        try {
+            fromRows = this.libraryDb.prepare(`
+        SELECT kl.to_id, kl.link_type
+        FROM knowledge_links kl
+        WHERE kl.from_type = 'knowledge' AND kl.from_id = ?
+          AND kl.to_type = 'knowledge'
+      `).all(knowledgeId);
+        }
+        catch {
+            // knowledge_links may not exist
+        }
+        for (const row of fromRows) {
+            // Look up the topic name from the target knowledge row
+            let targetKey = null;
+            try {
+                const targetRow = this.libraryDb.prepare(`
+          SELECT key FROM knowledge
+          WHERE id = ? AND agent_id = ? AND domain = 'topic-synthesis'
+        `).get(row.to_id, agentId);
+                targetKey = targetRow?.key ?? null;
+            }
+            catch {
+                // Ignore
+            }
+            if (targetKey) {
+                links.push({ topicName: targetKey, linkType: row.link_type, direction: 'from' });
+            }
+        }
+        // Incoming links (from other knowledge entries to this one)
+        let toRows = [];
+        try {
+            toRows = this.libraryDb.prepare(`
+        SELECT kl.from_id, kl.link_type
+        FROM knowledge_links kl
+        WHERE kl.to_type = 'knowledge' AND kl.to_id = ?
+          AND kl.from_type = 'knowledge'
+      `).all(knowledgeId);
+        }
+        catch {
+            // Ignore
+        }
+        for (const row of toRows) {
+            let sourceKey = null;
+            try {
+                const sourceRow = this.libraryDb.prepare(`
+          SELECT key FROM knowledge
+          WHERE id = ? AND agent_id = ? AND domain = 'topic-synthesis'
+        `).get(row.from_id, agentId);
+                sourceKey = sourceRow?.key ?? null;
+            }
+            catch {
+                // Ignore
+            }
+            if (sourceKey) {
+                links.push({ topicName: sourceKey, linkType: row.link_type, direction: 'to' });
+            }
+        }
+        return links;
+    }
+    /**
+     * Force re-synthesis of a specific topic regardless of staleness.
+     * Returns the new page or null if topic not found.
+     */
+    forceSynthesize(agentId, topicName) {
+        // Verify topic exists
+        let topicId;
+        try {
+            const row = this.libraryDb.prepare(`
+        SELECT id FROM topics WHERE agent_id = ? AND name = ? LIMIT 1
+      `).get(agentId, topicName);
+            topicId = row?.id;
+        }
+        catch {
+            // Topics table may not exist
+        }
+        if (topicId === undefined)
+            return null;
+        // Invalidate existing synthesis by setting superseded_by so tick() will re-synthesize
+        // Strategy: temporarily lower the stored message_count to force re-synthesis.
+        // Actually, simplest approach: call tick() after removing the existing knowledge entry.
+        // But KnowledgeStore doesn't have a delete method. Instead, we can use the upsert
+        // with forced content change to invalidate, then call tick().
+        //
+        // Better approach: use a fresh synthesizer with regrowthThreshold=0 so any growth triggers.
+        const forceSynth = new TopicSynthesizer(this.libraryDb, this.getMessageDb, {
+            ...this.synthConfig,
+            SYNTHESIS_REGROWTH_THRESHOLD: 0,
+            SYNTHESIS_STALE_MINUTES: 0, // bypass staleness time gate too
+        });
+        forceSynth.tick(agentId);
+        const knowledge = this.knowledgeStore.get(agentId, 'topic-synthesis', topicName);
+        if (!knowledge)
+            return null;
+        const crossLinks = this.resolveLinks(agentId, knowledge.id);
+        return {
+            topicName,
+            content: knowledge.content,
+            version: this.getVersion(agentId, topicName),
+            updatedAt: knowledge.updatedAt,
+            crossLinks,
+        };
+    }
+}
+//# sourceMappingURL=wiki-page-emitter.js.map

package/dist/work-store.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem Work Item Store
+ * hypermem Work Item Store
  *
  * Fleet kanban board in SQL. Replaces WORKQUEUE.md.
  * Lives in the central library DB.