@modusensus/dsh-mneme 0.4.5 → 0.4.6

package/src/service.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { TYPE_FILE } from "./mirror.js";
+import { evaluateMemoryQuality } from "./quality-filter.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
@@ -9,6 +10,29 @@ const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 // unknown statuses are unscaled (×1). Off by default, so nothing changes.
 const EPISTEMIC_WEIGHTS = { observation: 1.0, inferred: 0.85, subjective: 0.7 };
 
+// Bug5: content version history cap (FIFO — the newest 20 versions are kept,
+// older ones dropped). Entries are {content, source, updated_at}; source marks
+// how the version was superseded (auto_merge | human_override | overwrite).
+const CONTENT_HISTORY_MAX = 20;
+
+/** Prepend the previous content to a memory's content_history (FIFO capped). */
+function pushContentHistory(existing, source) {
+  const history = Array.isArray(existing?.content_history) ? existing.content_history : [];
+  return [
+    { content: existing?.content ?? "", source, updated_at: new Date().toISOString() },
+    ...history
+  ].slice(0, CONTENT_HISTORY_MAX);
+}
+
+/** Bug5: same-title merge appends the new content under a timestamped `---`
+ *  separator instead of overwriting, so a re-noted memory never loses history.
+ *  The `---` line is compatible with the mirror's readHumanEdits (which strips
+ *  only the LAST structural `---` when parsing the human-editable file). */
+function appendContent(oldContent, newContent) {
+  const ts = new Date().toISOString();
+  return `${oldContent}\n\n---\n[${ts}] ${newContent}`;
+}
+
 /**
  * Standard retrieval-quality metrics over the ordered candidate ids actually
  * returned vs the ids the evaluator marked relevant (方案 B). Pure + total, so
@@ -69,6 +93,13 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   // judgment-layer audit trail (dream_runs).
   let recallRecorder = null;
 
+  // Bug4: semantic recall cache for the injection path. The system-prompt
+  // interpolator renders context synchronously, so injectCandidates cannot
+  // fire a fresh async embed. The most recent searchMemories recall is cached
+  // here (query + ordered candidates) and reused when the injection query
+  // matches, giving semantic-first injection without breaking the sync render.
+  let lastSemanticRecall = null;
+
   // Transaction nesting depth. Inside service.transaction the per-mutation side
   // effects (mirror render, write notify, re-embed) are deferred so a ROLLBACK
   // never leaves the mirror file diverged from the database; transaction()
@@ -429,6 +460,9 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         });
       } catch { /* recall receipt is best effort */ }
     }
+    // Bug4: cache the latest semantic recall so the sync injection path can
+    // reuse it when the injection query matches (no async embed available).
+    lastSemanticRecall = { query: q, items: result };
     touchRecalled(result);
     return result;
   }
@@ -570,25 +604,91 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     }
   }
 
