@equationalapplications/expo-llm-wiki 0.0.0-development

package/dist/index.mjs

@@ -0,0 +1,651 @@
+// src/db/schema.ts
+async function setupDatabase(db, prefix) {
+  await db.execAsync(`
+    CREATE TABLE IF NOT EXISTS ${prefix}entries (
+      id TEXT PRIMARY KEY,
+      entity_id TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL,
+      tags TEXT NOT NULL DEFAULT '[]',
+      confidence TEXT NOT NULL DEFAULT 'inferred',
+      source_type TEXT NOT NULL DEFAULT 'agent_inferred',
+      source_hash TEXT,
+      source_ref TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      last_accessed_at INTEGER,
+      access_count INTEGER NOT NULL DEFAULT 0,
+      deleted_at INTEGER
+    );
+
+    CREATE INDEX IF NOT EXISTS ${prefix}entries_entity_idx ON ${prefix}entries(entity_id);
+    CREATE INDEX IF NOT EXISTS ${prefix}entries_source_ref_idx ON ${prefix}entries(entity_id, source_ref);
+    CREATE INDEX IF NOT EXISTS ${prefix}entries_source_hash_idx ON ${prefix}entries(entity_id, source_hash) WHERE source_hash IS NOT NULL;
+    CREATE INDEX IF NOT EXISTS ${prefix}entries_updated_idx ON ${prefix}entries(updated_at DESC);
+
+    -- FTS5 Virtual Table for full-text search
+    CREATE VIRTUAL TABLE IF NOT EXISTS ${prefix}entries_fts USING fts5(
+      title,
+      body,
+      tags,
+      content='${prefix}entries',
+      content_rowid='rowid'
+    );
+
+    -- Triggers to keep FTS5 in sync with entries
+    CREATE TRIGGER IF NOT EXISTS ${prefix}entries_ai AFTER INSERT ON ${prefix}entries BEGIN
+      INSERT INTO ${prefix}entries_fts(rowid, title, body, tags) 
+      VALUES (new.rowid, new.title, new.body, new.tags);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS ${prefix}entries_ad AFTER DELETE ON ${prefix}entries BEGIN
+      INSERT INTO ${prefix}entries_fts(${prefix}entries_fts, rowid, title, body, tags) 
+      VALUES ('delete', old.rowid, old.title, old.body, old.tags);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS ${prefix}entries_au AFTER UPDATE ON ${prefix}entries BEGIN
+      INSERT INTO ${prefix}entries_fts(${prefix}entries_fts, rowid, title, body, tags) 
+      VALUES ('delete', old.rowid, old.title, old.body, old.tags);
+      INSERT INTO ${prefix}entries_fts(rowid, title, body, tags) 
+      VALUES (new.rowid, new.title, new.body, new.tags);
+    END;
+
+    CREATE TABLE IF NOT EXISTS ${prefix}tasks (
+      id TEXT PRIMARY KEY,
+      entity_id TEXT NOT NULL,
+      description TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending',
+      priority INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      resolved_at INTEGER,
+      deleted_at INTEGER
+    );
+
+    CREATE INDEX IF NOT EXISTS ${prefix}tasks_entity_idx ON ${prefix}tasks(entity_id, status);
+
+    CREATE TABLE IF NOT EXISTS ${prefix}events (
+      id TEXT PRIMARY KEY,
+      entity_id TEXT NOT NULL,
+      event_type TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      related_entry_id TEXT,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS ${prefix}events_entity_idx ON ${prefix}events(entity_id, created_at DESC);
+
+    CREATE TABLE IF NOT EXISTS ${prefix}checkpoints (
+      entity_id TEXT PRIMARY KEY,
+      heal_checkpoint INTEGER NOT NULL DEFAULT 0,
+      memory_checkpoint INTEGER NOT NULL DEFAULT 0
+    );
+  `);
+}
+
+// src/prompts.ts
+var LIBRARIAN_SYSTEM_PROMPT = `You are a knowledge extraction agent. Your job is to analyze recent episodic events and extract stable facts and actionable tasks about the user or entity.
+Return ONLY a valid JSON object matching this schema:
+{
+  "facts": [{ "title": "string (max 80 chars)", "body": "string (max 200 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }],
+  "tasks": [{ "description": "string", "priority": "number (0-10)" }]
+}
+Keep facts concise. Do not return markdown, just raw JSON.`;
+var HEAL_SYSTEM_PROMPT = `You are a memory grooming agent. Your job is to review a full dump of facts and recent events to resolve contradictions, downgrade stale claims, and flag obsolete facts for deletion.
+Return ONLY a valid JSON object matching this schema:
+{
+  "downgraded": ["string (fact IDs)"],
+  "deleted": ["string (fact IDs)"],
+  "newFacts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }]
+}
+Do not return markdown, just raw JSON.`;
+var INGEST_SYSTEM_PROMPT = `You are a document ingestion agent. Your job is to extract factual knowledge from the provided document chunk.
+Return ONLY a valid JSON object matching this schema:
+{
+  "facts": [{ "title": "string (max 80 chars)", "body": "string (max 200 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }]
+}
+Extract verbatim factual content. Do not return markdown, just raw JSON.`;
+
+// src/WikiMemory.ts
+function parseJsonResponse(text) {
+  const firstBrace = text.indexOf("{");
+  const firstBracket = text.indexOf("[");
+  let start;
+  let openChar;
+  let closeChar;
+  if (firstBrace !== -1 && (firstBracket === -1 || firstBrace < firstBracket)) {
+    start = firstBrace;
+    openChar = "{";
+    closeChar = "}";
+  } else if (firstBracket !== -1) {
+    start = firstBracket;
+    openChar = "[";
+    closeChar = "]";
+  } else {
+    throw new SyntaxError("No JSON object/array found in LLM response");
+  }
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  let end = -1;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (ch === "\\" && inString) {
+      escape = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === openChar) {
+      depth++;
+      continue;
+    }
+    if (ch === closeChar) {
+      depth--;
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  if (end === -1) throw new SyntaxError("No JSON object/array found in LLM response");
+  return JSON.parse(text.slice(start, end + 1));
+}
+function generateId(prefix = "") {
+  return prefix + Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+}
+function safeSlice(value, start, end) {
+  const length = value.length;
+  let safeStart = start < 0 ? Math.max(length + start, 0) : Math.min(start, length);
+  let safeEnd = end === void 0 ? length : end < 0 ? Math.max(length + end, 0) : Math.min(end, length);
+  if (safeStart > safeEnd) {
+    [safeStart, safeEnd] = [safeEnd, safeStart];
+  }
+  if (safeStart > 0 && safeStart < length && value.charCodeAt(safeStart) >= 56320 && value.charCodeAt(safeStart) <= 57343 && value.charCodeAt(safeStart - 1) >= 55296 && value.charCodeAt(safeStart - 1) <= 56319) {
+    safeStart--;
+  }
+  if (safeEnd > 0 && safeEnd < length && value.charCodeAt(safeEnd - 1) >= 55296 && value.charCodeAt(safeEnd - 1) <= 56319 && value.charCodeAt(safeEnd) >= 56320 && value.charCodeAt(safeEnd) <= 57343) {
+    safeEnd--;
+  }
+  return value.slice(safeStart, safeEnd);
+}
+function clip(value, max) {
+  if (typeof value !== "string") return "";
+  const s = value.trim();
+  return s.length <= max ? s : safeSlice(s, 0, max).trimEnd();
+}
+function validateTags(tags) {
+  if (!Array.isArray(tags)) return [];
+  return tags.filter((t) => typeof t === "string").map((t) => t.trim().toLowerCase()).filter((t) => t.length > 0 && t.length <= 40).slice(0, 6);
+}
+function validateFact(fact) {
+  if (typeof fact?.title !== "string" || typeof fact?.body !== "string") return null;
+  const title = clip(fact.title, 80);
+  const body = clip(fact.body, 200);
+  if (!title || !body) return null;
+  let confidence = fact.confidence;
+  if (confidence !== "certain" && confidence !== "tentative") confidence = "inferred";
+  return {
+    ...fact,
+    title,
+    body,
+    confidence,
+    tags: validateTags(fact.tags)
+  };
+}
+function validateTask(task) {
+  if (typeof task?.description !== "string") return null;
+  const description = clip(task.description, 200);
+  if (!description) return null;
+  let priority = task.priority;
+  if (typeof priority !== "number" || !isFinite(priority)) priority = 0;
+  return {
+    ...task,
+    description,
+    priority
+  };
+}
+function normalizeSourceRef(value) {
+  if (typeof value !== "string") return null;
+  const cleaned = value.replace(/[^A-Za-z0-9._\- ]/g, "").trim().slice(0, 255);
+  return cleaned.length > 0 ? cleaned : null;
+}
+function normalizeSourceHash(value) {
+  if (typeof value !== "string") return null;
+  return /^[0-9a-f]{64}$/i.test(value) ? value.toLowerCase() : null;
+}
+function titleTokens(title) {
+  return new Set(title.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((t) => t.length >= 3));
+}
+function jaccardScore(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  const intersection = new Set([...a].filter((x) => b.has(x)));
+  const union = /* @__PURE__ */ new Set([...a, ...b]);
+  return intersection.size / union.size;
+}
+var FUZZY_THRESHOLD = 0.5;
+var MIN_TOKENS_TO_QUALIFY = 3;
+var WikiMemory = class {
+  db;
+  prefix;
+  options;
+  activeMaintenanceJobs = /* @__PURE__ */ new Set();
+  constructor(db, options) {
+    this.db = db;
+    this.options = options;
+    this.prefix = options.config?.tablePrefix || "llm_wiki_";
+  }
+  async setup() {
+    await setupDatabase(this.db, this.prefix);
+    const rows = await this.db.getAllAsync(`
+      SELECT rowid, source_ref FROM ${this.prefix}entries
+      WHERE source_ref IS NOT NULL
+        AND (
+          TRIM(source_ref) != source_ref
+          OR INSTR(source_ref, '/') > 0
+          OR INSTR(source_ref, '\\') > 0
+          OR INSTR(source_ref, CHAR(0)) > 0
+          OR source_ref GLOB '*[^-A-Za-z0-9._ ]*'
+        )
+    `);
+    await this.db.withTransactionAsync(async () => {
+      for (const row of rows) {
+        const normalized = normalizeSourceRef(row.source_ref);
+        if (normalized !== row.source_ref) {
+          await this.db.runAsync(
+            `UPDATE ${this.prefix}entries SET source_ref = ? WHERE rowid = ?`,
+            [normalized, row.rowid]
+          );
+        }
+      }
+    });
+  }
+  formatSearchQuery(query) {
+    const tokens = query.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((t) => t.length >= 3).slice(0, 6);
+    if (tokens.length === 0) return "";
+    return tokens.map((t) => `"${t}"*`).join(" OR ");
+  }
+  async read(entityId, query) {
+    const ftsQuery = this.formatSearchQuery(query);
+    const maxResults = this.options.config?.maxFtsResults || 10;
+    let factsPromise;
+    if (ftsQuery) {
+      factsPromise = this.db.getAllAsync(`
+        SELECT e.* FROM ${this.prefix}entries e
+        JOIN ${this.prefix}entries_fts fts ON e.rowid = fts.rowid
+        WHERE fts.${this.prefix}entries_fts MATCH ?
+          AND e.entity_id = ?
+          AND e.deleted_at IS NULL
+        ORDER BY e.confidence DESC, e.access_count DESC, e.updated_at DESC
+        LIMIT ?
+      `, [ftsQuery, entityId, maxResults]);
+    } else {
+      factsPromise = this.db.getAllAsync(`
+        SELECT * FROM ${this.prefix}entries
+        WHERE entity_id = ? AND deleted_at IS NULL
+        ORDER BY updated_at DESC
+        LIMIT ?
+      `, [entityId, maxResults]);
+    }
+    const tasksPromise = this.db.getAllAsync(`
+      SELECT * FROM ${this.prefix}tasks
+      WHERE entity_id = ? AND status IN ('pending', 'in_progress') AND deleted_at IS NULL
+      ORDER BY priority DESC, created_at ASC
+    `, [entityId]);
+    const eventsPromise = this.db.getAllAsync(`
+      SELECT * FROM ${this.prefix}events
+      WHERE entity_id = ?
+      ORDER BY created_at DESC
+      LIMIT 10
+    `, [entityId]);
+    const [factsRaw, tasks, events] = await Promise.all([factsPromise, tasksPromise, eventsPromise]);
+    if (ftsQuery && factsRaw.length > 0) {
+      const ids = factsRaw.map((f) => f.id);
+      const placeholders = ids.map(() => "?").join(",");
+      const now = Date.now();
+      await this.db.runAsync(`
+        UPDATE ${this.prefix}entries 
+        SET access_count = access_count + 1, last_accessed_at = ?
+        WHERE id IN (${placeholders})
+      `, [now, ...ids]);
+    }
+    const facts = factsRaw.map((f) => ({
+      ...f,
+      tags: typeof f.tags === "string" ? JSON.parse(f.tags) : f.tags
+    }));
+    return { facts, tasks, events: events.reverse() };
+  }
+  async write(entityId, event) {
+    const id = generateId("evt_");
+    const now = Date.now();
+    let eventType = event.event_type;
+    if (!["observation", "decision", "action", "outcome"].includes(eventType)) {
+      eventType = "observation";
+    }
+    await this.db.runAsync(`
+      INSERT INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `, [id, entityId, eventType, event.summary, event.related_entry_id || null, now]);
+    const threshold = this.options.config?.autoLibrarianThreshold || 20;
+    const [row, cp] = await Promise.all([
+      this.db.getFirstAsync(`SELECT COUNT(*) as count FROM ${this.prefix}events WHERE entity_id = ?`, [entityId]),
+      this.db.getFirstAsync(`SELECT * FROM ${this.prefix}checkpoints WHERE entity_id = ?`, [entityId])
+    ]);
+    const count = row?.count || 0;
+    let memoryCheckpoint = cp?.memory_checkpoint || 0;
+    if (memoryCheckpoint > count) memoryCheckpoint = 0;
+    if (count - memoryCheckpoint >= threshold) {
+      const jobKey = `${this.prefix}:${entityId}`;
+      if (!this.activeMaintenanceJobs.has(jobKey)) {
+        this.activeMaintenanceJobs.add(jobKey);
+        this.runLibrarianThenMaybeHeal(entityId, count).catch(console.error).finally(() => this.activeMaintenanceJobs.delete(jobKey));
+      }
+    }
+  }
+  async runLibrarianThenMaybeHeal(entityId, currentEventCount) {
+    await this._doRunLibrarian(entityId);
+    await this.db.runAsync(`
+      INSERT INTO ${this.prefix}checkpoints (entity_id, memory_checkpoint) 
+      VALUES (?, ?) 
+      ON CONFLICT(entity_id) DO UPDATE SET memory_checkpoint = ?
+    `, [entityId, currentEventCount, currentEventCount]);
+    const autoHealThreshold = this.options.config?.autoHealThreshold || 100;
+    const cp = await this.db.getFirstAsync(`SELECT * FROM ${this.prefix}checkpoints WHERE entity_id = ?`, [entityId]);
+    let healCheckpoint = cp?.heal_checkpoint || 0;
+    if (healCheckpoint > currentEventCount) healCheckpoint = 0;
+    if (currentEventCount - healCheckpoint >= autoHealThreshold) {
+      await this._doRunHeal(entityId);
+      await this.db.runAsync(`
+        INSERT INTO ${this.prefix}checkpoints (entity_id, heal_checkpoint) 
+        VALUES (?, ?) 
+        ON CONFLICT(entity_id) DO UPDATE SET heal_checkpoint = ?
+      `, [entityId, currentEventCount, currentEventCount]);
+    }
+  }
+  async _doRunLibrarian(entityId) {
+    const events = await this.db.getAllAsync(`
+      SELECT * FROM ${this.prefix}events
+      WHERE entity_id = ?
+      ORDER BY created_at DESC
+      LIMIT 50
+    `, [entityId]);
+    const currentFactsRows = await this.db.getAllAsync(`
+      SELECT * FROM ${this.prefix}entries
+      WHERE entity_id = ? AND deleted_at IS NULL
+      ORDER BY updated_at DESC
+      LIMIT 100
+    `, [entityId]);
+    const currentFacts = currentFactsRows.map((f) => ({
+      ...f,
+      tags: typeof f.tags === "string" ? JSON.parse(f.tags) : f.tags
+    }));
+    const userPrompt = `Events:
+${JSON.stringify(events.reverse(), null, 2)}
+
+Current Facts:
+${JSON.stringify(currentFacts, null, 2)}`;
+    const responseText = await this.options.llmProvider.generateText({
+      systemPrompt: LIBRARIAN_SYSTEM_PROMPT,
+      userPrompt
+    });
+    const result = parseJsonResponse(responseText);
+    const facts = Array.isArray(result.facts) ? result.facts : [];
+    const tasks = Array.isArray(result.tasks) ? result.tasks : [];
+    const validFacts = facts.map(validateFact).filter((f) => f !== null);
+    const validTasks = tasks.map(validateTask).filter((t) => t !== null);
+    const now = Date.now();
+    await this.db.withTransactionAsync(async () => {
+      for (const fact of validFacts) {
+        const newTokens = titleTokens(fact.title);
+        let skip = false;
+        if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
+          for (const existing of currentFactsRows) {
+            if (existing.source_type !== "agent_inferred") continue;
+            const existingTokens = titleTokens(existing.title);
+            if (existingTokens.size >= MIN_TOKENS_TO_QUALIFY) {
+              if (jaccardScore(newTokens, existingTokens) >= FUZZY_THRESHOLD) {
+                skip = true;
+                break;
+              }
+            }
+          }
+        }
+        if (skip) continue;
+        const id = generateId("fact_");
+        await this.db.runAsync(`
+          INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "agent_inferred", now, now]);
+      }
+      for (const task of validTasks) {
+        const id = generateId("task_");
+        await this.db.runAsync(`
+          INSERT INTO ${this.prefix}tasks (id, entity_id, description, status, priority, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?)
+        `, [id, entityId, task.description, "pending", task.priority, now, now]);
+      }
+    });
+  }
+  async _doRunHeal(entityId) {
+    const now = Date.now();
+    const orphanAfterDays = this.options.config?.orphanAfterDays !== void 0 ? this.options.config.orphanAfterDays : 30;
+    const staleInferredAfterDays = this.options.config?.staleInferredAfterDays !== void 0 ? this.options.config.staleInferredAfterDays : 60;
+    const MS_PER_DAY = 24 * 60 * 60 * 1e3;
+    if (orphanAfterDays !== null && (typeof orphanAfterDays !== "number" || !Number.isFinite(orphanAfterDays) || orphanAfterDays < 0)) {
+      throw new Error("Invalid orphanAfterDays: must be a finite number >= 0 or null");
+    }
+    if (staleInferredAfterDays !== null && (typeof staleInferredAfterDays !== "number" || !Number.isFinite(staleInferredAfterDays) || staleInferredAfterDays < 0)) {
+      throw new Error("Invalid staleInferredAfterDays: must be a finite number >= 0 or null");
+    }
+    await this.db.withTransactionAsync(async () => {
+      if (orphanAfterDays !== null) {
+        const orphanThreshold = now - orphanAfterDays * MS_PER_DAY;
+        await this.db.runAsync(`
+          UPDATE ${this.prefix}entries 
+          SET deleted_at = ?, updated_at = ? 
+          WHERE entity_id = ? AND access_count = 0 AND created_at < ? AND source_type != 'user_document' AND deleted_at IS NULL
+        `, [now, now, entityId, orphanThreshold]);
+      }
+      if (staleInferredAfterDays !== null) {
+        const staleThreshold = now - staleInferredAfterDays * MS_PER_DAY;
+        await this.db.runAsync(`
+          UPDATE ${this.prefix}entries 
+          SET confidence = 'tentative', updated_at = ? 
+          WHERE entity_id = ? AND confidence = 'inferred' AND (last_accessed_at < ? OR (last_accessed_at IS NULL AND created_at < ?)) AND source_type != 'user_document' AND deleted_at IS NULL
+        `, [now, entityId, staleThreshold, staleThreshold]);
+      }
+    });
+    const allFactsRows = await this.db.getAllAsync(`SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`, [entityId]);
+    const allTasks = await this.db.getAllAsync(`SELECT * FROM ${this.prefix}tasks WHERE entity_id = ? AND status IN ('pending', 'in_progress') AND deleted_at IS NULL`, [entityId]);
+    const recentEvents = await this.db.getAllAsync(`SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at DESC LIMIT 20`, [entityId]);
+    const healCandidates = allFactsRows.filter((f) => f.source_type !== "user_document");
+    const documentAnchors = allFactsRows.filter((f) => f.source_type === "user_document").map(({ id, title, source_ref }) => ({ id, title, source_ref }));
+    const userPrompt = `Heal Candidates:
+${JSON.stringify(healCandidates.map((f) => ({ ...f, tags: typeof f.tags === "string" ? JSON.parse(f.tags) : f.tags })), null, 2)}
+
+Document Anchors (DO NOT MODIFY OR DELETE):
+${JSON.stringify(documentAnchors, null, 2)}
+
+All Tasks:
+${JSON.stringify(allTasks, null, 2)}
+
+Recent Events:
+${JSON.stringify(recentEvents, null, 2)}
+
+The following document anchors are provided for contradiction detection only. Do not include them in \`downgraded\`, \`deleted\`, or \`newFacts\`.`;
+    const responseText = await this.options.llmProvider.generateText({
+      systemPrompt: HEAL_SYSTEM_PROMPT,
+      userPrompt
+    });
+    const result = parseJsonResponse(responseText);
+    const mutableIds = new Set(healCandidates.map((f) => f.id));
+    const downgraded = Array.isArray(result.downgraded) ? result.downgraded : [];
+    const deleted = Array.isArray(result.deleted) ? result.deleted : [];
+    const newFacts = Array.isArray(result.newFacts) ? result.newFacts : [];
+    const safeDowngraded = downgraded.filter((id) => mutableIds.has(id));
+    const safeDeleted = deleted.filter((id) => mutableIds.has(id));
+    const validNewFacts = newFacts.map(validateFact).filter((f) => f !== null);
+    await this.db.withTransactionAsync(async () => {
+      for (const id of safeDowngraded) {
+        await this.db.runAsync(`UPDATE ${this.prefix}entries SET confidence = 'tentative', updated_at = ? WHERE id = ? AND entity_id = ?`, [now, id, entityId]);
+      }
+      for (const id of safeDeleted) {
+        await this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ?`, [now, now, id, entityId]);
+      }
+      for (const fact of validNewFacts) {
+        const id = generateId("fact_");
+        await this.db.runAsync(`
+          INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "agent_inferred", now, now]);
+      }
+    });
+  }
+  async runLibrarian(entityId) {
+    const jobKey = `${this.prefix}:${entityId}`;
+    if (this.activeMaintenanceJobs.has(jobKey)) return;
+    this.activeMaintenanceJobs.add(jobKey);
+    try {
+      await this._doRunLibrarian(entityId);
+    } finally {
+      this.activeMaintenanceJobs.delete(jobKey);
+    }
+  }
+  async runHeal(entityId) {
+    const jobKey = `${this.prefix}:${entityId}`;
+    if (this.activeMaintenanceJobs.has(jobKey)) return;
+    this.activeMaintenanceJobs.add(jobKey);
+    try {
+      await this._doRunHeal(entityId);
+    } finally {
+      this.activeMaintenanceJobs.delete(jobKey);
+    }
+  }
+  async forget(entityId, params) {
+    const now = Date.now();
+    let deletedEntries = 0;
+    let deletedTasks = 0;
+    if (params.clearAll) {
+      const [entriesRes, tasksRes] = await Promise.all([
+        this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`, [now, now, entityId]),
+        this.db.runAsync(`UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`, [now, now, entityId])
+      ]);
+      await this.db.runAsync(`UPDATE ${this.prefix}checkpoints SET memory_checkpoint = 0, heal_checkpoint = 0 WHERE entity_id = ?`, [entityId]);
+      deletedEntries = entriesRes.changes;
+      deletedTasks = tasksRes.changes;
+    } else {
+      const hasIdSelectors = params.entryId !== void 0 || params.taskId !== void 0;
+      const hasSourceSelectors = params.sourceRef !== void 0 || params.sourceHash !== void 0;
+      if (hasIdSelectors && hasSourceSelectors) {
+        throw new Error("forget() params are mutually exclusive: use entryId/taskId together, or sourceRef/sourceHash together, but not both in the same call");
+      }
+      const sourceRef = params.sourceRef !== void 0 ? normalizeSourceRef(params.sourceRef) : null;
+      if (params.sourceRef !== void 0 && !sourceRef) throw new Error("Invalid sourceRef");
+      const sourceHash = params.sourceHash !== void 0 ? normalizeSourceHash(params.sourceHash) : null;
+      if (params.sourceHash !== void 0 && !sourceHash) throw new Error("Invalid sourceHash (must be 64-char hex string)");
+      const entryPromise = params.entryId ? this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`, [now, now, params.entryId, entityId]) : null;
+      const taskPromise = params.taskId ? this.db.runAsync(`UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`, [now, now, params.taskId, entityId]) : null;
+      let refPromise = null;
+      if (sourceRef || sourceHash) {
+        let q = `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`;
+        const args = [now, now, entityId];
+        if (sourceRef) {
+          q += ` AND source_ref = ?`;
+          args.push(sourceRef);
+        }
+        if (sourceHash) {
+          q += ` AND source_hash = ?`;
+          args.push(sourceHash);
+        }
+        refPromise = this.db.runAsync(q, args);
+      }
+      const [entryResult, taskResult, refResult] = await Promise.all([
+        entryPromise ?? Promise.resolve(null),
+        taskPromise ?? Promise.resolve(null),
+        refPromise ?? Promise.resolve(null)
+      ]);
+      if (entryResult) deletedEntries += entryResult.changes;
+      if (taskResult) deletedTasks += taskResult.changes;
+      if (refResult) deletedEntries += refResult.changes;
+    }
+    return { deleted: { entries: deletedEntries, tasks: deletedTasks } };
+  }
+  async ingestDocument(entityId, params) {
+    const sourceRef = normalizeSourceRef(params.sourceRef);
+    if (!sourceRef) throw new Error("Invalid sourceRef");
+    const sourceHash = normalizeSourceHash(params.sourceHash);
+    if (!sourceHash) throw new Error("Invalid sourceHash (must be 64-char hex string)");
+    const maxChunkLength = params.maxChunkLength ?? this.options.config?.maxChunkLength ?? 6e3;
+    if (!Number.isInteger(maxChunkLength) || maxChunkLength < 2) {
+      throw new Error("maxChunkLength must be an integer greater than or equal to 2");
+    }
+    if (typeof params.documentChunk !== "string") {
+      throw new Error(`documentChunk must be a string, received ${typeof params.documentChunk}`);
+    }
+    const chunks = [];
+    let truncated = false;
+    let text = params.documentChunk.trim();
+    if (text.length === 0) {
+      return { truncated: false, chunks: 0 };
+    }
+    while (text.length > 0) {
+      if (text.length <= maxChunkLength) {
+        chunks.push(text);
+        break;
+      }
+      const searchArea = text.slice(0, maxChunkLength + 1);
+      const match = searchArea.match(/[.!?]\s+(?![\s\S]*[.!?]\s+)/);
+      if (match && match.index !== void 0) {
+        const splitPoint = Math.min(match.index + match[0].length, maxChunkLength);
+        const chunk = safeSlice(text, 0, splitPoint);
+        chunks.push(chunk);
+        text = text.slice(chunk.length);
+      } else {
+        truncated = true;
+        const chunk = safeSlice(text, 0, maxChunkLength);
+        chunks.push(chunk);
+        text = text.slice(chunk.length);
+      }
+    }
+    const allValidFacts = [];
+    for (const chunk of chunks) {
+      const userPrompt = `Document Chunk:
+${chunk}`;
+      const responseText = await this.options.llmProvider.generateText({
+        systemPrompt: INGEST_SYSTEM_PROMPT,
+        userPrompt
+      });
+      const result = parseJsonResponse(responseText);
+      const validFacts = (Array.isArray(result.facts) ? result.facts : []).map(validateFact).filter((f) => f !== null);
+      allValidFacts.push(...validFacts);
+    }
+    const now = Date.now();
+    await this.db.withTransactionAsync(async () => {
+      await this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE source_ref = ? AND entity_id = ? AND deleted_at IS NULL`, [now, now, sourceRef, entityId]);
+      for (const fact of allValidFacts) {
+        const id = generateId("fact_");
+        await this.db.runAsync(`
+                INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, source_hash, source_ref, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "user_document", sourceHash, sourceRef, now, now]);
+      }
+    });
+    return { truncated, chunks: chunks.length };
+  }
+};
+
+// src/index.ts
+function createWiki(db, options) {
+  return new WikiMemory(db, options);
+}
+export {
+  WikiMemory,
+  createWiki
+};