@equationalapplications/expo-llm-wiki 2.1.0 → 2.3.0

package/README.md

@@ -19,36 +19,46 @@ Offline-first, SQLite-backed memory for LLM apps built with Expo. Handles FTS5 s
 ## How It Works
 
 ```mermaid
-flowchart LR
-    subgraph API
+flowchart TB
+    subgraph API["API Layer"]
         direction TB
         write["write(event)"]
         ingest["ingestDocument()"]
         librarian["runLibrarian()"]
         heal["runHeal()"]
+        read["read(entityId, query)"]
     end
 
-    subgraph SQLite
+    subgraph LLMLayer["LLM Provider"]
+        LLM["LLMProvider.generateText()"]
+    end
+
+    subgraph SQLiteLayer["SQLite Database"]
         direction TB
         events[(events)]
-        entries[("entries\n(facts)")]
+        entries[("entries<br/>(facts)")]
         tasks[(tasks)]
     end
 
-    LLM["LLMProvider\n.generateText()"]
-
-    read["read(entityId, query)"]
-    FTS5(["FTS5 search"])
-    Bundle(["MemoryBundle\nfacts · tasks · events"])
+    subgraph ReadPath["Read Path"]
+        FTS5(["FTS5 search"])
+        Bundle(["MemoryBundle<br/>facts · tasks · events"])
+    end
 
+    %% Write paths
     write --> events
     events -. "≥ threshold" .-> librarian
+    
+    %% LLM calls
     librarian --> LLM
     heal --> LLM
     ingest --> LLM
+    
+    %% Database writes
     LLM --> entries
     LLM --> tasks
-
+    
+    %% Read path
     read --> FTS5
     FTS5 --> entries
     entries --> Bundle
@@ -56,6 +66,7 @@ flowchart LR
     events --> Bundle
 ```
 
+
 ## Installation
 
 In your Expo project:
@@ -97,6 +108,8 @@ const wiki = createWiki(db, {
     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)
+    pruneRetainSoftDeletedFor: 7,   // optional, default: 7  (days before hard-deleting soft-deleted rows)
+    pruneEventsAfter: 30,           // optional, default: 30 (days before hard-deleting old events)
   },
 });
 
@@ -162,6 +175,34 @@ await wiki.runLibrarian('entity-123');
 await wiki.runHeal('entity-123');
 ```
 
+### Format Context
+
+Convert a `MemoryBundle` into a string ready for LLM prompt injection:
+
+```typescript
+import { formatContext } from 'expo-llm-wiki';
+
+const bundle = await wiki.read('entity-123', 'weekend plans');
+const context = formatContext(bundle, {
+  format: 'markdown',        // 'markdown' (default) | 'plain'
+  maxFacts: 10,              // default 10
+  maxTasks: 10,              // default 10
+  maxEvents: 10,             // default 10
+  includeConfidence: true,   // default true — appends (certain/inferred/tentative)
+  includeTags: true,         // default true — appends [tag1, tag2]
+  factWeights: {
+    confidence: 1.0,         // default 1.0
+    accessCount: 0.3,        // default 0.3 — log(1 + access_count) * weight
+    recency: 0.5,            // default 0.5 — decays over 30d
+  },
+});
+
+// Inject into your system prompt:
+const systemPrompt = `You are a helpful assistant.\n\n${context}`;
+```
+
+Facts are ranked by a weighted score combining confidence tier, access frequency, and recency. Returns an empty string for an empty bundle.
+
 ### Forget
 
 ```typescript
@@ -176,6 +217,38 @@ await wiki.forget('entity-123', { clearAll: true });          // wipe entity
 
 Throws `Error` if `sourceRef` or `sourceHash` is provided but invalid. Soft-deletes are idempotent — calling again with the same parameters returns `{ deleted: { entries: 0; tasks: 0 } }`.
 
+### Check for Changes
+
+Skip re-ingest if a document's content hasn't changed since the last ingest:
+
+```typescript
+const changed = await wiki.hasChanged('entity-123', 'preferences.md', sha256(content));
+if (changed) {
+  await wiki.ingestDocument('entity-123', { sourceRef: 'preferences.md', sourceHash: sha256(content), documentChunk: content });
+}
+```
+
+Returns `true` if the document has never been ingested, all prior ingest results were forgotten, or the stored hash differs from the supplied one. Returns `false` if the stored hash matches exactly.
+
+Throws `Error` if `sourceRef` or `sourceHash` is invalid (same rules as `ingestDocument`).
+
+### Prune (Hard Delete)
+
+Hard-delete aged soft-deleted entries/tasks and old events to reclaim storage:
+
+```typescript
+const result = await wiki.runPrune('entity-123', {
+  retainSoftDeletedFor: 7,    // days — hard-delete entries/tasks soft-deleted > 7d ago; null to skip
+  retainEventsFor: 30,         // days since created_at — hard-delete old events; null to skip
+  vacuum: false,               // set true to VACUUM (slow on mobile, rewrites entire DB)
+});
+// result: { entries: number; tasks: number; events: number }
+```
+
+Defaults: `retainSoftDeletedFor = config.pruneRetainSoftDeletedFor ?? 7`, `retainEventsFor = config.pruneEventsAfter ?? 30`, `vacuum = false`.
+
+Throws `WikiBusyError` if librarian, heal, ingest, or another prune is in-flight for the same entity. `ingestDocument`, `runLibrarian`, and `runHeal` reciprocally throw `WikiBusyError` if a prune is in-flight.
+
 ---
 
 ## React / Expo Component API
