sessionmem 1.3.0 → 1.5.0

package/dist/core/storage/memorySearchRepo.js

@@ -27,6 +27,7 @@ function getSearchStatements(db) {
       embedding, embedding_dim, embedding_version
     FROM memories
     WHERE project_id = @projectId
+      AND (@includeHistory = 1 OR id NOT IN (SELECT memory_id FROM superseded_memories))
       AND (expires_at IS NULL OR expires_at > @now)
       AND (
         importance >= 8
@@ -38,13 +39,15 @@ function getSearchStatements(db) {
       m.id, m.project_id, m.session_id, m.source_adapter, m.kind, m.content,
       m.normalized_content, m.importance, m.author, m.origin_project_id,
       m.access_count, m.created_at, m.updated_at,
-      m.embedding, m.embedding_dim, m.embedding_version
+      m.embedding, m.embedding_dim, m.embedding_version,
+      -bm25(memories_fts) AS lexical_score
     FROM memories_fts
     JOIN memories m ON m.rowid = memories_fts.rowid
     WHERE memories_fts MATCH @match
       AND m.project_id = @projectId
+      AND (@includeHistory = 1 OR m.id NOT IN (SELECT memory_id FROM superseded_memories))
       AND (m.expires_at IS NULL OR m.expires_at > @now)
-    ORDER BY rank
+    ORDER BY rank, m.id
     LIMIT @limit
   `),
     };
@@ -83,34 +86,40 @@ function mapRows(rows) {
         const versionMatch = row.embedding_version === EMBEDDING_VERSION;
         return {
             ...row,
+            lexical_score: row.lexical_score ?? 0,
             embedding: versionMatch ? parsed : null,
         };
     });
 }
-export function searchMemoryCandidates(db, projectId, now = new Date()) {
+export function searchMemoryCandidates(db, projectId, now = new Date(), includeHistory = false) {
     const rows = getSearchStatements(db).searchCandidates.all({
         projectId,
+        includeHistory: Number(includeHistory),
         now: toStorageTimestamp(now),
         recencyCutoff: toStorageTimestamp(new Date(now.getTime() - FALLBACK_RECENCY_DAYS * MS_PER_DAY)),
     });
     return mapRows(rows);
 }
-/**
- * Sanitize query text for FTS5 MATCH syntax.
- * Wraps each non-empty token in double quotes so special characters
- * (colons, hyphens, parentheses, etc.) are treated as literals.
- * Tokens are joined with implicit AND.
- */
+const QUERY_STOP_WORDS = new Set(("a an and are as at be been being but by can could did do does doing for from " +
+    "had has have he her hers herself him himself his how i if in into is it its itself " +
+    "me my myself of on or our ours ourselves she should so than that the their theirs " +
+    "them themselves then there these they this those to too us was we were what when " +
+    "where which who whom why will with would you your yours yourself yourselves " +
+    "s t don doesn didn isn wasn weren won wouldn couldn shouldn").split(" "));
+/** Match any meaningful query term; question grammar must not exclude evidence. */
 function sanitizeFtsQuery(queryText) {
-    return queryText
-        .split(/\s+/)
-        .filter((token) => token.length > 0)
-        .map((token) => `"${token.replace(/"/g, '""')}"`)
-        .join(" ");
+    const tokens = [...new Set(queryText.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [])];
+    const terms = tokens.filter((token) => !QUERY_STOP_WORDS.has(token));
+    // Preserve literal searches consisting entirely of stop words. Tokens contain
+    // only letters/numbers, so FTS operators and punctuation cannot become syntax.
+    return (terms.length ? terms : tokens)
+        .slice(0, 64)
+        .map((token) => `"${token}"`)
+        .join(" OR ");
 }
 /**
- * Pre-filter candidates using FTS5 full-text search before cosine similarity.
- * Returns up to FTS_CANDIDATE_LIMIT candidates.
+ * Retrieve BM25-ranked lexical candidates, including stored summaries.
+ * Returns up to FTS_CANDIDATE_LIMIT matches with deterministic ID tie breaks.
  *
  * FTS keyword overlap can be sparse, so the fallback recency/importance scan is
  * UNIONed with (never substituted for) the FTS hits:
@@ -124,28 +133,29 @@ function sanitizeFtsQuery(queryText) {
  * (<8) — exactly the rows the fallback's filter excludes — returning zero
  * candidates for a query that matched only such rows.
  */
