@equationalapplications/core-llm-wiki 2.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Equational Applications
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @equationalapplications/core-llm-wiki
+
+Pure TypeScript business logic for LLM Wiki Memory.
+
+## Features
+
+- **Platform-agnostic** — Zero runtime dependencies; works with any SQLite driver via the `SQLiteAdapter` interface
+- **Full-featured memory** — Facts, tasks, events, semantic search, maintenance jobs
+- **Type-safe** — Built with TypeScript, full type exports
+
+## Installation
+
+```bash
+npm install @equationalapplications/core-llm-wiki
+```
+
+## Usage
+
+```typescript
+import { WikiMemory, type SQLiteAdapter } from '@equationalapplications/core-llm-wiki';
+
+// Provide any SQLiteAdapter-compatible driver
+const wikiMemory = new WikiMemory(db, {
+  llmProvider: {
+    generateText: async ({ systemPrompt, userPrompt }) => {
+      // Your LLM call here
+      return 'Model output';
+    },
+  },
+});
+
+// Initialize schema and run migrations
+await wikiMemory.setup();
+
+// Store facts
+await wikiMemory.write('user-123', {
+  event_type: 'observation',
+  summary: 'User prefers async/await over promises',
+});
+
+// Query memory
+const memory = await wikiMemory.read('user-123', 'coding style preferences');
+```
+
+## Adapter Interface
+
+Implement `SQLiteAdapter` to use your platform's SQLite driver:
+
+```typescript
+export interface SQLiteAdapter {
+  execAsync(sql: string): Promise<void>;
+  runAsync(sql: string, params?: unknown[]): Promise<{ changes: number; lastInsertRowId: number }>;
+  getAllAsync<T>(sql: string, params?: unknown[]): Promise<T[]>;
+  getFirstAsync<T>(sql: string, params?: unknown[]): Promise<T | null>;
+  withTransactionAsync<T>(fn: () => Promise<T>): Promise<T>;
+  closeAsync(): Promise<void>;
+}
+```
+
+`@equationalapplications/expo-llm-wiki` provides a pre-built adapter for Expo/React Native. For web and Node.js, implement the interface yourself — examples below.
+
+**Browser (sql.js):**
+
+```typescript
+import initSqlJs from 'sql.js';
+import type { SQLiteAdapter } from '@equationalapplications/core-llm-wiki';
+
+const SQL = await initSqlJs({ locateFile: (f) => `/wasm/${f}` });
+const sqlDb = new SQL.Database();
+
+const adapter: SQLiteAdapter = {
+  async execAsync(sql) { sqlDb.run(sql); },
+  async runAsync(sql, params = []) {
+    sqlDb.run(sql, params as any[]);
+    // sql.js doesn't expose lastInsertRowId; hardcode 0 since WikiMemory uses internal ID generation
+    return { changes: sqlDb.getRowsModified(), lastInsertRowId: 0 };
+  },
+  async getAllAsync<T>(sql, params = []) {
+    const stmt = sqlDb.prepare(sql);
+    stmt.bind(params as any[]);
+    const rows: T[] = [];
+    while (stmt.step()) rows.push(stmt.getAsObject() as T);
+    stmt.free();
+    return rows;
+  },
+  async getFirstAsync<T>(sql, params = []) {
+    const stmt = sqlDb.prepare(sql);
+    stmt.bind(params as any[]);
+    const row = stmt.step() ? stmt.getAsObject() as T : null;
+    stmt.free();
+    return row;
+  },
+  async withTransactionAsync(fn) {
+    sqlDb.run('BEGIN');
+    try { const r = await fn(); sqlDb.run('COMMIT'); return r; }
+    catch (e) { sqlDb.run('ROLLBACK'); throw e; }
+  },
+  async closeAsync() { sqlDb.close(); },
+};
+```
+
+**Node.js (better-sqlite3):**
+
+```typescript
+import Database from 'better-sqlite3';
+import type { SQLiteAdapter } from '@equationalapplications/core-llm-wiki';
+
+const db = new Database('wiki.db');
+
+const adapter: SQLiteAdapter = {
+  async execAsync(sql) { db.exec(sql); },
+  async runAsync(sql, params = []) {
+    const info = db.prepare(sql).run(...(params as any[]));
+    return { changes: info.changes, lastInsertRowId: Number(info.lastInsertRowid) };
+  },
+  async getAllAsync<T>(sql, params = []) {
+    return db.prepare(sql).all(...(params as any[])) as T[];
+  },
+  async getFirstAsync<T>(sql, params = []) {
+    return (db.prepare(sql).get(...(params as any[])) ?? null) as T | null;
+  },
+  async withTransactionAsync(fn) {
+    db.exec('BEGIN');
+    try { const r = await fn(); db.exec('COMMIT'); return r; }
+    catch (e) { db.exec('ROLLBACK'); throw e; }
+  },
+  async closeAsync() { db.close(); },
+};
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,212 @@
+/**
+ * Platform-agnostic SQLite driver interface.
+ * Each platform package (wiki-expo, wiki-react) provides an adapter
+ * that wraps its native driver behind this interface.
+ */
+interface SQLiteAdapter {
+    execAsync(sql: string): Promise<void>;
+    runAsync(sql: string, params?: unknown[]): Promise<{
+        changes: number;
+        lastInsertRowId: number;
+    }>;
+    getAllAsync<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    getFirstAsync<T>(sql: string, params?: unknown[]): Promise<T | null>;
+    withTransactionAsync<T>(fn: () => Promise<T>): Promise<T>;
+    closeAsync(): Promise<void>;
+}
+interface WikiConfig {
+    tablePrefix?: string;
+    maxFtsResults?: number;
+    pruneEventsAfter?: number;
+    pruneRetainSoftDeletedFor?: number;
+    autoLibrarianThreshold?: number;
+    autoHealThreshold?: number;
+    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;
+    entity_id: string;
+    title: string;
+    body: string;
+    tags: string[];
+    confidence: 'certain' | 'inferred' | 'tentative';
+    source_type: 'user_stated' | 'agent_inferred' | 'user_confirmed' | 'user_document';
+    source_hash: string | null;
+    source_ref: string | null;
+    created_at: number;
+    updated_at: number;
+    last_accessed_at: number | null;
+    access_count: number;
+    deleted_at: number | null;
+}
+interface WikiTask {
+    id: string;
+    entity_id: string;
+    description: string;
+    status: 'pending' | 'in_progress' | 'done' | 'abandoned';
+    priority: number;
+    created_at: number;
+    updated_at: number;
+    resolved_at: number | null;
+    deleted_at: number | null;
+}
+interface WikiEvent {
+    id: string;
+    entity_id: string;
+    event_type: 'observation' | 'decision' | 'action' | 'outcome';
+    summary: string;
+    related_entry_id?: string | null;
+    created_at: number;
+}
+interface WikiCheckpoint {
+    entity_id: string;
+    heal_checkpoint: number;
+    memory_checkpoint: number;
+}
+interface ExtractedFact {
+    title: string;
+    body: string;
+    tags: string[];
+    confidence: 'certain' | 'inferred' | 'tentative';
+}
+interface ExtractedTask {
+    description: string;
+    priority: number;
+}
+interface LLMProvider {
+    /**
+     * Generates text using the developer's LLM of choice.
+     * Expected to return the raw text response (typically a JSON string).
+     */
+    generateText: (params: {
+        systemPrompt: string;
+        userPrompt: string;
+    }) => Promise<string>;
+}
+interface WikiOptions {
+    config?: WikiConfig;
+    llmProvider: LLMProvider;
+}
+interface MemoryBundle {
+    facts: WikiFact[];
+    tasks: WikiTask[];
+    events: WikiEvent[];
+}
+interface MemoryDump {
+    generatedAt: number;
+    entities: Record<string, MemoryBundle>;
+}
+interface FormattedMemoryDump {
+    manifest: string;
+    files: Array<{
+        name: string;
+        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' | 'prune';
+    readonly entityId: string;
+    constructor(operation: 'ingest' | 'librarian' | 'heal' | 'prune', entityId: string);
+}
+
+declare class WikiMemory {
+    private db;
+    private prefix;
+    private options;
+    private activeMaintenanceJobs;
+    private activeIngestJobs;
+    private _librarianKey;
+    private _healKey;
+    private _warnCrossEntityCollision;
+    constructor(db: SQLiteAdapter, 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>;
+    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;
+        sourceRef?: string;
+        sourceHash?: string;
+        clearAll?: boolean;
+    }): Promise<{
+        deleted: {
+            entries: number;
+            tasks: number;
+        };
+    }>;
+    ingestDocument(entityId: string, params: {
+        sourceRef: string;
+        sourceHash: string;
+        documentChunk: string;
+        maxChunkLength?: number;
+        chunkOverlap?: number;
+        chunkConcurrency?: number;
+    }): Promise<{
+        truncated: boolean;
+        chunks: number;
+    }>;
+}
+
+declare function formatContext(bundle: MemoryBundle, options?: FormatContextOptions): string;
+
+declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
+
+declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
+
+export { type EntityStatus, type ExtractedFact, type ExtractedTask, type FormatContextOptions, type FormattedMemoryDump, type LLMProvider, type MemoryBundle, type MemoryDump, type SQLiteAdapter, WikiBusyError, type WikiCheckpoint, type WikiConfig, type WikiEvent, type WikiFact, WikiMemory, type WikiOptions, type WikiTask, createWiki, formatContext, formatMemoryDump };

package/dist/index.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Platform-agnostic SQLite driver interface.
+ * Each platform package (wiki-expo, wiki-react) provides an adapter
+ * that wraps its native driver behind this interface.
+ */
+interface SQLiteAdapter {
+    execAsync(sql: string): Promise<void>;
+    runAsync(sql: string, params?: unknown[]): Promise<{
+        changes: number;
+        lastInsertRowId: number;
+    }>;
+    getAllAsync<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    getFirstAsync<T>(sql: string, params?: unknown[]): Promise<T | null>;
+    withTransactionAsync<T>(fn: () => Promise<T>): Promise<T>;
+    closeAsync(): Promise<void>;
+}
+interface WikiConfig {
+    tablePrefix?: string;
+    maxFtsResults?: number;
+    pruneEventsAfter?: number;
+    pruneRetainSoftDeletedFor?: number;
+    autoLibrarianThreshold?: number;
+    autoHealThreshold?: number;
+    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;
+    entity_id: string;
+    title: string;
+    body: string;
+    tags: string[];
+    confidence: 'certain' | 'inferred' | 'tentative';
+    source_type: 'user_stated' | 'agent_inferred' | 'user_confirmed' | 'user_document';
+    source_hash: string | null;
+    source_ref: string | null;
+    created_at: number;
+    updated_at: number;
+    last_accessed_at: number | null;
+    access_count: number;
+    deleted_at: number | null;
+}
+interface WikiTask {
+    id: string;
+    entity_id: string;
+    description: string;
+    status: 'pending' | 'in_progress' | 'done' | 'abandoned';
+    priority: number;
+    created_at: number;
+    updated_at: number;
+    resolved_at: number | null;
+    deleted_at: number | null;
+}
+interface WikiEvent {
+    id: string;
+    entity_id: string;
+    event_type: 'observation' | 'decision' | 'action' | 'outcome';
+    summary: string;
+    related_entry_id?: string | null;
+    created_at: number;
+}
+interface WikiCheckpoint {
+    entity_id: string;
+    heal_checkpoint: number;
+    memory_checkpoint: number;
+}
+interface ExtractedFact {
+    title: string;
+    body: string;
+    tags: string[];
+    confidence: 'certain' | 'inferred' | 'tentative';
+}
+interface ExtractedTask {
+    description: string;
+    priority: number;
+}
+interface LLMProvider {
+    /**
+     * Generates text using the developer's LLM of choice.
+     * Expected to return the raw text response (typically a JSON string).
+     */
+    generateText: (params: {
+        systemPrompt: string;
+        userPrompt: string;
+    }) => Promise<string>;
+}
+interface WikiOptions {
+    config?: WikiConfig;
+    llmProvider: LLMProvider;
+}
+interface MemoryBundle {
+    facts: WikiFact[];
+    tasks: WikiTask[];
+    events: WikiEvent[];
+}
+interface MemoryDump {
+    generatedAt: number;
+    entities: Record<string, MemoryBundle>;
+}
+interface FormattedMemoryDump {
+    manifest: string;
+    files: Array<{
+        name: string;
+        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' | 'prune';
+    readonly entityId: string;
+    constructor(operation: 'ingest' | 'librarian' | 'heal' | 'prune', entityId: string);
+}
+
+declare class WikiMemory {
+    private db;
+    private prefix;
+    private options;
+    private activeMaintenanceJobs;
+    private activeIngestJobs;
+    private _librarianKey;
+    private _healKey;
+    private _warnCrossEntityCollision;
+    constructor(db: SQLiteAdapter, 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>;
+    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;
+        sourceRef?: string;
+        sourceHash?: string;
+        clearAll?: boolean;
+    }): Promise<{
+        deleted: {
+            entries: number;
+            tasks: number;
+        };
+    }>;
+    ingestDocument(entityId: string, params: {
+        sourceRef: string;
+        sourceHash: string;
+        documentChunk: string;
+        maxChunkLength?: number;
+        chunkOverlap?: number;
+        chunkConcurrency?: number;
+    }): Promise<{
+        truncated: boolean;
+        chunks: number;
+    }>;
+}
+
+declare function formatContext(bundle: MemoryBundle, options?: FormatContextOptions): string;
+
+declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
+
+declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
+
+export { type EntityStatus, type ExtractedFact, type ExtractedTask, type FormatContextOptions, type FormattedMemoryDump, type LLMProvider, type MemoryBundle, type MemoryDump, type SQLiteAdapter, WikiBusyError, type WikiCheckpoint, type WikiConfig, type WikiEvent, type WikiFact, WikiMemory, type WikiOptions, type WikiTask, createWiki, formatContext, formatMemoryDump };