@@ -223,10 +296,10 @@ await execute('entity-123', {
 
 ### `useWikiMaintenance()`
 
-Shared `isPending` — true if either operation is in-flight:
+Shared `isPending` — true if any operation is in-flight. See [extended form below](#usewikimaintenance-extended) for `runPrune`:
 
 ```typescript
-const { runLibrarian, runHeal, isPending, error } = useWikiMaintenance();
+const { runLibrarian, runHeal, runPrune, isPending, error } = useWikiMaintenance();
 
 await runLibrarian('entity-123');
 await runHeal('entity-123');
@@ -257,6 +330,43 @@ const result = await execute('entity-123', { entryId: 'fact_abc' });
 // result.deleted.entries — rows soft-deleted
 ```
 
+### `useWikiHasChanged()`
+
+```typescript
+const { execute, lastResult, isPending, error } = useWikiHasChanged();
+// lastResult: boolean | null
+
+const changed = await execute('entity-123', 'preferences.md', sha256(content));
+```
+
+### `useWikiMaintenance()` (extended)
+
+`runPrune` is now available alongside `runLibrarian` and `runHeal`. Shared `isPending` is true if any operation is in-flight. `lastResult` is a discriminated union — check `.operation` to narrow the type:
+
+```typescript
+const { runLibrarian, runHeal, runPrune, lastResult, isPending, error } = useWikiMaintenance();
+
+await runLibrarian('entity-123');
+// lastResult: { operation: 'librarian', result: void }
+
+await runHeal('entity-123');
+// lastResult: { operation: 'heal', result: void }
+
+const counts = await runPrune('entity-123', { retainSoftDeletedFor: 7, retainEventsFor: 30 });
+// counts: { entries: number; tasks: number; events: number }
+// lastResult: { operation: 'prune', result: { entries: number; tasks: number; events: number } }
+
+if (lastResult?.operation === 'prune') {
+  console.log(lastResult.result.entries); // type-safe access to prune counts
+}
+```
+
+The exported `MaintenanceResult` type can be imported for typed consumers:
+
+```typescript
+import type { MaintenanceResult } from 'expo-llm-wiki/react';
+```
+
 All mutation hooks follow the same pattern (`TResult` is specific per hook):
 
 ```typescript

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

@@ -4,6 +4,7 @@ interface WikiConfig {
     tablePrefix?: string;
     maxFtsResults?: number;
     pruneEventsAfter?: number;
+    pruneRetainSoftDeletedFor?: number;
     autoLibrarianThreshold?: number;
     autoHealThreshold?: number;
     orphanAfterDays?: number | null;
@@ -101,15 +102,28 @@ interface FormattedMemoryDump {
         content: string;
     }>;
 }
+interface FormatContextOptions {
+    format?: 'markdown' | 'plain';
+    maxFacts?: number;
+    maxTasks?: number;
+    maxEvents?: number;
+    includeConfidence?: boolean;
+    includeTags?: boolean;
+    factWeights?: {
+        confidence?: number;
+        accessCount?: number;
+        recency?: number;
+    };
+}
 interface EntityStatus {
     ingesting: boolean;
     librarian: boolean;
     heal: boolean;
 }
 declare class WikiBusyError extends Error {
-    readonly operation: 'ingest' | 'librarian' | 'heal';
+    readonly operation: 'ingest' | 'librarian' | 'heal' | 'prune';
     readonly entityId: string;
-    constructor(operation: 'ingest' | 'librarian' | 'heal', entityId: string);
+    constructor(operation: 'ingest' | 'librarian' | 'heal' | 'prune', entityId: string);
 }
 
 declare class WikiMemory {
@@ -123,6 +137,18 @@ declare class WikiMemory {
     private _warnCrossEntityCollision;
     constructor(db: SQLite.SQLiteDatabase, options: WikiOptions);
     setup(): Promise<void>;
+    hasChanged(entityId: string, sourceRef: string, sourceHash: string): Promise<boolean>;
+    private _pruneKey;
+    private _validatePruneDuration;
+    runPrune(entityId: string, options?: {
+        retainSoftDeletedFor?: number | null;
+        retainEventsFor?: number | null;
+        vacuum?: boolean;
+    }): Promise<{
+        entries: number;
+        tasks: number;
+        events: number;
+    }>;
     private formatSearchQuery;
     read(entityId: string, query: string): Promise<MemoryBundle>;
     getMemoryBundle(entityId: string): Promise<MemoryBundle>;
@@ -163,4 +189,4 @@ declare class WikiMemory {
     }>;
 }
 
-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 };
+export { type EntityStatus as E, type FormattedMemoryDump as F, type LLMProvider as L, type MemoryDump as M, type WikiOptions as W, type MemoryBundle as a, type FormatContextOptions as b, WikiMemory as c, type ExtractedFact as d, type ExtractedTask as e, WikiBusyError as f, type WikiCheckpoint as g, type WikiConfig as h, type WikiEvent as i, type WikiFact as j, type WikiTask as k };

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

@@ -4,6 +4,7 @@ interface WikiConfig {
     tablePrefix?: string;
     maxFtsResults?: number;
     pruneEventsAfter?: number;
+    pruneRetainSoftDeletedFor?: number;
     autoLibrarianThreshold?: number;
     autoHealThreshold?: number;
     orphanAfterDays?: number | null;
@@ -101,15 +102,28 @@ interface FormattedMemoryDump {
         content: string;
     }>;
 }
+interface FormatContextOptions {
+    format?: 'markdown' | 'plain';
+    maxFacts?: number;
+    maxTasks?: number;
+    maxEvents?: number;
+    includeConfidence?: boolean;
+    includeTags?: boolean;
+    factWeights?: {
+        confidence?: number;
+        accessCount?: number;
+        recency?: number;
+    };
+}
 interface EntityStatus {
     ingesting: boolean;
     librarian: boolean;
     heal: boolean;
 }
 declare class WikiBusyError extends Error {
-    readonly operation: 'ingest' | 'librarian' | 'heal';
+    readonly operation: 'ingest' | 'librarian' | 'heal' | 'prune';
     readonly entityId: string;
-    constructor(operation: 'ingest' | 'librarian' | 'heal', entityId: string);
+    constructor(operation: 'ingest' | 'librarian' | 'heal' | 'prune', entityId: string);
 }
 
 declare class WikiMemory {
@@ -123,6 +137,18 @@ declare class WikiMemory {
     private _warnCrossEntityCollision;
     constructor(db: SQLite.SQLiteDatabase, options: WikiOptions);
     setup(): Promise<void>;
+    hasChanged(entityId: string, sourceRef: string, sourceHash: string): Promise<boolean>;
+    private _pruneKey;
+    private _validatePruneDuration;
+    runPrune(entityId: string, options?: {
+        retainSoftDeletedFor?: number | null;
+        retainEventsFor?: number | null;
+        vacuum?: boolean;
+    }): Promise<{
+        entries: number;
+        tasks: number;
+        events: number;
+    }>;
     private formatSearchQuery;
     read(entityId: string, query: string): Promise<MemoryBundle>;
     getMemoryBundle(entityId: string): Promise<MemoryBundle>;
@@ -163,4 +189,4 @@ declare class WikiMemory {
     }>;
 }
 
-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 };
+export { type EntityStatus as E, type FormattedMemoryDump as F, type LLMProvider as L, type MemoryDump as M, type WikiOptions as W, type MemoryBundle as a, type FormatContextOptions as b, WikiMemory as c, type ExtractedFact as d, type ExtractedTask as e, WikiBusyError as f, type WikiCheckpoint as g, type WikiConfig as h, type WikiEvent as i, type WikiFact as j, type WikiTask as k };

package/dist/index.d.mts

@@ -1,9 +1,11 @@
 import * as SQLite from 'expo-sqlite';
-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';
+import { M as MemoryDump, F as FormattedMemoryDump, a as MemoryBundle, b as FormatContextOptions, W as WikiOptions, c as WikiMemory } from './WikiMemory-ChQmVyvA.mjs';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedTask, L as LLMProvider, f as WikiBusyError, g as WikiCheckpoint, h as WikiConfig, i as WikiEvent, j as WikiFact, k as WikiTask } from './WikiMemory-ChQmVyvA.mjs';
 
 declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
 
+declare function formatContext(bundle: MemoryBundle, options?: FormatContextOptions): string;
+
 declare function createWiki(db: SQLite.SQLiteDatabase, options: WikiOptions): WikiMemory;
 
-export { FormattedMemoryDump, MemoryDump, WikiMemory, WikiOptions, createWiki, formatMemoryDump };
+export { FormatContextOptions, FormattedMemoryDump, MemoryBundle, MemoryDump, WikiMemory, WikiOptions, createWiki, formatContext, formatMemoryDump };

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import * as SQLite from 'expo-sqlite';
-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';
+import { M as MemoryDump, F as FormattedMemoryDump, a as MemoryBundle, b as FormatContextOptions, W as WikiOptions, c as WikiMemory } from './WikiMemory-ChQmVyvA.js';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedTask, L as LLMProvider, f as WikiBusyError, g as WikiCheckpoint, h as WikiConfig, i as WikiEvent, j as WikiFact, k as WikiTask } from './WikiMemory-ChQmVyvA.js';
 
 declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
 
+declare function formatContext(bundle: MemoryBundle, options?: FormatContextOptions): string;
+
 declare function createWiki(db: SQLite.SQLiteDatabase, options: WikiOptions): WikiMemory;
 
-export { FormattedMemoryDump, MemoryDump, WikiMemory, WikiOptions, createWiki, formatMemoryDump };
+export { FormatContextOptions, FormattedMemoryDump, MemoryBundle, MemoryDump, WikiMemory, WikiOptions, createWiki, formatContext, formatMemoryDump };