@equationalapplications/core-llm-wiki 2.4.0 → 2.5.0

package/dist/index.d.mts

@@ -16,6 +16,8 @@ interface SQLiteAdapter {
 }
 interface WikiConfig {
     tablePrefix?: string;
+    maxResults?: number;
+    /** @deprecated Use maxResults */
     maxFtsResults?: number;
     pruneEventsAfter?: number;
     pruneRetainSoftDeletedFor?: number;
@@ -26,15 +28,6 @@ interface WikiConfig {
     maxChunkLength?: number;
     chunkOverlap?: number;
     chunkConcurrency?: number;
-    /**
-     * Static caller-supplied synonym expansions applied at query time.
-     * Keys must match the same normalization pipeline used by query formatting:
-     * the query is lowercased, stripped to `[a-z0-9 ]`, split into tokens, and
-     * only tokens with length >= 3 are considered for synonym lookup.
-     * Values are appended to the FTS5 query token list (multi-word values are
-     * split into tokens), then deduped and sliced to 12.
-     */
-    synonymMap?: Record<string, string[]>;
 }
 interface WikiFact {
     id: string;
@@ -95,10 +88,28 @@ interface LLMProvider {
         systemPrompt: string;
         userPrompt: string;
     }) => Promise<string>;
+    /**
+     * Optional. When provided, enables semantic similarity search in `read()`.
+     * Must return a stable-dimension float array for any input text.
+     * Called once per fact on creation/update, and once per `read()` query.
+     * When absent or throws, `read()` falls back to MiniSearch.
+     */
+    embed?: (text: string) => Promise<number[]>;
 }
 interface WikiOptions {
     config?: WikiConfig;
     llmProvider: LLMProvider;
+    /**
+     * Called when embedding-based retrieval is unavailable during `read()` and
+     * MiniSearch keyword search is used instead. This can happen when:
+     * - `embed()` throws (e.g. network error, model unavailable)
+     * - `embed()` returns a vector with non-finite values (NaN / Infinity)
+     * - The query vector's dimension doesn't match stored embeddings (model switch;
+     *   resolve by calling `runReembed()`)
+     *
+     * `read()` still returns keyword-search results — this is a notification, not an error path.
+     */
+    onRetrievalFallback?: (error: Error) => void;
 }
 interface MemoryBundle {
     facts: WikiFact[];
@@ -135,9 +146,9 @@ interface EntityStatus {
     heal: boolean;
 }
 declare class WikiBusyError extends Error {
-    readonly operation: 'ingest' | 'librarian' | 'heal' | 'prune';
+    readonly operation: 'ingest' | 'librarian' | 'heal' | 'prune' | 'reembed';
     readonly entityId: string;
-    constructor(operation: 'ingest' | 'librarian' | 'heal' | 'prune', entityId: string);
+    constructor(operation: 'ingest' | 'librarian' | 'heal' | 'prune' | 'reembed', entityId: string);
 }
 
 declare class WikiMemory {
@@ -146,6 +157,19 @@ declare class WikiMemory {
     private options;
     private activeMaintenanceJobs;
     private activeIngestJobs;
+    private miniSearch;
+    private miniSearchEntryIdsByEntity;
+    private normalizeMiniSearchRow;
+    private rebuildMiniSearchIndex;
+    private storeEmbeddingDimension;
+    /**
+     * After a successful runReembed(), promote the pending `embedding_dimension_mismatch`
+     * value to the canonical `embedding_dimension` key and clear the mismatch flag.
+     * This ensures future read() calls use embedding-based retrieval rather than staying
+     * stuck on the MiniSearch fallback.
+     */
+    private _reconcileEmbeddingDimension;
+    private embedFact;
     private _librarianKey;
     private _healKey;
     private _warnCrossEntityCollision;
@@ -153,6 +177,13 @@ declare class WikiMemory {
     setup(): Promise<void>;
     hasChanged(entityId: string, sourceRef: string, sourceHash: string): Promise<boolean>;
     private _pruneKey;
+    private _reembedKey;
+    private _globalReembedKey;
+    private _isReembedActive;
+    /** Returns true if any maintenance job has the given operation suffix (e.g. ':prune'). */
+    private _isAnyMaintenanceActiveWithSuffix;
+    /** Returns true if any ingest job is active for the given entity. */
+    private _isIngestActiveFor;
     private _validatePruneDuration;
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
@@ -163,7 +194,6 @@ declare class WikiMemory {
         tasks: number;
         events: number;
     }>;
-    private formatSearchQuery;
     read(entityId: string, query: string): Promise<MemoryBundle>;
     getMemoryBundle(entityId: string): Promise<MemoryBundle>;
     write(entityId: string, event: Omit<WikiEvent, 'id' | 'entity_id' | 'created_at'>): Promise<void>;
@@ -172,6 +202,10 @@ declare class WikiMemory {
     private _doRunHeal;
     runLibrarian(entityId: string): Promise<void>;
     runHeal(entityId: string): Promise<void>;
+    runReembed(entityId?: string): Promise<{
+        embedded: number;
+        skipped: number;
+    }>;
     getEntityStatus(entityId: string): EntityStatus;
     private _getFullBundle;
     exportDump(entityIds?: string[]): Promise<MemoryDump>;

package/dist/index.d.ts

@@ -16,6 +16,8 @@ interface SQLiteAdapter {
 }
 interface WikiConfig {
     tablePrefix?: string;
+    maxResults?: number;
+    /** @deprecated Use maxResults */
     maxFtsResults?: number;
     pruneEventsAfter?: number;
     pruneRetainSoftDeletedFor?: number;
@@ -26,15 +28,6 @@ interface WikiConfig {
     maxChunkLength?: number;
     chunkOverlap?: number;
     chunkConcurrency?: number;
-    /**
-     * Static caller-supplied synonym expansions applied at query time.
-     * Keys must match the same normalization pipeline used by query formatting:
-     * the query is lowercased, stripped to `[a-z0-9 ]`, split into tokens, and
-     * only tokens with length >= 3 are considered for synonym lookup.
-     * Values are appended to the FTS5 query token list (multi-word values are
-     * split into tokens), then deduped and sliced to 12.
-     */
-    synonymMap?: Record<string, string[]>;
 }
 interface WikiFact {
     id: string;
@@ -95,10 +88,28 @@ interface LLMProvider {
         systemPrompt: string;
         userPrompt: string;
     }) => Promise<string>;
+    /**
+     * Optional. When provided, enables semantic similarity search in `read()`.
+     * Must return a stable-dimension float array for any input text.
+     * Called once per fact on creation/update, and once per `read()` query.
+     * When absent or throws, `read()` falls back to MiniSearch.
+     */
+    embed?: (text: string) => Promise<number[]>;
 }
 interface WikiOptions {
     config?: WikiConfig;
     llmProvider: LLMProvider;
+    /**
+     * Called when embedding-based retrieval is unavailable during `read()` and
+     * MiniSearch keyword search is used instead. This can happen when:
+     * - `embed()` throws (e.g. network error, model unavailable)
+     * - `embed()` returns a vector with non-finite values (NaN / Infinity)
+     * - The query vector's dimension doesn't match stored embeddings (model switch;
+     *   resolve by calling `runReembed()`)
+     *
+     * `read()` still returns keyword-search results — this is a notification, not an error path.
+     */
+    onRetrievalFallback?: (error: Error) => void;
 }
 interface MemoryBundle {
     facts: WikiFact[];
@@ -135,9 +146,9 @@ interface EntityStatus {
     heal: boolean;
 }
 declare class WikiBusyError extends Error {
-    readonly operation: 'ingest' | 'librarian' | 'heal' | 'prune';
+    readonly operation: 'ingest' | 'librarian' | 'heal' | 'prune' | 'reembed';
     readonly entityId: string;
-    constructor(operation: 'ingest' | 'librarian' | 'heal' | 'prune', entityId: string);
+    constructor(operation: 'ingest' | 'librarian' | 'heal' | 'prune' | 'reembed', entityId: string);
 }
 
 declare class WikiMemory {
@@ -146,6 +157,19 @@ declare class WikiMemory {
     private options;
     private activeMaintenanceJobs;
     private activeIngestJobs;
+    private miniSearch;
+    private miniSearchEntryIdsByEntity;
+    private normalizeMiniSearchRow;
+    private rebuildMiniSearchIndex;
+    private storeEmbeddingDimension;
+    /**
+     * After a successful runReembed(), promote the pending `embedding_dimension_mismatch`
+     * value to the canonical `embedding_dimension` key and clear the mismatch flag.
+     * This ensures future read() calls use embedding-based retrieval rather than staying
+     * stuck on the MiniSearch fallback.
+     */
+    private _reconcileEmbeddingDimension;
+    private embedFact;
     private _librarianKey;
     private _healKey;
     private _warnCrossEntityCollision;
@@ -153,6 +177,13 @@ declare class WikiMemory {
     setup(): Promise<void>;
     hasChanged(entityId: string, sourceRef: string, sourceHash: string): Promise<boolean>;
     private _pruneKey;
+    private _reembedKey;
+    private _globalReembedKey;
+    private _isReembedActive;
+    /** Returns true if any maintenance job has the given operation suffix (e.g. ':prune'). */
+    private _isAnyMaintenanceActiveWithSuffix;
+    /** Returns true if any ingest job is active for the given entity. */
+    private _isIngestActiveFor;
     private _validatePruneDuration;
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
@@ -163,7 +194,6 @@ declare class WikiMemory {
         tasks: number;
         events: number;
     }>;
-    private formatSearchQuery;
     read(entityId: string, query: string): Promise<MemoryBundle>;
     getMemoryBundle(entityId: string): Promise<MemoryBundle>;
     write(entityId: string, event: Omit<WikiEvent, 'id' | 'entity_id' | 'created_at'>): Promise<void>;
@@ -172,6 +202,10 @@ declare class WikiMemory {
     private _doRunHeal;
     runLibrarian(entityId: string): Promise<void>;
     runHeal(entityId: string): Promise<void>;
+    runReembed(entityId?: string): Promise<{
+        embedded: number;
+        skipped: number;
+    }>;
     getEntityStatus(entityId: string): EntityStatus;
     private _getFullBundle;
     exportDump(entityIds?: string[]): Promise<MemoryDump>;