@equationalapplications/expo-llm-wiki 0.0.0-development → 2.1.0

package/README.md

@@ -1,5 +1,10 @@
 # expo-llm-wiki
 
+[![GitHub Tag](https://img.shields.io/github/v/tag/equationalapplications/expo-llm-wiki?label=github%20tag)](https://github.com/equationalapplications/expo-llm-wiki/tags)
+[![npm version](https://img.shields.io/npm/v/%40equationalapplications%2Fexpo-llm-wiki?label=npm)](https://www.npmjs.com/package/@equationalapplications/expo-llm-wiki)
+[![npm downloads](https://img.shields.io/npm/dm/%40equationalapplications%2Fexpo-llm-wiki?label=downloads)](https://www.npmjs.com/package/@equationalapplications/expo-llm-wiki)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
 Offline-first, SQLite-backed memory for LLM apps built with Expo. Handles FTS5 search, episodic event logging, background fact extraction, and memory healing — bring your own LLM.
 
 ## Key Principles
@@ -8,6 +13,7 @@ Offline-first, SQLite-backed memory for LLM apps built with Expo. Handles FTS5 s
 - **Namespace Safe:** All tables are prefixed (default: `llm_wiki_`) — no collisions with your existing database.
 - **Multi-Entity:** Multiple independent "brains" in one database via `entityId`.
 - **Offline First:** Reads are fully local via SQLite FTS5, typically under 50ms.
+- **Morphological Matching:** Porter stemming enables recall across word forms — queries for `running` match facts about `run`, `runs`, etc., without manual synonym configuration.
 - **Full Unicode Support:** UTF-8 and UTF-16 (including surrogate pairs for emoji) are fully supported. Chunks are split safely at sentence boundaries; surrogate pairs are never fragmented.
 
 ## How It Works
@@ -89,6 +95,8 @@ const wiki = createWiki(db, {
     maxFtsResults: 10,              // optional, default: 10
     autoLibrarianThreshold: 20,     // optional, default: 20
     maxChunkLength: 6000,           // optional, default: 6000 (char count, not bytes)
+    chunkOverlap: 400,              // optional, default: 400 (overlap between chunks in characters)
+    chunkConcurrency: 1,            // optional, default: 1 (parallel LLM calls per ingestDocument)
   },
 });
 
@@ -135,7 +143,9 @@ const result = await wiki.ingestDocument('entity-123', {
   sourceRef: 'preferences.md',        // stable identifier
   sourceHash: sha256(content),        // for change detection
   documentChunk: content,
-  maxChunkLength: 6000,               // optional, character count
+  maxChunkLength: 12000,              // optional, character count
+  chunkOverlap: 400,                  // optional, overlap in characters
+  chunkConcurrency: 1,                // optional, parallel LLM calls per ingest (default: 1)
 });
 // result: { truncated: boolean; chunks: number }
 // truncated: true if at least one hard-split was required (no sentence boundary)
@@ -257,3 +267,7 @@ All mutation hooks follow the same pattern (`TResult` is specific per hook):
   error: Error | null;         // cleared on the next execute call
 }
 ```
+
+---
+
+Made with ❤️ by Equational Applications LLC. [https://equationalapplications.com/](https://equationalapplications.com/)

package/dist/{WikiMemory-BI2Aizwv.d.mts → WikiMemory-BDVn-TJf.d.mts}

@@ -9,6 +9,17 @@ interface WikiConfig {
     orphanAfterDays?: number | null;
     staleInferredAfterDays?: number | null;
     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;
@@ -79,22 +90,54 @@ interface MemoryBundle {
     tasks: WikiTask[];
     events: WikiEvent[];
 }
+interface MemoryDump {
+    generatedAt: number;
+    entities: Record<string, MemoryBundle>;
+}
+interface FormattedMemoryDump {
+    manifest: string;
+    files: Array<{
+        name: string;
+        content: string;
+    }>;
+}
+interface EntityStatus {
+    ingesting: boolean;
+    librarian: boolean;
+    heal: boolean;
+}
+declare class WikiBusyError extends Error {
+    readonly operation: 'ingest' | 'librarian' | 'heal';
+    readonly entityId: string;
+    constructor(operation: 'ingest' | 'librarian' | 'heal', entityId: string);
+}
 
 declare class WikiMemory {
     private db;
     private prefix;
     private options;
     private activeMaintenanceJobs;
+    private activeIngestJobs;
+    private _librarianKey;
+    private _healKey;
+    private _warnCrossEntityCollision;
     constructor(db: SQLite.SQLiteDatabase, options: WikiOptions);
     setup(): Promise<void>;
     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>;
     private runLibrarianThenMaybeHeal;
     private _doRunLibrarian;
     private _doRunHeal;
     runLibrarian(entityId: string): Promise<void>;
     runHeal(entityId: string): Promise<void>;
+    getEntityStatus(entityId: string): EntityStatus;
+    private _getFullBundle;
+    exportDump(entityIds?: string[]): Promise<MemoryDump>;
+    importDump(dump: MemoryDump, opts?: {
+        merge?: boolean;
+    }): Promise<void>;
     forget(entityId: string, params: {
         entryId?: string;
         taskId?: string;
@@ -112,10 +155,12 @@ declare class WikiMemory {
         sourceHash: string;
         documentChunk: string;
         maxChunkLength?: number;
+        chunkOverlap?: number;
+        chunkConcurrency?: number;
     }): Promise<{
         truncated: boolean;
         chunks: number;
     }>;
 }
 
-export { type ExtractedFact as E, type LLMProvider as L, type MemoryBundle as M, type WikiOptions as W, WikiMemory as a, type ExtractedTask as b, type WikiCheckpoint as c, type WikiConfig as d, type WikiEvent as e, type WikiFact as f, type WikiTask as g };
+export { type EntityStatus as E, type FormattedMemoryDump as F, type LLMProvider as L, type MemoryDump as M, type WikiOptions as W, WikiMemory as a, type ExtractedFact as b, type ExtractedTask as c, type MemoryBundle as d, WikiBusyError as e, type WikiCheckpoint as f, type WikiConfig as g, type WikiEvent as h, type WikiFact as i, type WikiTask as j };

package/dist/{WikiMemory-BI2Aizwv.d.ts → WikiMemory-BDVn-TJf.d.ts}

@@ -9,6 +9,17 @@ interface WikiConfig {
     orphanAfterDays?: number | null;
     staleInferredAfterDays?: number | null;
     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;
@@ -79,22 +90,54 @@ interface MemoryBundle {
     tasks: WikiTask[];
     events: WikiEvent[];
 }
+interface MemoryDump {
+    generatedAt: number;
+    entities: Record<string, MemoryBundle>;
+}
+interface FormattedMemoryDump {
+    manifest: string;
+    files: Array<{
+        name: string;
+        content: string;
+    }>;
+}
+interface EntityStatus {
+    ingesting: boolean;
+    librarian: boolean;
+    heal: boolean;
+}
+declare class WikiBusyError extends Error {
+    readonly operation: 'ingest' | 'librarian' | 'heal';
+    readonly entityId: string;
+    constructor(operation: 'ingest' | 'librarian' | 'heal', entityId: string);
+}
 
 declare class WikiMemory {
     private db;
     private prefix;
     private options;
     private activeMaintenanceJobs;
+    private activeIngestJobs;
+    private _librarianKey;
+    private _healKey;
+    private _warnCrossEntityCollision;
     constructor(db: SQLite.SQLiteDatabase, options: WikiOptions);
     setup(): Promise<void>;
     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>;
     private runLibrarianThenMaybeHeal;
     private _doRunLibrarian;
     private _doRunHeal;
     runLibrarian(entityId: string): Promise<void>;
     runHeal(entityId: string): Promise<void>;
+    getEntityStatus(entityId: string): EntityStatus;
+    private _getFullBundle;
+    exportDump(entityIds?: string[]): Promise<MemoryDump>;
+    importDump(dump: MemoryDump, opts?: {
+        merge?: boolean;
+    }): Promise<void>;
     forget(entityId: string, params: {
         entryId?: string;
         taskId?: string;
@@ -112,10 +155,12 @@ declare class WikiMemory {
         sourceHash: string;
         documentChunk: string;
         maxChunkLength?: number;
+        chunkOverlap?: number;
+        chunkConcurrency?: number;
     }): Promise<{
         truncated: boolean;
         chunks: number;
     }>;
 }
 
-export { type ExtractedFact as E, type LLMProvider as L, type MemoryBundle as M, type WikiOptions as W, WikiMemory as a, type ExtractedTask as b, type WikiCheckpoint as c, type WikiConfig as d, type WikiEvent as e, type WikiFact as f, type WikiTask as g };
+export { type EntityStatus as E, type FormattedMemoryDump as F, type LLMProvider as L, type MemoryDump as M, type WikiOptions as W, WikiMemory as a, type ExtractedFact as b, type ExtractedTask as c, type MemoryBundle as d, WikiBusyError as e, type WikiCheckpoint as f, type WikiConfig as g, type WikiEvent as h, type WikiFact as i, type WikiTask as j };

package/dist/index.d.mts

@@ -1,7 +1,9 @@
 import * as SQLite from 'expo-sqlite';
-import { W as WikiOptions, a as WikiMemory } from './WikiMemory-BI2Aizwv.mjs';
-export { E as ExtractedFact, b as ExtractedTask, L as LLMProvider, M as MemoryBundle, c as WikiCheckpoint, d as WikiConfig, e as WikiEvent, f as WikiFact, g as WikiTask } from './WikiMemory-BI2Aizwv.mjs';
+import { M as MemoryDump, F as FormattedMemoryDump, W as WikiOptions, a as WikiMemory } from './WikiMemory-BDVn-TJf.mjs';
+export { E as EntityStatus, b as ExtractedFact, c as ExtractedTask, L as LLMProvider, d as MemoryBundle, e as WikiBusyError, f as WikiCheckpoint, g as WikiConfig, h as WikiEvent, i as WikiFact, j as WikiTask } from './WikiMemory-BDVn-TJf.mjs';
+
+declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
 
 declare function createWiki(db: SQLite.SQLiteDatabase, options: WikiOptions): WikiMemory;
 
-export { WikiMemory, WikiOptions, createWiki };
+export { FormattedMemoryDump, MemoryDump, WikiMemory, WikiOptions, createWiki, formatMemoryDump };

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import * as SQLite from 'expo-sqlite';
-import { W as WikiOptions, a as WikiMemory } from './WikiMemory-BI2Aizwv.js';
-export { E as ExtractedFact, b as ExtractedTask, L as LLMProvider, M as MemoryBundle, c as WikiCheckpoint, d as WikiConfig, e as WikiEvent, f as WikiFact, g as WikiTask } from './WikiMemory-BI2Aizwv.js';
+import { M as MemoryDump, F as FormattedMemoryDump, W as WikiOptions, a as WikiMemory } from './WikiMemory-BDVn-TJf.js';
+export { E as EntityStatus, b as ExtractedFact, c as ExtractedTask, L as LLMProvider, d as MemoryBundle, e as WikiBusyError, f as WikiCheckpoint, g as WikiConfig, h as WikiEvent, i as WikiFact, j as WikiTask } from './WikiMemory-BDVn-TJf.js';
+
+declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
 
 declare function createWiki(db: SQLite.SQLiteDatabase, options: WikiOptions): WikiMemory;
 
-export { WikiMemory, WikiOptions, createWiki };
+export { FormattedMemoryDump, MemoryDump, WikiMemory, WikiOptions, createWiki, formatMemoryDump };