-export function searchMemoryCandidatesFTS(db, projectId, queryText, now = new Date()) {
+export function searchMemoryCandidatesFTS(db, projectId, queryText, now = new Date(), includeHistory = false) {
     const sanitized = sanitizeFtsQuery(queryText);
     if (!sanitized) {
-        return searchMemoryCandidates(db, projectId, now);
+        return searchMemoryCandidates(db, projectId, now, includeHistory);
     }
     let rows;
     try {
         rows = getSearchStatements(db).searchCandidatesFTS.all({
             match: sanitized,
             projectId,
+            includeHistory: Number(includeHistory),
             now: toStorageTimestamp(now),
             limit: FTS_CANDIDATE_LIMIT,
         });
     }
     catch {
         // FTS5 MATCH can throw on malformed queries — fall back to full scan
-        return searchMemoryCandidates(db, projectId, now);
+        return searchMemoryCandidates(db, projectId, now, includeHistory);
     }
     if (rows.length >= FTS_FALLBACK_THRESHOLD) {
         return dedupById(mapRows(rows));
     }
-    const fallback = searchMemoryCandidates(db, projectId, now);
+    const fallback = searchMemoryCandidates(db, projectId, now, includeHistory);
     if (rows.length === 0) {
         return fallback;
     }

package/dist/core/storage/supersessionRepo.js

@@ -0,0 +1,101 @@
+import { claimKey, claimSlot, extractFactClaims, supersessionReason } from "../extract/factClaims.js";
+const toClaim = (row) => ({ source: { kind: row.source_kind, name: row.source_name },
+    type: row.relation, target: { kind: row.target_kind, name: row.target_name }, context: row.context,
+    attribute: row.attribute, negative: !!row.negative, explicitChange: !!row.explicit_change, replaces: row.replaces_value });
+function prepareStatements(db) {
+    return {
+        memory: db.prepare("SELECT project_id, created_at FROM memories WHERE id = ?"),
+        projectGroups: db.prepare(`SELECT DISTINCT c.source_kind, c.source_name, c.relation FROM memory_claims c
+      JOIN memories m ON m.id = c.memory_id WHERE m.project_id = ?`),
+        previous: db.prepare("SELECT * FROM memory_claims WHERE memory_id = ?"),
+        clear: db.prepare("DELETE FROM memory_claims WHERE memory_id = ? AND claim_key NOT IN (SELECT value FROM json_each(?))"),
+        insert: db.prepare(`INSERT INTO memory_claims
+      (memory_id, claim_key, source_kind, source_name, relation, target_kind, target_name, context, attribute, negative, explicit_change, replaces_value, observed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(memory_id, claim_key) DO UPDATE SET negative=excluded.negative,
+        explicit_change=excluded.explicit_change, replaces_value=excluded.replaces_value, observed_at=excluded.observed_at`),
+        select: db.prepare(`SELECT c.*, m.expires_at FROM memory_claims c JOIN memories m ON m.id = c.memory_id
+      WHERE m.project_id = ? AND c.source_kind = ? AND c.source_name = ? AND c.relation = ?
+      ORDER BY c.observed_at, m.rowid, c.claim_key`),
+        remove: db.prepare("DELETE FROM memory_supersessions WHERE supersedes = ? AND claim_key = ?"),
+        link: db.prepare(`INSERT INTO memory_supersessions (supersedes, claim_key, superseded_by, new_claim_key, superseded_at, reason)
+      VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(supersedes, claim_key) DO UPDATE SET
+        superseded_by=excluded.superseded_by, new_claim_key=excluded.new_claim_key, superseded_at=excluded.superseded_at,
+        reason=excluded.reason, detected_at=strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+      WHERE superseded_by <> excluded.superseded_by OR new_claim_key <> excluded.new_claim_key OR superseded_at <> excluded.superseded_at OR reason <> excluded.reason`),
+    };
+}
+const cache = new WeakMap();
+function statements(db) {
+    let stmts = cache.get(db);
+    if (!stmts) {
+        stmts = prepareStatements(db);
+        cache.set(db, stmts);
+    }
+    return stmts;
+}
+/** Reconcile affected entity/relation groups, including out-of-order imports and rewrites. */
+export function indexMemorySupersessions(db, memoryId, content, sources) {
+    const stmts = statements(db);
+    const memory = stmts.memory.get(memoryId);
+    const previous = stmts.previous.all(memoryId);
+    const finalClaims = new Map();
+    for (const source of sources ?? [{ text: content, observedAt: memory.created_at }]) {
+        for (const claim of extractFactClaims(source.text))
+            finalClaims.set(claimSlot(claim), { ...claim, observedAt: source.observedAt });
+    }
+    const claims = [...finalClaims.values()];
+    const groups = new Map();
+    for (const row of previous)
+        groups.set(JSON.stringify([row.source_kind, row.source_name, row.relation]), [row.source_kind, row.source_name, row.relation]);
+    const keys = claims.map(claimKey);
+    // Preserve identical claims and links on replays (including detected_at).
+    stmts.clear.run(memoryId, JSON.stringify(keys));
+    for (const claim of claims) {
+        const group = [claim.source.kind, claim.source.name, claim.type];
+        groups.set(JSON.stringify(group), group);
+        stmts.insert.run(memoryId, claimKey(claim), ...group, claim.target.kind, claim.target.name, claim.context, claim.attribute, Number(claim.negative), Number(claim.explicitChange), claim.replaces, claim.observedAt);
+    }
+    reconcileGroups(db, memory.project_id, [...groups.values()]);
+}
+/** Deleting an intermediate replacement must not revive an older contradicted fact. */
+export function reconcileProjectSupersessions(db, projectId) {
+    const groups = statements(db).projectGroups.all(projectId);
+    reconcileGroups(db, projectId, groups.map(row => [row.source_kind, row.source_name, row.relation]));
+}
+function reconcileGroups(db, projectId, groups) {
+    const stmts = statements(db);
+    for (const group of groups) {
+        const rows = stmts.select.all(projectId, ...group);
+        for (let i = 0; i < rows.length; i++) {
+            const older = rows[i];
+            let found = false;
+            for (let j = i + 1; j < rows.length; j++) {
+                const newer = rows[j];
+                if (older.memory_id === newer.memory_id || (older.expires_at && older.expires_at <= newer.observed_at)
+                    || (newer.expires_at && newer.expires_at <= newer.observed_at))
+                    continue;
+                const reason = supersessionReason(toClaim(older), toClaim(newer));
+                if (!reason)
+                    continue;
+                stmts.link.run(older.memory_id, older.claim_key, newer.memory_id, newer.claim_key, newer.observed_at, reason);
+                found = true;
+                break;
+            }
+            if (!found)
+                stmts.remove.run(older.memory_id, older.claim_key);
+        }
+    }
+}
+export function listSupersessions(db, projectId) {
+    return db.prepare(`SELECT s.supersedes, s.superseded_by AS supersededBy, s.superseded_at AS supersededAt,
+    s.detected_at AS detectedAt, s.reason, c.source_name AS entity, c.relation,
+    CASE WHEN c.negative THEN 'not ' ELSE '' END || c.target_name AS oldValue,
+    CASE WHEN n.negative THEN 'not ' ELSE '' END || n.target_name AS newValue,
+    EXISTS (SELECT 1 FROM superseded_memories f WHERE f.memory_id = s.supersedes) AS fullySuperseded
+    FROM memory_supersessions s JOIN memories m ON m.id = s.supersedes
+    JOIN memory_claims c ON c.memory_id = s.supersedes AND c.claim_key = s.claim_key
+    JOIN memory_claims n ON n.memory_id = s.superseded_by AND n.claim_key = s.new_claim_key
+    WHERE m.project_id = ? ORDER BY s.superseded_at, s.supersedes, s.superseded_by, s.claim_key`)
+        .all(projectId).map(row => ({ ...row, fullySuperseded: !!row.fullySuperseded }));
+}

package/dist/core/summarize/cloudSummarizer.js

@@ -1,4 +1,5 @@
 import Anthropic from "@anthropic-ai/sdk";
+import { capTokens } from "../injection/tokenBudget.js";
 import { summarizeLocalSessionEvents } from "./localSummarizer.js";
 import { DEFAULT_SUMMARIZER_MODEL } from "../config/policyConfig.js";
 const CLOUD_SYSTEM_PROMPT = "You are a memory compressor for AI coding sessions. Given this session transcript summary, produce a compact, high-signal list of facts, decisions, and context that should be remembered. Be extremely concise.";
@@ -26,7 +27,7 @@ export async function summarizeWithCloud(input) {
         messages: [{ role: "user", content: localResult.summary }],
     });
     // Extract text from response content blocks
-    let text = response.content
+    const text = response.content
         .filter((block) => block.type === "text")
         .map((block) => block.text)
         .join("\n");
@@ -35,14 +36,8 @@ export async function summarizeWithCloud(input) {
     if (!text || text.trim().length === 0) {
         throw new Error("Cloud summarizer returned empty response");
     }
-    // Cap cloud output to summaryTokenCap (rough token→char ratio) for parity
-    // with the local summarizer, so a verbose cloud response cannot blow past the
-    // configured budget.
-    if (input.summaryTokenCap && text.length > input.summaryTokenCap * 4) {
-        text = text.slice(0, input.summaryTokenCap * 4);
-    }
     return {
-        summary: text,
+        summary: capTokens(text, input.summaryTokenCap),
         warningCodes: localResult.warningCodes,
     };
 }

package/dist/core/summarize/summaryShape.js

@@ -7,7 +7,7 @@ const MAX_FACT_LINES = 8;
  * carrying a one-line description ("Ran: npm test", "Edited src/foo.ts"); fall
  * back to the raw payload for events written by other producers.
  */
-function extractEventText(event) {
+export function extractEventText(event) {
     try {
         const parsed = JSON.parse(event.payload_json);
         if (typeof parsed.text === "string" && parsed.text.trim().length > 0) {

package/dist/ui/assets.js

@@ -0,0 +1,181 @@
+// Bundled as JavaScript strings so the existing tsc build and npm package include every asset.
+export const HTML = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>sessionmem · Memory viewer</title><link rel="stylesheet" href="/style.css"><script src="/app.js" defer></script></head>
+<body><header><div class="brand"><span class="mark" aria-hidden="true">s</span><div><strong>sessionmem</strong><span class="muted">Memory viewer</span></div></div><span class="badge">Local · Read-only</span></header>
+<main><div class="intro"><div><p class="eyebrow">YOUR PROJECT CONTEXT</p><h1>What sessionmem knows</h1><p class="muted">Explore saved context, connections, and how facts changed.</p></div><label class="project-label">Project<select id="project" aria-label="Project"></select></label></div>
+<nav aria-label="Views"><button type="button" data-view="memories" aria-pressed="true">Memories</button><button type="button" data-view="entities" aria-pressed="false">Entities &amp; relations</button><button type="button" data-view="history" aria-pressed="false">Supersession chains</button></nav>
+<form id="search"><label for="query">Search memories</label><div class="search-row"><input id="query" type="search" maxlength="1000" placeholder="Search decisions, facts, warnings…"><button type="submit" class="primary">Search</button></div><label class="check"><input id="include-history" type="checkbox"> Include superseded facts in search</label></form>
+<div class="section-heading"><h2 id="view-title">Memories</h2><button type="button" id="refresh">Refresh</button></div><p id="status" role="status" aria-live="polite">Loading your memory store…</p><div id="results"></div>
+<div id="pagination"><button id="previous" type="button">← Previous</button><span id="page-info"></span><button id="next" type="button">Next →</button></div>
+<footer>Served from this computer. Browsing and searching do not change your memories.</footer></main>
+<dialog id="detail"><div class="section-heading"><h2>Memory details</h2><button id="close-detail" type="button">Close</button></div><div id="detail-content"></div></dialog></body></html>`;
+export const CSS = `
+:root{color-scheme:light;--ink:#202b33;--muted:#626f78;--line:#dce3e5;--accent:#176c58;--pale:#eaf4ef;font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#f6f8f7;color:var(--ink)}
+*{box-sizing:border-box}body{margin:0;font-size:15px;line-height:1.6}header{background:#fff;border-bottom:1px solid var(--line);padding:18px max(24px,calc((100vw - 1160px)/2));display:flex;align-items:center;justify-content:space-between;gap:16px}.brand{display:flex;align-items:center;gap:12px}.brand strong{font-size:20px;letter-spacing:-.7px}.brand .muted{margin-left:14px;font-size:13px}.mark{display:grid;place-items:center;background:var(--accent);color:#fff;border-radius:10px;width:36px;height:36px;font:bold 28px Georgia,serif}.badge{background:var(--pale);color:#215e4d;border:1px solid #cae2d5;border-radius:20px;padding:4px 12px;font-size:12px;white-space:nowrap}main{max-width:1160px;margin:auto;padding:36px 24px}.intro{display:flex;justify-content:space-between;align-items:center;gap:24px;margin-bottom:28px}h1{font-size:32px;line-height:1.2;letter-spacing:-1.1px;margin:4px 0 12px}h2{font-size:19px;margin:0}h3{font-size:16px;margin:0 0 14px}.eyebrow{font-size:11px;font-weight:700;letter-spacing:1.6px;color:var(--accent);margin:0}.muted{color:var(--muted)}p{margin:6px 0}.project-label{font-size:12px;font-weight:600;display:grid;gap:6px;min-width:240px;max-width:40%}select,input[type=search]{background:#fff;border:1px solid #b8c5c7;border-radius:7px;padding:10px 12px;color:var(--ink);font:inherit;width:100%}nav{display:flex;gap:8px;border-bottom:1px solid var(--line);padding-bottom:12px;margin-bottom:24px;flex-wrap:wrap}button{font:inherit;cursor:pointer;color:var(--ink);background:#fff;border:1px solid var(--line);border-radius:7px;padding:7px 13px}button:hover{border-color:var(--accent);background:#f1f7f4}button[aria-pressed=true],.primary{background:var(--accent);border-color:var(--accent);color:#fff}button:disabled{opacity:.45;cursor:default}button:focus-visible,input:focus-visible,select:focus-visible{outline:3px solid #73b6a1;outline-offset:3px}#search>label:first-child{font-size:13px;font-weight:600}.search-row{display:flex;gap:10px;margin:7px 0 10px}.check{display:flex;align-items:center;gap:7px;font-size:13px;color:var(--muted)}.section-heading{display:flex;align-items:center;justify-content:space-between;gap:12px;margin:26px 0 12px}#status{font-size:13px;color:var(--muted);margin-bottom:18px}#status.error{color:#a43327}#results{display:grid;gap:14px}.card{background:#fff;border:1px solid var(--line);border-radius:10px;padding:20px}.card-top{display:flex;gap:8px;align-items:center;flex-wrap:wrap;margin-bottom:10px}.kind{font-size:11px;font-weight:700;text-transform:uppercase;letter-spacing:.6px;color:var(--accent);background:var(--pale);padding:2px 8px;border-radius:4px}.meta{font-size:12px;color:var(--muted)}.content{white-space:pre-wrap;overflow-wrap:anywhere;margin:10px 0 16px}.memory-link{font:12px ui-monospace,SFMono-Regular,Consolas,monospace;color:var(--accent);padding:4px 7px;overflow-wrap:anywhere;max-width:100%;text-align:left}.source-links{display:flex;gap:6px;flex-wrap:wrap;margin-top:8px}.columns{display:grid;grid-template-columns:1fr 1.4fr;gap:18px}.row{padding:14px 0;border-top:1px solid var(--line);overflow-wrap:anywhere}.row:first-child{border:0}.relation{color:var(--accent);font-size:12px;font-weight:600;margin:0 8px}.timeline{border-left:2px solid #c7ddd3;margin-left:6px;padding-left:20px}.transition{position:relative;padding:0 0 24px;overflow-wrap:anywhere}.transition:before{content:"";position:absolute;left:-26px;top:8px;width:9px;height:9px;border-radius:50%;background:var(--accent);border:1px solid #fff}.values{font-size:17px;margin:8px 0}.arrow{color:var(--accent);margin:0 10px}.empty{text-align:center;padding:48px 24px;background:#fff;border:1px dashed #c4d0cd;border-radius:10px;color:var(--muted)}#pagination{display:flex;align-items:center;justify-content:center;gap:20px;margin:24px 0}footer{text-align:center;font-size:12px;color:var(--muted);margin-top:42px}dialog{max-width:800px;width:calc(100% - 32px);max-height:85vh;border:1px solid var(--line);border-radius:12px;padding:24px;color:var(--ink)}dialog::backdrop{background:#152a2780}dialog .section-heading{margin-top:0}dl{display:grid;grid-template-columns:110px 1fr;gap:6px 12px;font-size:13px}dt{color:var(--muted)}dd{margin:0;overflow-wrap:anywhere}[hidden]{display:none!important}
+@media(max-width:700px){header{padding:16px}.brand .muted{display:none}main{padding:24px 16px}.intro{align-items:stretch;flex-direction:column;gap:16px}.project-label{max-width:100%;min-width:0}.columns{grid-template-columns:1fr}h1{font-size:28px}.card{padding:16px}nav button{font-size:13px}}
+`;
+export const JS = String.raw `
+'use strict';
+const $ = (id) => document.getElementById(id);
+const state = { project: '', view: 'memories', query: '', offset: 0, generation: 0 };
+const titles = { memories: 'Memories', entities: 'Entities & relations', history: 'Supersession chains' };
+function el(tag, text, className) {
+  const node = document.createElement(tag);
+  if (text !== undefined) node.textContent = text;
+  if (className) node.className = className;
+  return node;
+}
+function timestamp(value) {
+  if (!value) return 'Unknown';
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString();
+}
+async function api(path, params = {}) {
+  const url = new URL('/api/' + path, location.origin);
+  url.search = new URLSearchParams({ ...(state.project ? { project: state.project } : {}), ...params });
+  const response = await fetch(url, { cache: 'no-store' });
+  const result = await response.json();
+  if (!response.ok) throw new Error(result.error || 'Unable to load the memory store');
+  return result;
+}
+function source(id) {
+  const button = el('button', id, 'memory-link');
+  button.type = 'button';
+  button.title = 'Inspect source memory';
+  button.addEventListener('click', () => showMemory(id));
+  return button;
+}
+function sources(ids) {
+  const wrapper = el('div', undefined, 'source-links');
+  ids.forEach(id => wrapper.append(source(id)));
+  return wrapper;
+}
+async function showMemory(id) {
+  const project = state.project;
+  $('detail-content').textContent = 'Loading…';
+  if (!$('detail').open) $('detail').showModal();
+  try {
+    const { memory } = await api('memory', { id });
+    if (project !== state.project) return;
+    $('detail-content').replaceChildren(el('div', memory.content, 'content'));
+    const details = el('dl');
+    for (const key of ['id', 'kind', 'importance', 'author', 'sessionId', 'sourceAdapter', 'createdAt', 'updatedAt', 'expiresAt']) {
+      if (memory[key] != null) details.append(el('dt', key), el('dd', String(memory[key])));
+    }
+    $('detail-content').append(details);
+  } catch (error) { $('detail-content').textContent = error.message; }
+}
+function renderMemories(data) {
+  for (const memory of data.memories) {
+    const card = el('article', undefined, 'card');
+    const top = el('div', undefined, 'card-top');
+    top.append(el('span', memory.kind, 'kind'), el('span', 'Importance ' + memory.importance + '/10', 'meta'));
+    if (memory.score) top.append(el('span', 'Recall score ' + memory.score.total.toFixed(3), 'meta'));
+    card.append(top, el('div', memory.content, 'content'), source(memory.id), el('p', 'Updated ' + timestamp(memory.updatedAt) + (memory.author ? ' · ' + memory.author : ''), 'meta'));
+    if (memory.expiresAt) card.append(el('p', 'Expires ' + timestamp(memory.expiresAt), 'meta'));
+    $('results').append(card);
+  }
+  if (!data.memories.length) empty(state.query ? 'No matching memories.' : 'No memories in this project yet.');
+  $('status').textContent = state.query ? data.total + ' recall results · current facts by default · showing up to 50' : data.total + ' saved memories · includes superseded and expired records';
+  $('pagination').hidden = !!state.query || data.total === 0;
+  $('previous').disabled = state.offset === 0;
+  $('next').disabled = state.offset + 50 >= data.total;
+  $('page-info').textContent = (state.offset + 1) + '–' + Math.min(state.offset + 50, data.total) + ' of ' + data.total;
+}
+function empty(message) { $('results').append(el('div', message, 'empty')); }
+function renderKnowledge(data) {
+  $('status').textContent = data.entities.length + ' entities · ' + data.relations.length + ' relations · source IDs open memory details';
+  if (!data.entities.length && !data.relations.length) { empty('No entities or relations captured for this project.'); return; }
+  const columns = el('div', undefined, 'columns');
+  for (const [title, rows] of [['Entities', data.entities], ['Relations', data.relations]]) {
+    const panel = el('section', undefined, 'card');
+    panel.append(el('h3', title));
+    for (const row of rows) {
+      const item = el('div', undefined, 'row');
+      if (title === 'Entities') item.append(el('span', row.kind, 'kind'), el('p', row.name));
+      else item.append(el('span', row.sourceName), el('span', row.relation + ' →', 'relation'), el('span', row.targetName), el('p', row.sourceKind + ' → ' + row.targetKind, 'meta'));
+      item.append(sources(row.memoryIds));
+      panel.append(item);
+    }
+    if (!rows.length) panel.append(el('p', 'None captured.', 'muted'));
+    columns.append(panel);
+  }
+  $('results').append(columns);
+}
+function renderHistory(data) {
+  $('status').textContent = data.links.length + ' replacement links · ordered by assertion time · source IDs open memory details';
+  if (!data.links.length) { empty('No supersession chains captured for this project.'); return; }
+  const groups = new Map();
+  for (const link of data.links) {
+    const key = JSON.stringify([link.entity, link.relation]);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(link);
+  }
+  for (const links of groups.values()) {
+    const card = el('section', undefined, 'card');
+    card.append(el('h3', links[0].entity + ' · ' + links[0].relation));
+    const timeline = el('div', undefined, 'timeline');
+    for (const link of links) {
+      const item = el('article', undefined, 'transition');
+      item.append(el('div', timestamp(link.supersededAt), 'meta'));
+      const values = el('div', undefined, 'values');
+      values.append(el('span', link.oldValue), el('span', '→', 'arrow'), el('strong', link.newValue));
+      item.append(values);
+      const refs = el('div', undefined, 'source-links');
+      refs.append(source(link.supersedes), el('span', '→', 'arrow'), source(link.supersededBy));
+      item.append(refs, el('p', (link.fullySuperseded ? 'Fully superseded' : 'Partially superseded') + ' · ' + link.reason.replaceAll('_', ' '), 'meta'), el('p', 'Detected ' + timestamp(link.detectedAt), 'meta'));
+      timeline.append(item);
+    }
+    card.append(timeline);
+    $('results').append(card);
+  }
+}
+async function load() {
+  const generation = ++state.generation;
+  $('view-title').textContent = titles[state.view];
+  $('search').hidden = state.view !== 'memories';
+  $('pagination').hidden = true;
+  $('results').replaceChildren();
+  $('status').className = '';
+  $('status').textContent = 'Loading…';
+  try {
+    const data = await api(state.view === 'entities' ? 'entities' : state.view === 'history' ? 'history' : 'memories', { q: state.query, offset: String(state.offset), history: String($('include-history').checked) });
+    if (generation !== state.generation) return;
+    if (state.view === 'memories') renderMemories(data);
+    else if (state.view === 'entities') renderKnowledge(data);
+    else renderHistory(data);
+  } catch (error) {
+    if (generation !== state.generation) return;
+    $('status').className = 'error';
+    $('status').textContent = error.message;
+  }
+}
+document.querySelectorAll('[data-view]').forEach(button => button.addEventListener('click', () => {
+  state.view = button.dataset.view;
+  document.querySelectorAll('[data-view]').forEach(other => other.setAttribute('aria-pressed', String(other === button)));
+  load();
+}));
+$('project').addEventListener('change', () => { state.project = $('project').value; state.offset = 0; $('detail').close(); load(); });
+$('search').addEventListener('submit', event => { event.preventDefault(); state.query = $('query').value.trim(); state.offset = 0; load(); });
+$('query').addEventListener('input', () => { if (!$('query').value && state.query) { state.query = ''; state.offset = 0; load(); } });
+$('include-history').addEventListener('change', () => { if (state.query) load(); });
+$('refresh').addEventListener('click', load);
+$('previous').addEventListener('click', () => { state.offset = Math.max(0, state.offset - 50); load(); });
+$('next').addEventListener('click', () => { state.offset += 50; load(); });
+$('close-detail').addEventListener('click', () => $('detail').close());
+(async () => {
+  try {
+    const data = await api('projects');
+    state.project = data.defaultProjectId;
+    if (!data.projects.some(project => project.id === state.project)) data.projects.unshift({ id: state.project, count: 0 });
+    for (const project of data.projects) {
+      const option = el('option', project.id + ' (' + project.count + ')');
+      option.value = project.id;
+      $('project').append(option);
+    }
+    $('project').value = state.project;
+    await load();
+  } catch (error) { $('status').className = 'error'; $('status').textContent = error.message; }
+})();
+`;

package/dist/ui/server.js

@@ -0,0 +1,147 @@
+import { createServer } from "node:http";
+import { listProjectKnowledge } from "../core/storage/knowledgeRepo.js";
+import { listSupersessions } from "../core/storage/supersessionRepo.js";
+import { HTML, CSS, JS } from "./assets.js";
+export const DEFAULT_UI_PORT = 3777;
+export function parseUiPort(value = DEFAULT_UI_PORT) {
+    const port = Number(value);
+    if (!/^\d+$/.test(String(value)) || !Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error("--port must be an integer from 0 to 65535 (0 selects a free port)");
+    }
+    return port;
+}
+function json(response, status, value) {
+    response.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+    response.end(JSON.stringify(value));
+}
+function integer(value, fallback, max) {
+    if (value === null)
+        return fallback;
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) > max) {
+        throw new Error("Invalid pagination parameter");
+    }
+    return Number(value);
+}
+/** Fixed read routes only: never dispatch a caller-supplied service method. */
+export async function startUiServer(context, port = DEFAULT_UI_PORT) {
+    parseUiPort(port);
+    let origin = "";
+    const server = createServer(async (request, response) => {
+        response.setHeader("Cache-Control", "no-store");
+        response.setHeader("X-Content-Type-Options", "nosniff");
+        response.setHeader("Referrer-Policy", "no-referrer");
+        response.setHeader("Content-Security-Policy", "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'");
+        if (request.method !== "GET" && request.method !== "HEAD") {
+            response.setHeader("Allow", "GET, HEAD");
+            json(response, 405, { error: "Read-only viewer: method not allowed" });
+            return;
+        }
+        // Block DNS rebinding and cross-origin browser reads of the unauthenticated store.
+        if (request.headers.host !== new URL(origin).host
+            || (request.headers.origin && request.headers.origin !== origin)
+            || request.headers["sec-fetch-site"] === "cross-site") {
+            json(response, 403, { error: "Local origin required" });
+            return;
+        }
+        try {
+            const url = new URL(request.url ?? "/", origin);
+            if (url.origin !== origin) {
+                json(response, 403, { error: "Local origin required" });
+                return;
+            }
+            const assets = {
+                "/": ["text/html", HTML], "/style.css": ["text/css", CSS], "/app.js": ["text/javascript", JS],
+            };
+            const asset = Object.hasOwn(assets, url.pathname) ? assets[url.pathname] : undefined;
+            if (asset) {
+                response.writeHead(200, { "Content-Type": `${asset[0]}; charset=utf-8` });
+                response.end(request.method === "HEAD" ? undefined : asset[1]);
+                return;
+            }
+            const params = url.searchParams;
+            const projectId = params.get("project") ?? context.projectId;
+            if (!projectId || projectId.length > 2000)
+                throw new Error("Invalid project ID");
+            switch (url.pathname) {
+                case "/api/projects": {
+                    const projects = context.db.prepare(`SELECT project_id AS id, COUNT(*) AS count
+            FROM memories GROUP BY project_id ORDER BY project_id`).all();
+                    json(response, 200, { defaultProjectId: context.projectId, projects });
+                    break;
+                }
+                case "/api/memories": {
+                    const query = params.get("q")?.trim();
+                    const limit = integer(params.get("limit"), 50, 100);
+                    if (!limit)
+                        throw new Error("Limit must be at least 1");
+                    if (query) {
+                        if (query.length > 1000)
+                            throw new Error("Query must be at most 1000 characters");
+                        const result = await context.service.call("retrieveMemories", {
+                            projectId, query, limit, mode: "on-demand", depth: "default",
+                            includeHistory: params.get("history") === "true",
+                        });
+                        if (!result.ok) {
+                            json(response, 400, { error: result.error.message });
+                            break;
+                        }
+                        json(response, 200, { memories: result.memories, total: result.total });
+                    }
+                    else {
+                        const offset = integer(params.get("offset"), 0, Number.MAX_SAFE_INTEGER);
+                        const memories = context.db.prepare(`SELECT id, kind, content, importance, author,
+              created_at AS createdAt, updated_at AS updatedAt, expires_at AS expiresAt
+              FROM memories WHERE project_id = ? ORDER BY updated_at DESC, id LIMIT ? OFFSET ?`)
+                            .all(projectId, limit, offset);
+                        const { total } = context.db.prepare("SELECT COUNT(*) AS total FROM memories WHERE project_id = ?")
+                            .get(projectId);
+                        json(response, 200, { memories, total });
+                    }
+                    break;
+                }
+                case "/api/memory": {
+                    const id = params.get("id");
+                    if (!id || id.length > 200)
+                        throw new Error("Invalid memory ID");
+                    const result = await context.service.call("getMemory", { projectId, memoryId: id });
+                    json(response, result.ok ? 200 : 404, result.ok ? { memory: result.memory } : { error: result.error.message });
+                    break;
+                }
+                case "/api/entities":
+                    json(response, 200, listProjectKnowledge(context.db, projectId));
+                    break;
+                case "/api/history":
+                    json(response, 200, { links: listSupersessions(context.db, projectId) });
+                    break;
+                default:
+                    json(response, 404, { error: "Not found" });
+            }
+        }
+        catch (error) {
+            // Do not send database paths or raw SQL errors to the browser.
+            const invalid = error instanceof Error && /^(Invalid |Limit must|Query must)/.test(error.message);
+            json(response, invalid ? 400 : 500, { error: invalid ? error.message : "Unable to read the memory store" });
+        }
+    });
+    // Bound incomplete requests and idle clients; close() also terminates open connections.
+    server.requestTimeout = 10000;
+    server.headersTimeout = 10000;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            server.removeListener("error", reject);
+            const address = server.address();
+            if (!address || typeof address === "string")
+                throw new Error("Missing HTTP address");
+            origin = `http://127.0.0.1:${address.port}`;
+            resolve();
+        });
+    });
+    return {
+        server, url: `${origin}/`,
+        close: () => new Promise((resolve, reject) => {
+            server.close(error => error ? reject(error) : resolve());
+            server.closeAllConnections();
+        }),
+    };
+}