open-memex 0.7.0-alpha.8 → 0.7.0

package/dist/inventory-html.js

@@ -0,0 +1,150 @@
+/**
+ * HTML renderer for the inventory (D68 follow-up): a single local file
+ * a user opens in any browser to read what the store remembers. It
+ * renders the SAME data layer as the text/JSON formats
+ * (`src/inventory.ts`) — one source, three renderings, no drift.
+ *
+ * Design rules (3-C v2) enforced here:
+ * - Every byte of memory content is HTML-escaped. Memory text can come
+ *   from an imported bundle or a pasted web page; under file:// an
+ *   unescaped <script> would execute in the user's own browser.
+ * - The filter box is plain show/hide over server-rendered entries
+ *   (no innerHTML, no network, no external resources).
+ * - History (superseded versions, retracted, archived) is a folded
+ *   section with supersede-chain pointers — auditable, never mixed
+ *   into "what is remembered now". At scale (>50 current entries) the
+ *   scope sections fold too.
+ * - Read-only: no delete buttons, no server callback. Deletion stays a
+ *   confirmed conversation; the page says so, with the id to quote.
+ */
+import path from "node:path";
+import { PERSONAL_SCOPE } from "./scope.js";
+import { escapeHtml, relativeTime, reviewStateLabel, sourceLabel, } from "./retrieve/display.js";
+const FOLD_THRESHOLD = 50;
+function entryHtml(row, now) {
+    const meta = [escapeHtml(sourceLabel(row.source))];
+    const when = relativeTime(row.created_at, now);
+    if (when)
+        meta.push(escapeHtml(when));
+    if (row.scope_key !== PERSONAL_SCOPE.key) {
+        meta.push(escapeHtml(reviewStateLabel(row.review_state)));
+        if (row.review_state !== "draft") {
+            meta.push(row.file_path.replace(/\\/g, "/").includes("/.ai/open-memex/")
+                ? "file is in the repo"
+                : "file is not in the repo yet");
+        }
+    }
+    if (row.status !== "active")
+        meta.push(escapeHtml(`marked ${row.status}`));
+    return `    <article class="entry">
+      <p class="body">${escapeHtml(row.content.trim())}</p>
+      <p class="meta">${meta.join(" · ")} · <span class="id">id ${escapeHtml(row.id)}</span></p>
+    </article>`;
+}
+function hiddenEntryHtml(row, now) {
+    const when = relativeTime(row.created_at, now);
+    const chain = row.superseded_by
+        ? ` · replaced by <span class="id">${escapeHtml(row.superseded_by)}</span>`
+        : "";
+    return `    <article class="entry hidden-entry">
+      <p class="body">${escapeHtml(row.content.trim())}</p>
+      <p class="meta">${escapeHtml(row.status)}${when ? ` · saved ${escapeHtml(when)}` : ""}${chain} · <span class="id">id ${escapeHtml(row.id)}</span></p>
+    </article>`;
+}
+function sectionHtml(title, blurb, entries, count, fold, open) {
+    if (fold) {
+        return `  <details${open ? " open" : ""}>
+    <summary>${escapeHtml(title)} <span class="count">${count}</span></summary>
+    <p class="blurb">${escapeHtml(blurb)}</p>
+${entries}
+  </details>`;
+    }
+    return `  <section>
+    <h2>${escapeHtml(title)} <span class="count">${count}</span></h2>
+    <p class="blurb">${escapeHtml(blurb)}</p>
+${entries || '    <p class="empty">(nothing here yet)</p>'}
+  </section>`;
+}
+export function renderInventoryHtml(data) {
+    const now = Date.now();
+    const fold = data.total > FOLD_THRESHOLD;
+    const personalCount = data.scopes
+        .filter((s) => s.scopeKey === PERSONAL_SCOPE.key)
+        .reduce((n, s) => n + s.rows.length, 0);
+    const parts = [];
+    data.scopes.forEach((s, i) => {
+        const isPersonal = s.scopeKey === PERSONAL_SCOPE.key;
+        parts.push(sectionHtml(isPersonal ? "About you — personal" : `Project: ${s.projectName}`, isPersonal
+            ? "These describe you, apply in every project, and never leave this machine."
+            : "Project memories. Each entry says whether it is still only on this machine (the outbox) or has reached the repo.", s.rows.map((r) => entryHtml(r, now)).join("\n"), s.rows.length, fold, isPersonal || i === 0));
+    });
+    if (data.outbox.length > 0) {
+        parts.push(sectionHtml("Not in the repo yet — outbox drafts", "These drafts exist only on this machine. They reach the repo through review (submit → promote), never automatically.", data.outbox.map((r) => entryHtml(r, now)).join("\n"), data.outbox.length, fold, false));
+    }
+    if (data.hiddenEntries.length > 0) {
+        const h = data.hiddenEntries.map((r) => hiddenEntryHtml(r, now)).join("\n");
+        parts.push(`  <details>
+    <summary>Replaced &amp; hidden history <span class="count">${data.hiddenEntries.length}</span></summary>
+    <p class="blurb">Older versions and withdrawn memories. Kept so you can audit how a fact changed; none of this is used for recall.</p>
+${h}
+  </details>`);
+    }
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<!-- D70: the page claims it makes no network requests - enforce it. Inline
+     style/script are the only allowances; anything else (a stray <img
+     src>, a remote font) is blocked by the browser, not just by our promise. -->
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'">
+<title>What OpenMemex remembers</title>
+<style>
+  body { font-family: system-ui, sans-serif; margin: 2rem auto; max-width: 44rem; padding: 0 1rem; color: #1a1a1a; background: #fdfdfb; }
+  h1 { font-size: 1.4rem; margin-bottom: 0.25rem; }
+  h2, summary { font-size: 1.1rem; font-weight: 600; }
+  summary { cursor: pointer; margin: 1.2rem 0 0.4rem; }
+  .sub { color: #666; font-size: 0.9rem; margin-top: 0; }
+  .count { color: #888; font-weight: normal; font-size: 0.85em; }
+  .blurb { color: #555; font-size: 0.9rem; }
+  .entry { border-top: 1px solid #e5e2d9; padding: 0.75rem 0; }
+  .hidden-entry { opacity: 0.75; }
+  .body { white-space: pre-wrap; margin: 0 0 0.35rem; }
+  .meta { color: #666; font-size: 0.82rem; margin: 0; }
+  .id { font-family: ui-monospace, monospace; font-size: 0.78rem; }
+  .empty { color: #888; }
+  .howto { background: #f4f1e8; border-radius: 6px; padding: 0.75rem 1rem; font-size: 0.9rem; }
+  input[type="search"] { width: 100%; padding: 0.5rem; font-size: 1rem; margin: 1rem 0; box-sizing: border-box; }
+  .hidden { display: none; }
+</style>
+</head>
+<body>
+<h1>What OpenMemex remembers about you</h1>
+<p class="sub">Generated ${escapeHtml(data.generatedAt)} · ${data.total} memories (${personalCount} personal, ${data.total - personalCount} project incl. outbox). Read-only report.</p>
+<input type="search" id="filter" placeholder="Filter memories…" aria-label="Filter memories">
+<div class="howto">
+  <strong>Checking my work:</strong> every entry shows where it came from.
+  “I inferred this” means I wrote it from context, not from your words — those are the ones to check.
+  To remove one, tell your agent <em>“forget the memory about …”</em> (quote the id if you like) and it will read the entry back before deleting it — deletion is permanent, there is no undo.
+  A memory that lives in a repo is only truly gone once the deletion is committed.
+</div>
+${parts.join("\n")}
+<script>
+  var input = document.getElementById('filter');
+  input.addEventListener('input', function () {
+    var q = input.value.trim().toLowerCase();
+    var entries = document.querySelectorAll('.entry');
+    for (var i = 0; i < entries.length; i++) {
+      var el = entries[i];
+      el.classList.toggle('hidden', q !== '' && el.textContent.toLowerCase().indexOf(q) === -1);
+    }
+  });
+</script>
+</body>
+</html>
+`;
+}
+/** Default report location: the data dir, never a working tree. */
+export function defaultHtmlOutPath(dataRoot) {
+    return path.join(dataRoot, "inventory.html");
+}

package/dist/inventory.js

@@ -0,0 +1,176 @@
+/**
+ * `open-memex inventory` (D68): what the store remembers, in the open.
+ * One data layer, three renderers (text / json / html). The HTML
+ * renderer lives in inventory-html.ts; this module owns the data and
+ * the two renderers an agent or a terminal consumes directly.
+ *
+ * Design rules (3-C v2) enforced here:
+ * - Default scope is personal + the current project — "can't see it"
+ *   is the disease this surface treats.
+ * - Nothing truncates silently: every section states its totals, and
+ *   hidden history (superseded versions, retracted, archived) is
+ *   counted and pointed at, never just omitted.
+ * - Drafts that have not reached the repo (the outbox) are their own
+ *   section, consistent with what memory_status reports.
+ * - The report is read-only. Deleting stays a confirmed conversation.
+ */
+import { db } from "./store/db.js";
+import { PERSONAL_SCOPE } from "./scope.js";
+import { formatInventoryLine } from "./retrieve/display.js";
+const BASE_COLS = `id, scope_key, project_name, type, status, review_state,
+  source, created_at, updated_at, content, file_path`;
+/**
+ * Load the inventory for the given scopes. `projectScopeKey` separates the
+ * outbox drafts (they belong to that scope's draft rows).
+ *
+ * D70: `hidden: "entries"` fetches the hidden rows themselves (HTML audit
+ * view); the default keeps the cheap COUNT query, because pulling every
+ * superseded body for a text report nobody reads is pure waste.
+ */
+export function loadInventory(scopeKeys, opts = {}) {
+    const inList = scopeKeys.map(() => "?").join(",");
+    const current = db()
+        .prepare(`SELECT ${BASE_COLS} FROM memories
+       WHERE scope_key IN (${inList}) AND status IN ('active', 'deprecated')
+       ORDER BY scope_key, updated_at DESC`)
+        .all(...scopeKeys);
+    const hiddenEntries = opts.hidden === "entries"
+        ? db()
+            .prepare(`SELECT ${BASE_COLS}, superseded_by FROM memories
+             WHERE scope_key IN (${inList}) AND status IN ('superseded', 'retracted', 'archived')
+             ORDER BY updated_at DESC`)
+            .all(...scopeKeys)
+        : [];
+    const hidden = { superseded: 0, retracted: 0, archived: 0 };
+    if (hiddenEntries.length > 0) {
+        for (const r of hiddenEntries) {
+            if (r.status === "superseded")
+                hidden.superseded++;
+            if (r.status === "retracted")
+                hidden.retracted++;
+            if (r.status === "archived")
+                hidden.archived++;
+        }
+    }
+    else {
+        const counted = db()
+            .prepare(`SELECT status, COUNT(*) AS n FROM memories
+         WHERE scope_key IN (${inList}) AND status IN ('superseded', 'retracted', 'archived')
+         GROUP BY status`)
+            .all(...scopeKeys);
+        for (const r of counted) {
+            if (r.status === "superseded")
+                hidden.superseded = r.n;
+            if (r.status === "retracted")
+                hidden.retracted = r.n;
+            if (r.status === "archived")
+                hidden.archived = r.n;
+        }
+    }
+    const outbox = current.filter((r) => r.scope_key !== PERSONAL_SCOPE.key && r.review_state === "draft");
+    const outboxIds = new Set(outbox.map((r) => r.id));
+    const byScope = new Map();
+    for (const r of current) {
+        if (outboxIds.has(r.id))
+            continue;
+        const arr = byScope.get(r.scope_key) ?? [];
+        arr.push(r);
+        byScope.set(r.scope_key, arr);
+    }
+    // Personal first, then project scopes by key for a stable order.
+    // D70: every requested scope appears, including one with nothing in it —
+    // "this project has no memories" is part of the answer, and dropping the
+    // section made the report look like the project was never looked at.
+    const orderedKeys = [
+        ...scopeKeys.filter((k) => k === PERSONAL_SCOPE.key),
+        ...scopeKeys.filter((k) => k !== PERSONAL_SCOPE.key).sort(),
+    ];
+    const scopes = orderedKeys.map((k) => {
+        const rows = byScope.get(k) ?? [];
+        return {
+            scopeKey: k,
+            projectName: rows[0]?.project_name || k,
+            rows,
+        };
+    });
+    return {
+        generatedAt: new Date().toISOString(),
+        scopes,
+        outbox,
+        hidden,
+        hiddenEntries,
+        total: current.length,
+    };
+}
+function hiddenLine(data) {
+    const { superseded, retracted, archived } = data.hidden;
+    if (superseded + retracted + archived === 0)
+        return "";
+    return `Not shown: ${superseded} superseded version(s), ${retracted} retracted, ${archived} archived — inspect with \`open-memex list --include all\`.`;
+}
+function entriesText(rows, startAt = 0) {
+    if (rows.length === 0)
+        return "(nothing remembered in this scope yet)";
+    return rows
+        .map((r, i) => formatInventoryLine(startAt + i, { ...r, snippet: r.content }, PERSONAL_SCOPE.key))
+        .join("\n");
+}
+/** Plain-text rendering: diffable in any terminal or CI log. */
+export function renderInventoryText(data) {
+    const out = [];
+    out.push(`What OpenMemex remembers — ${data.generatedAt}`);
+    out.push(`${data.total} memories (${data.scopes.reduce((n, s) => n + (s.scopeKey === PERSONAL_SCOPE.key ? s.rows.length : 0), 0)} personal, ${data.outbox.length} in the outbox).`);
+    // D70: one running counter across every section, so a number quoted back
+    // ("delete #3") names exactly one entry in this report.
+    let seq = 0;
+    for (const s of data.scopes) {
+        const title = s.scopeKey === PERSONAL_SCOPE.key
+            ? "About you — personal (never leaves this machine)"
+            : `Project: ${s.projectName}`;
+        out.push("", `## ${title} (${s.rows.length})`, entriesText(s.rows, seq));
+        seq += s.rows.length;
+    }
+    if (data.outbox.length > 0) {
+        out.push("", `## Not in the repo yet — outbox drafts (${data.outbox.length})`, "These exist only on this machine. They reach the repo through review (submit → promote), never automatically.", entriesText(data.outbox, seq));
+        seq += data.outbox.length;
+    }
+    const hidden = hiddenLine(data);
+    if (hidden)
+        out.push("", hidden);
+    out.push("", "Read-only report. To remove a memory, tell your agent to forget it — it will read the entry back before deleting (deletion is permanent).");
+    return out.join("\n") + "\n";
+}
+/**
+ * JSON rendering: same data, for agents. Mirrors the export field names.
+ *
+ * D70: format `/2` drops the absolute `file` path. This artifact is meant
+ * to be handed to an agent — i.e. pasted into a cloud conversation — and it
+ * carried the user's home directory and name with it. The id locates the
+ * file (`open-memex where` prints the data root).
+ */
+export function renderInventoryJson(data) {
+    const entry = (r) => ({
+        id: r.id,
+        scope: r.scope_key,
+        project: r.project_name,
+        type: r.type,
+        status: r.status,
+        review_state: r.review_state,
+        source: r.source,
+        created_at: new Date(r.created_at).toISOString(),
+        updated_at: new Date(r.updated_at).toISOString(),
+        content: r.content,
+    });
+    return (JSON.stringify({
+        format: "open-memex-inventory/2",
+        generated_at: data.generatedAt,
+        total: data.total,
+        scopes: data.scopes.map((s) => ({
+            scope: s.scopeKey,
+            project: s.projectName,
+            memories: s.rows.map(entry),
+        })),
+        outbox: data.outbox.map(entry),
+        hidden: data.hidden,
+    }, null, 2) + "\n");
+}

package/dist/mcp.js

@@ -89,6 +89,15 @@ memory_resolve, memory_pr_status — always call them by these full names.
   question into its concepts and try 2–3 phrasings per concept (synonyms, the
   user's other language, shorter keyword forms), and check the other scope too,
   before concluding nothing is stored.
+- When the user asks what you remember (about them, or in this project),
+  call memory_list with scope=both and present it conversationally — turn
+  the structured fields into plain words (source=user → "you told me
+  this"; source=inference → "I inferred this, check me"), and don't read
+  raw ids aloud. If they ask to remove or hide an entry, re-run
+  memory_list first (numbers from an older listing may have shifted),
+  read the candidate back in full, and get a confirmation before calling
+  memory_forget: deletion is permanent. If they hesitate, offer soft=true
+  (hide it instead — still one-way, but the file survives).
 - Memories default to this project's scope; use the personal scope for facts
   about the user that hold across all projects. When a saved fact becomes
   outdated, call memory_supersede (find the old memory's id with memory_search

package/dist/opencode-v2.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { PLUGIN_ID, bootstrapPlugin, captureFromText, injectOnce, } from "./plugin-core.js";
+import { PLUGIN_ID, bootstrapPlugin, captureFromText, captureHandoff, injectOnce, } from "./plugin-core.js";
 import { makeTools } from "./tools/memory.js";
 /** Register the five memory tools on a v2 host. */
 async function registerTools(ctx, state) {
@@ -28,12 +28,17 @@ export const v2Plugin = {
         const registrations = [];
         await registerTools(ctx, state);
         registrations.push(await ctx.session.hook("prompt", (ev) => {
-            captureFromText(ev.prompt?.text ?? "", state);
+            captureFromText(ev.prompt?.text ?? "", state, ev.sessionID ?? "");
         }));
         registrations.push(await ctx.session.hook("context", (ev) => {
-            injectOnce(ev.sessionID ?? "", state, (block) => {
+            const sessionID = ev.sessionID ?? "";
+            injectOnce(sessionID, state, (block) => {
                 ev.system.push({ type: "text", text: block });
             });
+            // D73: tell the agent what the keyword hook already stored this turn.
+            const handoff = captureHandoff(sessionID, state);
+            if (handoff)
+                ev.system.push({ type: "text", text: handoff });
         }));
         return () => {
             for (const r of registrations)

package/dist/paths.js

@@ -84,6 +84,24 @@ export function inRepoMemoriesDir(root, memoryDir) {
     return dir;
 }
 /** Same as `inRepoMemoriesDir` but never creates the directory. */
+/**
+ * True when a memory file lives inside the user's git working tree (the
+ * in-repo `.ai/open-memex/` copy) rather than in the local data root.
+ *
+ * D70: both destructive/corrective surfaces need this — the hard delete
+ * already said "commit the deletion so the team sees it" (D64), and the
+ * soft hide has to say the same, because a retraction that never gets
+ * committed leaves the memory standing on every teammate's clone.
+ */
+export function isInRepoMemoryFile(filePath) {
+    if (!filePath)
+        return false;
+    const normalized = filePath.replace(/\\/g, "/");
+    return normalized.includes("/.ai/open-memex/") && !normalized.startsWith(root());
+}
+function root() {
+    return paths().root.replace(/\\/g, "/");
+}
 export function inRepoMemoriesDirPath(root, memoryDir) {
     return path.join(root, memoryDir);
 }

package/dist/plugin-core.js

@@ -6,6 +6,7 @@ import { scopeHasFiles } from "./store/migrate.js";
 import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
 import { buildContextBlock } from "./retrieve/inject.js";
 import { detectKeywords } from "./capture/keywords.js";
+import { formatHandoffBlock, freshCaptures, } from "./capture/handoff.js";
 import { findDuplicates } from "./store/lifecycle.js";
 import { redact } from "./redact.js";
 /**
@@ -44,14 +45,16 @@ export function bootstrapPlugin(root) {
     catch (err) {
         console.error("[open-memex] init failed:", err);
     }
-    return { cfg, scope, injectedSessions: new Set() };
+    return { cfg, scope, injectedSessions: new Set(), captures: new Map() };
 }
 /**
  * Keyword capture (§ capture): scan one user message for "remember …"
  * triggers and save each hit. Shared by the v1 `chat.message` hook and
- * the v2 session `prompt` hook — both hand us the message text.
+ * the v2 session `prompt` hook — both hand us the message text and the
+ * session id. The session id is what makes the D73 hand-off possible: without
+ * it the agent never learns the sentence is already stored.
  */
-export function captureFromText(text, state) {
+export function captureFromText(text, state, sessionID) {
     const { cfg, scope } = state;
     if (!cfg.keywordCaptureEnabled || !text)
         return;
@@ -106,12 +109,54 @@ export function captureFromText(text, state) {
             // offers no toast channel, so the plugin log is the feedback surface.
             const preview = content.length > 60 ? content.slice(0, 60) + "…" : content;
             console.log(`[open-memex] remembered → ${target.kind} scope: "${preview}"`);
+            // D73 hand-off: the agent gets told about this capture in the turn's
+            // system context, so it does not save the same statement again.
+            recordCapture(state, sessionID, { id: fm.id, scopeKey: target.key, content, at: now });
         }
         catch (err) {
             console.error("[open-memex] keyword capture failed:", err);
         }
     }
 }
+/** Note one hook capture against its session (D73). No-op without a session. */
+function recordCapture(state, sessionID, record) {
+    if (!sessionID)
+        return;
+    const list = state.captures.get(sessionID) ?? [];
+    list.push(record);
+    state.captures.set(sessionID, list);
+}
+/**
+ * D73 hand-off note (a): what the keyword hook already stored for this
+ * session, delivered once per capture into the turn's system context. The
+ * agent cannot avoid re-saving a statement it cannot see is stored, so the
+ * store tells it. Returns "" when there is nothing new to hand off; stale
+ * records are pruned (in-memory only, like `injectedSessions`).
+ *
+ * Both host adapters push this from their system/context hook — the one that
+ * runs before the model request, i.e. after `chat.message` / `prompt`.
+ */
+export function captureHandoff(sessionID, state) {
+    if (!sessionID)
+        return "";
+    const list = state.captures.get(sessionID);
+    if (!list || list.length === 0)
+        return "";
+    const now = Date.now();
+    const fresh = freshCaptures(list, now);
+    if (fresh.length !== list.length) {
+        if (fresh.length === 0)
+            state.captures.delete(sessionID);
+        else
+            state.captures.set(sessionID, fresh);
+    }
+    const pending = fresh.filter((r) => !r.delivered);
+    if (pending.length === 0)
+        return "";
+    for (const r of pending)
+        r.delivered = true;
+    return formatHandoffBlock(pending);
+}
 /**
  * First-turn context injection: exactly once per session. The host adapter
  * supplies `push` (v1: output.system.push; v2: the session context hook's

package/dist/retrieve/display.js

@@ -0,0 +1,161 @@
+/**
+ * Display helpers (D68): how memory provenance, age, and state are
+ * rendered on the user-facing surfaces — the `memory_list` inventory an
+ * agent shows its user, and the `open-memex inventory` reports.
+ *
+ * Two rules from the 3-C design (v2) live here:
+ * - The list format is STRUCTURED data (number + id + created= + source=
+ *   + state tags). The plain-language renderings ("you said this",
+ *   "3 days ago") live in the guidance surfaces (tool descriptions,
+ *   SKILL.md, MCP handshake) so an agent rephrases them in the
+ *   conversation's language — the raw enums never get localized or
+ *   reworded inside the data itself.
+ * - Nothing truncates silently: callers pair these lines with the true
+ *   totals so a cut list says so.
+ */
+/** Human age for a saved memory: "just now", "3 days ago", else a date. */
+export function relativeTime(ts, now = Date.now()) {
+    if (!ts || Number.isNaN(ts))
+        return "";
+    const diff = now - ts;
+    if (diff < 0)
+        return "just now";
+    const minute = 60_000;
+    const hour = 60 * minute;
+    const day = 24 * hour;
+    if (diff < minute)
+        return "just now";
+    if (diff < hour) {
+        const n = Math.floor(diff / minute);
+        return `${n} minute${n === 1 ? "" : "s"} ago`;
+    }
+    if (diff < day) {
+        const n = Math.floor(diff / hour);
+        return `${n} hour${n === 1 ? "" : "s"} ago`;
+    }
+    if (diff < 30 * day) {
+        const n = Math.floor(diff / day);
+        return `${n} day${n === 1 ? "" : "s"} ago`;
+    }
+    const d = new Date(ts);
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    return `on ${d.getFullYear()}-${mm}-${dd}`;
+}
+/** Compact age token for the structured list format: `3d`, `12h`, `now`. */
+export function ageToken(ts, now = Date.now()) {
+    if (!ts || Number.isNaN(ts))
+        return "?";
+    const diff = now - ts;
+    if (diff < 60_000)
+        return "now";
+    if (diff < 3_600_000)
+        return `${Math.floor(diff / 60_000)}m`;
+    if (diff < 86_400_000)
+        return `${Math.floor(diff / 3_600_000)}h`;
+    if (diff < 60 * 86_400_000)
+        return `${Math.floor(diff / 86_400_000)}d`;
+    const d = new Date(ts);
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    return `${d.getFullYear()}-${mm}-${dd}`;
+}
+/**
+ * Provenance in the user's words (D68). Used by prose surfaces (HTML
+ * report); the structured list keeps the raw `source=` enum instead.
+ * The distinction that matters to the user is *whose words these were* —
+ * said outright, asked to be saved, auto-captured, or inferred by the
+ * agent and possibly wrong.
+ */
+export function sourceLabel(source) {
+    switch (source) {
+        case "user":
+            return "you said this";
+        case "cli":
+            return "you saved this from the command line";
+        case "tool":
+            return "you asked me to save this";
+        case "keyword":
+            return "auto-captured from your own wording";
+        case "inference":
+            return "I inferred this — not in your words, check me";
+        case "import":
+            return "imported from another machine";
+        default:
+            return source ? `saved (${source})` : "saved";
+    }
+}
+/**
+ * Review state in plain words for project scopes (D68). Personal
+ * memories are always `draft` by design; callers must not show this
+ * for them — "not yet shared" would be alarming noise there.
+ */
+export function reviewStateLabel(reviewState) {
+    switch (reviewState) {
+        case "draft":
+            return "still in your outbox — not in the repo yet";
+        case "proposed":
+            return "shared with the project, waiting for review";
+        case "approved":
+            return "approved, not yet published";
+        case "published":
+            return "published to the repo";
+        case "rejected":
+            return "reviewed and rejected";
+        default:
+            return reviewState ?? "draft";
+    }
+}
+/** Escape user content for HTML. Memory text is arbitrary user input. */
+export function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+/**
+ * One structured inventory line (D68):
+ *   3. [fact] id=01K6… created=3d source=user [draft] — body text
+ * Number and id always appear together: the number is for the user's
+ * mouth ("delete #3"), the id is the machine contract. `created=` is
+ * when the memory was learned; `updated=` appears only when it moved
+ * materially later (supersede/promote touch updated_at).
+ *
+ * D70: `index` must be a running counter across every section of one
+ * listing — a per-section counter produces two "#1"s in a single
+ * `scope: both` output, which makes "delete #3" a guess.
+ */
+export function formatInventoryLine(index, hit, personalKey, now = Date.now()) {
+    const parts = [
+        `${index + 1}.`,
+        `[${hit.type}]`,
+        `id=${hit.id}`,
+        `created=${ageToken(hit.created_at ?? hit.updated_at, now)}`,
+        `source=${hit.source || "?"}`,
+    ];
+    const created = hit.created_at ?? hit.updated_at ?? 0;
+    if (hit.updated_at && hit.updated_at - created >= 86_400_000) {
+        parts.push(`updated=${ageToken(hit.updated_at, now)}`);
+    }
+    if (hit.scope_key !== personalKey) {
+        const state = hit.review_state ?? "draft";
+        if (state !== "published")
+            parts.push(`[${state}]`);
+    }
+    if (hit.status !== "active")
+        parts.push(`[${hit.status}]`);
+    const body = hit.snippet.replace(/\s+/g, " ").trim();
+    return `${parts.join(" ")} — ${body}`;
+}
+/**
+ * Truncation disclosure (D68): a cut list always says so.
+ * D70: the wording names the surface that can show everything — the CLI —
+ * so a hidden entry is always reachable.
+ */
+export function truncationNote(shown, total, cli = "open-memex") {
+    if (total <= shown)
+        return null;
+    return `… and ${total - shown} more not shown (raise limit up to 100, run \`${cli} list --limit 100\`, or use memory_search to find something specific).`;
+}