+  /**
+   * Embed an arbitrary query text and return its vector (null on failure / no
+   * embedder). Used by the injector to prefetch the semantic-first recall
+   * vector for the current user message — the system-prompt render is
+   * synchronous, so the vector must be cached in advance (Bug4).
+   */
+  async function embedQuery(query) {
+    const q = String(query ?? "").trim();
+    if (!q || !embedder) return null;
+    try {
+      const embedSingle = typeof embedder.embedSingle === "function"
+        ? embedder.embedSingle.bind(embedder)
+        : embedder.embed.bind(embedder);
+      const vector = await embedSingle(q);
+      return Array.isArray(vector) && vector.length ? vector : null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Save a memory, merging into an existing one when title matches within the same type.
+   *
+   * Bug5: a same-title merge no longer overwrites — the new content is appended
+   * under a timestamped `---` separator (`旧内容\n\n---\n[时间戳] 新内容`) and the
+   * previous content is archived into content_history (source: auto_merge, FIFO
+   * capped at 20). importance takes the max of both (capped at 5). Callers that
+   * truly replace a row (dream summary regeneration) pass `_overwrite: true` to
+   * overwrite directly while still archiving the old version (source: overwrite).
+   * mergeHumanEdits entry points pass `_humanEdited: true` — same direct
+   * overwrite semantics, source: human_override.
+   *
+   * Bug7 (memory quality filter): when config.memoryQualityFilter.enabled, the
+   * memory is scored after dedupe, before write:
+   *   score >= degradeThreshold        → stored normally (score persisted)
+   *   archiveThreshold <= score < 60   → persisted + ranked degraded
+   *   score < archiveThreshold         → archived + tagged low_quality (still
+   *                                      explicitly searchable via includeArchived)
    * @returns {{action: "created"|"merged", memory: object}}
    */
   function saveWithDedupe(memory) {
+    // Bug7: score quality once (after dedupe lookup, before write). Failures
+    // inside the evaluator are impossible (pure function), but the write that
+    // records the score must never fail the save — wrap defensively.
+    const qf = config.memoryQualityFilter;
+    let quality = null;
+    if (qf?.enabled === true) {
+      try {
+        const recentContents = store.all().slice(0, 20).map((m) => m.content ?? "");
+        quality = evaluateMemoryQuality(memory, {
+          minContentLength: qf.minContentLength ?? 10,
+          recentContents
+        });
+      } catch { /* quality scoring is best-effort */ }
+    }
     const existing = store
       .list({ type: memory.type, limit: 100 })
       .find((m) => m.title.trim() === String(memory.title).trim());
     if (existing) {
+      const newContent = String(memory.content ?? "");
+      if (!newContent.trim()) {
+        // Nothing to merge: the row stays untouched.
+        return { action: "merged", memory: existing };
+      }
+      const direct = memory._overwrite === true || memory._humanEdited === true;
+      const content = direct
+        ? newContent
+        : appendContent(existing.content, newContent);
+      const importance = Math.min(5, Math.max(existing.importance, memory.importance ?? existing.importance));
       const merged = store.update(existing.id, {
-        content: memory.content ?? existing.content,
-        importance: memory.importance ?? existing.importance,
+        content,
+        importance,
         tags: memory.tags ?? existing.tags,
-        title: memory.title ?? existing.title
+        title: memory.title ?? existing.title,
+        content_history: pushContentHistory(existing, direct
+          ? (memory._humanEdited === true ? "human_override" : "overwrite")
+          : "auto_merge"),
+        ...(quality ? { quality_score: quality.score } : {})
       });
+      // Bug7: a degraded/archived result is applied on top of the merged row.
+      const result = applyQualityDisposition(merged, quality, qf);
       afterSync("write");
       notifyWrite();
-      scheduleEmbed(merged);
-      return { action: "merged", memory: merged };
+      scheduleEmbed(result);
+      return { action: "merged", memory: result };
     }
     const created = store.save({
       type: memory.type,
@@ -596,13 +696,44 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       content: memory.content,
       tags: memory.tags ?? [],
       importance: memory.importance ?? 3,
-      source: memory.source ?? "manual"
+      source: memory.source ?? "manual",
+      ...(quality ? { quality_score: quality.score } : {})
     });
+    const result = applyQualityDisposition(created, quality, qf);
     afterSync("write");
     notifyWrite();
-    scheduleEmbed(created);
-    scheduleEntityExtraction(created);
-    return { action: "created", memory: created };
+    scheduleEmbed(result);
+    scheduleEntityExtraction(result);
+    return { action: "created", memory: result };
+  }
+
+  /**
+   * Bug7: apply the quality verdict to a freshly written row. Below the archive
+   * threshold the memory is archived + tagged low_quality (still searchable
+   * explicitly via includeArchived); between archive and degrade thresholds the
+   * score is already persisted and only the injection ranking is affected
+   * (importance × score/100). Best-effort: a disposition write failure must
+   * never fail the save. Returns the (possibly refreshed) memory row so callers
+   * see the archived/tagged state, not the pre-disposition snapshot.
+   */
+  function applyQualityDisposition(memory, quality, qf) {
+    if (!quality || qf?.enabled !== true) return memory;
+    const archiveThreshold = qf.archiveThreshold ?? 30;
+    // Signal tags (meta / repetitive / duplicate / short_content / low_quality)
+    // are merged onto the stored row in every assessed band so the verdict is
+    // observable, not just the numeric score. Below the archive threshold the
+    // memory is additionally archived (still explicitly searchable).
+    const tags = [...new Set([...(memory.tags ?? []), ...(quality.tags ?? [])])];
+    if (tags.length === (memory.tags?.length ?? 0) && quality.score >= archiveThreshold) {
+      return memory; // no tag drift and not archived → nothing extra to write
+    }
+    try {
+      store.update(memory.id, { tags, quality_score: quality.score });
+      if (quality.score < archiveThreshold) store.setArchived(memory.id, true);
+      return store.getById(memory.id);
+    } catch {
+      return memory;
+    }
   }
 
   /**
@@ -611,17 +742,71 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * importance >= threshold. History is never auto-injected. Archived entries
    * are excluded (store.list already filters them by default; the extra
    * !m.archived check is kept as double insurance).
+   *
+   * Bug4 (hybridInject): when a non-empty `query` is available and a matching
+   * semantic recall was cached by the last searchMemories, the vector hits
+   * lead the selection (up to maxItems*2 candidates) and the rule-based pick
+   * fills + dedupes the remaining slots. Empty query / no cached recall /
+   * hybridInject off → pure legacy rule-based selection.
    */
-  function injectCandidates({ maxItems = 5, threshold = 3 } = {}) {
+  function injectCandidates({ query = "", maxItems = 5, threshold = 3, queryVector } = {}) {
+    const q = String(query ?? "").trim();
+    // Bug7: quality-weighted importance in the rule-based tier. Unassessed rows
+    // (quality_score null) count as 100 (weight 1), so legacy stores keep their
+    // exact summary>preference>importance ordering.
+    const qualityWeight = (m) => (m.quality_score != null ? m.quality_score / 100 : 1);
     const items = store.list({ limit: 200, includeForgotten: false })
       .filter((m) => !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten &&
         (m.type === "summary" || m.type === "preference" || m.importance >= threshold))
       .sort((a, b) => {
         const pa = a.type === "summary" ? 0 : a.type === "preference" ? 1 : 2;
         const pb = b.type === "summary" ? 0 : b.type === "preference" ? 1 : 2;
-        return pa - pb || b.importance - a.importance;
+        return pa - pb || (b.importance * qualityWeight(b)) - (a.importance * qualityWeight(a));
       });
-    const selected = items.slice(0, maxItems);
+    let candidates = items;
+    if (config.hybridInject !== false && q) {
+      // Bug4: semantic-first recall. Vector hits (queryVector, cached by the
+      // injector's async prefetch) lead when present; otherwise the last
+      // searchMemories recall for the exact same query is reused. Rule-based
+      // items fill + dedupe the remaining slots. Empty query / no vector /
+      // no cached recall → pure legacy rule-based selection.
+      const semanticItems = [];
+      if (Array.isArray(queryVector) && queryVector.length && vectorIndex) {
+        try {
+          const hits = vectorIndex.search(queryVector, { limit: maxItems * 2, threshold: 0 });
+          for (const m of hits) {
+            if (m && !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten &&
+              (m.type === "summary" || m.type === "preference" || m.importance >= threshold)) {
+              semanticItems.push(m);
+            }
+          }
+        } catch { /* vector unavailable: fall through to the recall cache */ }
+      }
+      if (!semanticItems.length && lastSemanticRecall?.query === q && lastSemanticRecall.items?.length) {
+        for (const m of lastSemanticRecall.items) {
+          if (m && !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten) semanticItems.push(m);
+        }
+      }
+      if (semanticItems.length) {
+        const seen = new Set();
+        const merged = [];
+        const push = (m) => {
+          if (seen.has(m.id)) return;
+          seen.add(m.id);
+          merged.push(m);
+        };
+        for (const m of semanticItems) {
+          push(m);
+          if (merged.length >= maxItems * 2) break;
+        }
+        for (const m of items) {
+          if (merged.length >= maxItems * 2) break;
+          push(m);
+        }
+        candidates = merged;
+      }
+    }
+    const selected = candidates.slice(0, maxItems);
     touchRecalled(selected);
     return selected;
   }
@@ -654,7 +839,15 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         // 人工编辑回灌后触发 re-embed（issue #3 残留修复）：向量必须与
         // 新 title/content 一致。scheduleEmbed 为 fire-and-forget，
         // 内部 try/catch 吞错，失败不影响主流程。
-        const merged = store.update(edit.id, patch);
+        // Bug5: human edits overwrite directly, but the machine version is
+        // archived into content_history (source: human_override) before being
+        // replaced, so a manual correction never silently destroys the old value.
+        const merged = store.update(edit.id, {
+          ...patch,
+          content_history: patch.content !== undefined && existing.content !== patch.content
+            ? pushContentHistory(existing, "human_override")
+            : existing.content_history
+        });
         applied++;
         scheduleEmbed(merged);
       }
@@ -999,6 +1192,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     setReranker(rn) { reranker = rn; },
     setRecallRecorder(fn) { recallRecorder = fn; },
     searchMemories,
+    embedQuery,
     evaluateRetrieval,
     computeRetrievalMetrics,
     // passthroughs used by tools and api layers; mutations keep the mirror in sync
@@ -1139,6 +1333,13 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     saveRecallEval: (r) => store.saveRecallEval(r),
     getRecallEval: (id) => store.getRecallEval(id),
     listRecallEvals: (opts) => store.listRecallEvals(opts),
+    // LLM audit trail (Bug8): bookkeeping semantics like the recall/dream
+    // passthroughs — a saveLlmAudit write never triggers write hooks.
+    saveLlmAudit: (entry) => store.saveLlmAudit(entry),
+    listLlmAudits: (opts) => store.listLlmAudits(opts),
+    countLlmAudits: (opts) => store.countLlmAudits(opts),
+    getLlmAuditStats: (opts) => store.getLlmAuditStats(opts),
+    deleteOldLlmAudits: (before) => store.deleteOldLlmAudits(before),
     // Entity gene (v0.3.0) passthroughs for the autoDream apply path
     // (applyDecisions): records supersedes relations after an update and
     // migrates entity_attrs on merge. Bookkeeping writes like the audit

package/src/store.js

@@ -12,6 +12,7 @@ CREATE TABLE IF NOT EXISTS memories (
   forgotten   INTEGER NOT NULL DEFAULT 0,
   archived    INTEGER NOT NULL DEFAULT 0,
   source      TEXT,
+  content_history TEXT,
   embedding   TEXT,
   epistemic_status TEXT NOT NULL DEFAULT 'subjective',
   last_accessed_at  TEXT,
@@ -146,6 +147,31 @@ CREATE TABLE IF NOT EXISTS conflict_pending (
 );
 CREATE INDEX IF NOT EXISTS idx_conflict_pending_unresolved ON conflict_pending(resolved_at);
 
+-- llm_audit_logs: every background LLM call (autoDream consolidation + summary,
+-- autoSummarize compression) is recorded here — tokens in/out, duration, status
+-- and the trigger that caused it (Bug8). Failures are captured as status='error'
+-- and never block the calling feature. retentionDays is enforced by a boot-time
+-- purge (deleteOldLlmAudits). Bookkeeping like the other audit tables: it never
+-- triggers write hooks.
+CREATE TABLE IF NOT EXISTS llm_audit_logs (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp         TEXT NOT NULL,
+  trigger_source    TEXT NOT NULL,          -- autoDream | autoSummarize | manual ...
+  operation_type    TEXT NOT NULL,          -- dream_consolidate | dream_summarize | summarize_compress ...
+  model_id          TEXT NOT NULL,
+  input_tokens      INTEGER NOT NULL DEFAULT 0,
+  output_tokens     INTEGER NOT NULL DEFAULT 0,
+  total_tokens      INTEGER NOT NULL DEFAULT 0,
+  cost_usd          REAL NOT NULL DEFAULT 0,
+  duration_ms       INTEGER NOT NULL DEFAULT 0,
+  status            TEXT NOT NULL,          -- success | error | skipped
+  error_message     TEXT,
+  related_memory_ids TEXT,                  -- JSON: ids the call operated on
+  metadata          TEXT                    -- JSON: free-form extras
+);
+CREATE INDEX IF NOT EXISTS idx_llm_audit_timestamp ON llm_audit_logs(timestamp);
+CREATE INDEX IF NOT EXISTS idx_llm_audit_source ON llm_audit_logs(trigger_source);
+
 -- entity gene (v0.3.0): named entities mentioned across memories, with
 -- time-boxed attributes (valid_from → valid_until) and typed relations.
 -- Attributes follow the snapshot style: saveAttr invalidates the previous
@@ -295,6 +321,8 @@ function toRow(row) {
     forgotten: row.forgotten === 1,
     archived: row.archived === 1,
     source: row.source ?? undefined,
+    content_history: parseJsonArray(row.content_history),
+    quality_score: row.quality_score !== null && row.quality_score !== undefined ? Number(row.quality_score) : undefined,
     epistemic_status: row.epistemic_status ?? "subjective",
     created_at: row.created_at,
     updated_at: row.updated_at,
@@ -439,6 +467,34 @@ function toRelation(row) {
   };
 }
 
+function toLlmAudit(row) {
+  if (!row) return undefined;
+  let metadata;
+  if (row.metadata != null) {
+    try {
+      metadata = JSON.parse(row.metadata);
+    } catch {
+      metadata = row.metadata;
+    }
+  }
+  return {
+    id: row.id,
+    timestamp: row.timestamp,
+    trigger_source: row.trigger_source,
+    operation_type: row.operation_type,
+    model_id: row.model_id,
+    input_tokens: row.input_tokens,
+    output_tokens: row.output_tokens,
+    total_tokens: row.total_tokens,
+    cost_usd: row.cost_usd,
+    duration_ms: row.duration_ms,
+    status: row.status,
+    error_message: row.error_message ?? undefined,
+    related_memory_ids: parseJsonArray(row.related_memory_ids),
+    metadata
+  };
+}
+
 function toMirrorState(row) {
   if (!row) {
     return {
@@ -509,6 +565,12 @@ export function createStore(path) {
   if (!columns.includes("epistemic_status")) {
     db.exec("ALTER TABLE memories ADD COLUMN epistemic_status TEXT NOT NULL DEFAULT 'subjective'");
   }
+  if (!columns.includes("content_history")) {
+    db.exec("ALTER TABLE memories ADD COLUMN content_history TEXT");
+  }
+  if (!columns.includes("quality_score")) {
+    db.exec("ALTER TABLE memories ADD COLUMN quality_score REAL");
+  }
 
   // Legacy dream_runs without policy_epoch → backfill with the default epoch.
   const dreamCols = db.prepare("PRAGMA table_info(dream_runs)").all().map((c) => c.name);
@@ -607,9 +669,24 @@ export function createStore(path) {
       : inferEpistemicStatus(memory);
     runAtomically(() => {
       db.prepare(
-        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, source, embedding, epistemic_status, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?)`
-      ).run(id, type, memory.title, memory.content, tags, importance, memory.source ?? null, embedding, epistemicStatus, now, now);
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?)`
+      ).run(
+        id,
+        type,
+        memory.title,
+        memory.content,
+        tags,
+        importance,
+        memory.archived ? 1 : 0,
+        memory.source ?? null,
+        JSON.stringify(memory.content_history ?? []),
+        Number.isFinite(memory.quality_score) ? memory.quality_score : null,
+        embedding,
+        epistemicStatus,
+        now,
+        now
+      );
       // desired generation bumped in the same transaction as the write: once
       // this commits, generation > applied_generation, so a crash right after
       // (before syncMirror) is caught by recoverMirror on restart (peer
@@ -632,9 +709,15 @@ export function createStore(path) {
       ? (Array.isArray(patch.embedding) && patch.embedding.length ? JSON.stringify(patch.embedding) : null)
       : existing.embedding ?? null;
     const epistemicStatus = resolveEpistemicStatus(existing, patch);
+    const contentHistory = Array.isArray(patch.content_history)
+      ? JSON.stringify(patch.content_history)
+      : (Array.isArray(existing.content_history) ? JSON.stringify(existing.content_history) : null);
+    const qualityScore = patch.quality_score !== undefined && Number.isFinite(patch.quality_score)
+      ? patch.quality_score
+      : (existing.quality_score ?? null);
     runAtomically(() => {
       db.prepare(
-        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, epistemic_status=?, updated_at=? WHERE id=?`
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, updated_at=? WHERE id=?`
       ).run(
         type,
         patch.title ?? existing.title,
@@ -642,6 +725,8 @@ export function createStore(path) {
         JSON.stringify(patch.tags ?? existing.tags),
         Number.isInteger(patch.importance) ? patch.importance : existing.importance,
         patch.source !== undefined ? patch.source : (existing.source ?? null),
+        contentHistory,
+        qualityScore,
         embedding,
         epistemicStatus,
         now,
@@ -684,6 +769,12 @@ export function createStore(path) {
       ? (Array.isArray(patch.embedding) && patch.embedding.length ? JSON.stringify(patch.embedding) : null)
       : existing.embedding ?? null;
     const epistemicStatus = resolveEpistemicStatus(existing, patch);
+    const contentHistory = Array.isArray(patch.content_history)
+      ? JSON.stringify(patch.content_history)
+      : (Array.isArray(existing.content_history) ? JSON.stringify(existing.content_history) : null);
+    const qualityScore = patch.quality_score !== undefined && Number.isFinite(patch.quality_score)
+      ? patch.quality_score
+      : (existing.quality_score ?? null);
     // The CAS UPDATE and the desired-generation bump must commit together (audit
     // peer A): if the UPDATE autocommits first and the process dies before the
     // increment, the store is mutated while generation == applied_generation and
@@ -693,7 +784,7 @@ export function createStore(path) {
     let applied = false;
     runAtomically(() => {
       const result = db.prepare(
-        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, epistemic_status=?, updated_at=?
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, updated_at=?
          WHERE id=? AND updated_at=?`
       ).run(
         type,
@@ -702,6 +793,8 @@ export function createStore(path) {
         JSON.stringify(patch.tags ?? existing.tags),
         Number.isInteger(patch.importance) ? patch.importance : existing.importance,
         patch.source !== undefined ? patch.source : (existing.source ?? null),
+        contentHistory,
+        qualityScore,
         embedding,
         epistemicStatus,
         now,
@@ -1152,6 +1245,115 @@ export function createStore(path) {
     return rows.map(toRecallEval);
   }
 
+  // --- llm audit trail (Bug8) ---------------------------------------------
+
+  /**
+   * Persist one LLM audit row (a background call's token/time/status receipt).
+   * Bookkeeping like the other audit tables: it never triggers write hooks, so
+   * recording a call can never loop back into the scheduler that made it. The
+   * call itself is wrapped so a failure is captured (status='error') instead of
+   * blocking the feature — only a throwing saveLlmAudit is swallowed, never the
+   * LLM call.
+   */
+  function saveLlmAudit(entry) {
+    const now = nowIso();
+    const inTokens = Number.isFinite(entry.input_tokens) ? entry.input_tokens : 0;
+    const outTokens = Number.isFinite(entry.output_tokens) ? entry.output_tokens : 0;
+    db.prepare(
+      `INSERT INTO llm_audit_logs (timestamp, trigger_source, operation_type, model_id,
+        input_tokens, output_tokens, total_tokens, cost_usd, duration_ms, status,
+        error_message, related_memory_ids, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      entry.timestamp ?? now,
+      entry.trigger_source,
+      entry.operation_type,
+      entry.model_id,
+      inTokens,
+      outTokens,
+      Number.isFinite(entry.total_tokens) ? entry.total_tokens : inTokens + outTokens,
+      Number.isFinite(entry.cost_usd) ? entry.cost_usd : 0,
+      Number.isFinite(entry.duration_ms) ? entry.duration_ms : 0,
+      entry.status ?? "success",
+      entry.error_message ?? null,
+      JSON.stringify(entry.related_memory_ids ?? []),
+      entry.metadata !== undefined
+        ? (typeof entry.metadata === "string" ? entry.metadata : JSON.stringify(entry.metadata))
+        : null
+    );
+    return toLlmAudit(db.prepare("SELECT * FROM llm_audit_logs ORDER BY id DESC LIMIT 1").get());
+  }
+
+  function listLlmAudits({ limit = 50, offset = 0, source } = {}) {
+    const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
+    const clauses = [];
+    const params = [];
+    if (source) {
+      clauses.push("trigger_source = ?");
+      params.push(source);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const rows = db.prepare(
+      `SELECT * FROM llm_audit_logs ${where} ORDER BY timestamp DESC, id DESC LIMIT ? OFFSET ?`
+    ).all(...params, lim, off);
+    return rows.map(toLlmAudit);
+  }
+
+  function countLlmAudits({ source } = {}) {
+    const clauses = [];
+    const params = [];
+    if (source) {
+      clauses.push("trigger_source = ?");
+      params.push(source);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    return db.prepare(`SELECT count(*) AS c FROM llm_audit_logs ${where}`).get(...params).c;
+  }
+
+  /**
+   * Aggregate LLM spend over the last `days`: total calls/tokens/duration/cost,
+   * broken down by trigger_source and by status. Used by the API's
+   * /llm-audit/stats endpoint so the Web panel can show where budget goes.
+   */
+  function getLlmAuditStats({ days = 7 } = {}) {
+    const since = new Date(Date.now() - days * 86400000).toISOString();
+    const total = db.prepare(
+      `SELECT count(*) AS c,
+              COALESCE(SUM(input_tokens), 0) AS i,
+              COALESCE(SUM(output_tokens), 0) AS o,
+              COALESCE(SUM(total_tokens), 0) AS t,
+              COALESCE(SUM(duration_ms), 0) AS d,
+              COALESCE(SUM(cost_usd), 0) AS cst
+       FROM llm_audit_logs WHERE timestamp >= ?`
+    ).get(since);
+    const bySource = db.prepare(
+      `SELECT trigger_source AS source, count(*) AS c,
+              COALESCE(SUM(total_tokens), 0) AS total_tokens
+       FROM llm_audit_logs WHERE timestamp >= ?
+       GROUP BY trigger_source ORDER BY total_tokens DESC`
+    ).all(since);
+    const byStatus = db.prepare(
+      "SELECT status, count(*) AS c FROM llm_audit_logs WHERE timestamp >= ? GROUP BY status"
+    ).all(since);
+    return {
+      days,
+      since,
+      total_calls: total.c,
+      input_tokens: total.i,
+      output_tokens: total.o,
+      total_tokens: total.t,
+      total_duration_ms: total.d,
+      total_cost_usd: Number(total.cst),
+      by_source: bySource,
+      by_status: byStatus
+    };
+  }
+
+  /** Delete audit rows older than `before` (ISO string). Returns count removed. */
+  function deleteOldLlmAudits(before) {
+    return db.prepare("DELETE FROM llm_audit_logs WHERE timestamp < ?").run(before).changes;
+  }
+
   // --- failure memories ----------------------------------------------------
 
   /**
@@ -1678,6 +1880,11 @@ export function createStore(path) {
     saveRecallEval,
     getRecallEval,
     listRecallEvals,
+    saveLlmAudit,
+    listLlmAudits,
+    countLlmAudits,
+    getLlmAuditStats,
+    deleteOldLlmAudits,
     saveFailure,
     listFailures,
     getFailureStats,