open-memex 0.7.0-alpha.8 → 0.7.0-alpha.9

package/AGENTS.md

@@ -33,6 +33,7 @@ npm run typecheck                                    # tsc --noEmit — the only
 npm run cli -- where | list | search "q" | add ... | forget <id> | reindex
 npm run cli -- <command> --help                          # per-command help (AI assistants discover flags this way)
 npm run cli -- sync-status                                  # last sync time/kind + outbox drafts + repo review states + uncommitted files
+npm run cli -- inventory [--format text|json] [--scope both]  # what is remembered, in the open (D68); personal-bearing output refused inside a git worktree without --allow-personal
 npm run cli -- audit [--scope project|personal|both]            # memory health: near-dup pairs, stale actives, broken chains, personal-in-repo (read-only)
 npm run cli -- pull                                          # fetch + fast-forward only (explicit; diverged = clean failure, never force-merge)
 npm run cli -- push                                          # push current branch to remote (explicit only; open-memex never auto-pushes)
@@ -165,9 +166,9 @@ Context injection happens exactly once per session in `experimental.chat.system.
 
 ## Design constraints — read the frozen design first
 
-`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions D1–D64 settled; open questions tracked at the end of the doc). Per its §12:
+`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D68; open questions tracked at the end of the doc). Per its §12:
 AGENTS.md answers "how should AI work here"; the design doc answers "why is it
-built this way" (principles, iron rules, the append-only decision log, currently D1–D67). Before changing
+built this way" (principles, iron rules, the append-only decision log, currently D1–D68). Before changing
 architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
 schema, MCP tools, CLI contract), read the relevant design section — the decision
 log records what was already considered and rejected.

package/CHANGELOG.md

@@ -9,6 +9,15 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+## Memory visibility: see it, hide it, delete it (D68)
+
+Group 3-C — the surface a user reads to learn what the store actually remembers:
+
+- **`memory_list` is now a numbered inventory.** Lines are structured (`[type] id=… created=… source=…`), keep the raw provenance, and every listing states its true total — a truncated list says how many entries it is not showing instead of quietly looking complete. New input `include: "active" | "all"` (default `active`): **behavior change** — superseded versions, retracted and archived memories no longer appear unless you pass `include=all` (the audit view). The CLI gains the matching `list --include` flag.
+- **`open-memex inventory`** renders the same data as readable text (default) or JSON (`--format json`, format `open-memex-inventory/1`) — personal plus the current project, outbox drafts in their own section, hidden history counted rather than silently dropped. A report containing personal memories refuses to be written inside a git working tree without `--allow-personal`.
+- **Hide instead of delete:** `memory_forget` gains `soft=true` (CLI: `forget --soft`) — the memory is retracted: out of lists and search, file kept. Still one-way (D64): bringing the fact back means saving it again.
+- **Guidance kept in one voice:** the tool descriptions, the MCP session-start instructions, SKILL.md and the `distill-agents` AGENTS.md snippet all teach the same flow — answer "what do you remember?" conversationally from the inventory, re-list before acting on a number, read an entry back before deleting it.
+
 ## Keyword capture: what counts as a trigger (D67)
 
 The D66 review left two questions open and introduced one regression. Ruled, not deferred:

package/README.md

@@ -416,9 +416,9 @@ they only matter once you share memories through Git.
 |---|---|
 | ● `memory_add`       | Save a fact, preference, decision, note |
 | ● `memory_search`    | Keyword search (BM25) across project + personal memories |
-| ● `memory_list`      | List memories in a scope (`project`, `personal`, or `both`), newest first |
+| ● `memory_list`      | List memories in a scope (`project`, `personal`, or `both`) as a numbered inventory; `include=all` is the audit view |
 | ● `memory_supersede` | Replace a memory with a newer version (keeps a supersede chain) |
-| ● `memory_forget`    | Delete a memory by id |
+| ● `memory_forget`    | Delete a memory by id (`soft=true` hides it instead — retracted, one-way) |
 | `memory_status`      | Show the sync queue: outbox drafts, repo review states, uncommitted files |
 | `memory_submit`      | Move named drafts into the repo memory dir (local branch + commit) |
 | `memory_propose`     | Copy personal memories into the project scope as review candidates |
@@ -643,9 +643,17 @@ open-memex search "auth flow"
 open-memex search "auth flow" --explain   # show FTS expression, scores, lifecycle-hidden counts
 open-memex list --scope project
 open-memex list --scope both       # each scope's newest under its own header
+open-memex list --include all      # audit view: superseded versions, retracted, archived
 open-memex supersede <id> "Updated content"
 open-memex status <id> deprecated
 open-memex forget <id>
+open-memex forget <id> --soft      # hide instead of delete (retracted; one-way)
+
+open-memex inventory                        # everything remembered, as readable text
+open-memex inventory --format json          # the same data, for agents
+# Personal + current project, outbox drafts in their own section, hidden
+# history counted. Refuses to write a personal-bearing report inside a
+# git working tree unless you pass --allow-personal.
 ```
 
 Team review workflow (two homes, one per stage):

package/README.zh-CN.md

@@ -275,9 +275,9 @@ MCP 服务器暴露十一个工具；opencode 原生插件暴露其中五个核
 |---|---|
 | ● `memory_add`       | 保存一条事实、偏好、决策、笔记 |
 | ● `memory_search`    | 关键词搜索（BM25），横跨项目 + 个人记忆 |
-| ● `memory_list`      | 列出某个作用域（`project`、`personal` 或 `both`）的记忆，最新在前 |
+| ● `memory_list`      | 以编号清单列出某个作用域（`project`、`personal` 或 `both`）的记忆；`include=all` 是审计视图 |
 | ● `memory_supersede` | 用新版本替换一条记忆（保留 supersede 链） |
-| ● `memory_forget`    | 按 id 删除一条记忆 |
+| ● `memory_forget`    | 按 id 删除一条记忆（`soft=true` 改为隐藏——retracted，单向） |
 | `memory_status`      | 显示同步队列：outbox 草稿、仓库评审状态、未提交文件 |
 | `memory_submit`      | 把指定的草稿移进仓库记忆目录（本地分支 + 提交） |
 | `memory_propose`     | 把个人记忆复制到项目作用域，作为评审候选 |
@@ -443,9 +443,16 @@ open-memex search "auth flow"
 open-memex search "auth flow" --explain   # 显示 FTS 表达式、分数、被生命周期藏掉的计数
 open-memex list --scope project
 open-memex list --scope both       # 两个作用域各自最新的，各带一个标题
+open-memex list --include all      # 审计视图：被替换的版本、已撤回、已归档
 open-memex supersede <id> "Updated content"
 open-memex status <id> deprecated
 open-memex forget <id>
+open-memex forget <id> --soft      # 隐藏而不是删除（retracted，单向）
+
+open-memex inventory                        # 记住的一切，纯文本清单
+open-memex inventory --format json          # 同一份数据，JSON 格式给 agent 用
+# 个人 + 当前项目，outbox 草稿单独成节，被藏起的历史只计数。含个人内容的
+# 报告拒绝写进 git 工作树，除非显式 --allow-personal。
 ```
 
 团队评审工作流（两个家，一个阶段一个）：

package/dist/.build-stamp

@@ -1 +1 @@
-f4cf4e253bbf0f3254ec439b1344af50e88cc4fd068b04be73cdc20ee770e819
+3a590ae176c625e174a075a2d9068fe443d23c374f70fc7df76809ff10a63ad4

package/dist/cli.js

@@ -17,7 +17,22 @@ import { redact } from "./redact.js";
 import { resolveMcpCommand } from "./init.js";
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+/** True when `target` sits inside a git working tree (D68 guard). */
+function isInsideWorkTree(target) {
+    try {
+        const dir = path.dirname(path.resolve(target));
+        const out = execFileSync("git", ["-C", dir, "rev-parse", "--is-inside-work-tree"], {
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf8",
+        });
+        return out.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
 /** Per-command help, printed by `open-memex <command> --help`.
     AI assistants discover the CLI through --help, so every command needs one. */
 const COMMAND_HELP = {
@@ -29,12 +44,14 @@ Example:
   open-memex where`,
     list: `List memories in a scope, newest first.
 
-Usage: open-memex list [--scope project|personal|both] [--type T] [--limit N]
+Usage: open-memex list [--scope project|personal|both] [--type T] [--limit N] [--include active|all]
 
 Flags:
-  --scope   project (default), personal, or both
-  --type    filter by memory type
-  --limit   max results
+  --scope    project (default), personal, or both
+  --type     filter by memory type
+  --limit    max results
+  --include  active (default: what is currently remembered) or all (audit
+             view: superseded versions, retracted and archived included)
 
 Examples:
   open-memex list
@@ -85,12 +102,15 @@ Retraction is one-way: a retracted memory cannot be set back to active
 
 Example:
   open-memex status 01ABC deprecated`,
-    forget: `Delete a memory by id.
+    forget: `Delete a memory by id. With --soft, hide it instead: the memory
+is retracted (out of lists and search, file kept). Retraction is one-way —
+save the content as a new memory to bring it back.
 
-Usage: open-memex forget <id>
+Usage: open-memex forget <id> [--soft]
 
 Example:
-  open-memex forget 01ABC`,
+  open-memex forget 01ABC
+  open-memex forget 01ABC --soft`,
     propose: `Copy personal memories into the project outbox as review drafts.
 The personal originals stay put. Nothing enters git at this step.
 
@@ -137,6 +157,19 @@ Usage: open-memex sync-status
 
 Example:
   open-memex sync-status`,
+    inventory: `Show everything remembered — personal + this project — in the
+open: what each memory says, where it came from, and whether it has reached
+the repo yet. Read-only; deleting stays a confirmed conversation with your
+agent. Formats: text (default, diffable) and json (for agents).
+
+Usage: open-memex inventory [--format text|json] [--scope project|personal|both] [--out <path>] [--allow-personal]
+
+Default scope: both. Without --out the report goes to stdout. A report that
+includes personal memories is refused inside a git working tree unless
+--allow-personal is passed — personal content must not ride a commit.
+
+Example:
+  open-memex inventory --format json --out ~/inventory.json`,
     pull: `Pull shared project memories from the git remote: fetch + fast-forward
 only. Never auto-merges — a diverged branch fails with a clear message and is
 left for you to resolve by hand. On success the local index re-syncs.
@@ -334,16 +367,17 @@ function usage(exitCode = 1) {
 
 Usage:
   open-memex where
-  open-memex list [--scope project|personal] [--type T] [--limit N]
+  open-memex list [--scope project|personal|both] [--type T] [--limit N] [--include active|all]
   open-memex search "query" [--scope project|personal|both] [--type T] [--limit N] [--explain]
   open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
   open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
   open-memex status <id> active|deprecated|retracted|archived
-  open-memex forget <id>
+  open-memex forget <id> [--soft]
   open-memex propose <id...> --to project [--local-approve]
   open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
   open-memex resolve [id-or-path]
   open-memex sync-status
+  open-memex inventory [--format text|json] [--scope project|personal|both] [--out <path>] [--allow-personal]
   open-memex pull
   open-memex push
   open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
@@ -784,6 +818,7 @@ async function main() {
             const hits = list(s.key, {
                 type: flags.type,
                 limit: flags.limit ? Number(flags.limit) : undefined,
+                include: flags.include === "all" ? "all" : "active",
             });
             if (scopes.length > 1)
                 console.log(`## ${s.kind} (${s.key})`);
@@ -792,7 +827,7 @@ async function main() {
                 continue;
             }
             for (const h of hits) {
-                const dep = h.status === "deprecated" ? " [deprecated]" : "";
+                const dep = h.status !== "active" ? ` [${h.status}]` : "";
                 const rev = hitStateLabel(h);
                 console.log(`[${h.type}]${dep}${rev} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
             }
@@ -964,6 +999,20 @@ async function main() {
         const id = rest[0];
         if (!id)
             usage();
+        // D68: --soft hides (retracts) instead of deleting — same action as
+        // the memory_forget tool's soft flag. One-way (D64).
+        if (rest.includes("--soft")) {
+            try {
+                const mf = setStatus(id, "retracted");
+                upsertFromFile(mf);
+                console.log(`hidden ${id} (retracted — out of lists and search; save it again as a new memory to bring it back)`);
+            }
+            catch (e) {
+                console.error(`hide failed: ${e.message}`);
+                process.exit(1);
+            }
+            return;
+        }
         const row = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id);
         if (!row) {
             console.error("not found");
@@ -1101,6 +1150,52 @@ async function main() {
         }
         return;
     }
+    if (cmd === "inventory") {
+        // D68: refresh both scopes first so the report matches the markdown
+        // on disk. Default scope: personal + this project.
+        syncScope(project.key, "cli");
+        syncScope(PERSONAL_SCOPE.key, "cli");
+        const flags = parseFlags(rest);
+        const format = flags.format ?? "text";
+        if (format !== "text" && format !== "json") {
+            console.error(`inventory: unknown --format '${format}' (text|json; html arrives separately)`);
+            process.exit(2);
+        }
+        const scopeKeys = flags.scope === "personal"
+            ? [PERSONAL_SCOPE.key]
+            : flags.scope === "project"
+                ? [project.key]
+                : [PERSONAL_SCOPE.key, project.key];
+        const outPath = flags["out"] ?? flags["output"];
+        // D68/3-C v2: the report contains personal content. Writing it into
+        // a git working tree would ride the next commit off this machine —
+        // refuse unless the user explicitly accepts that.
+        if (outPath &&
+            scopeKeys.includes(PERSONAL_SCOPE.key) &&
+            flags["allow-personal"] !== "true" &&
+            isInsideWorkTree(outPath)) {
+            console.error(`inventory: ${outPath} is inside a git working tree and this report includes personal memories. ` +
+                `Refusing to write it there. Pass --allow-personal if you really want that, or write outside the repo.`);
+            process.exit(2);
+        }
+        try {
+            const { loadInventory, renderInventoryText, renderInventoryJson } = await import("./inventory.js");
+            const data = loadInventory(scopeKeys);
+            const rendered = format === "json" ? renderInventoryJson(data) : renderInventoryText(data);
+            if (outPath) {
+                fs.writeFileSync(outPath, rendered, "utf8");
+                console.log(`inventory: ${data.total} memories → ${outPath}`);
+            }
+            else {
+                process.stdout.write(rendered);
+            }
+        }
+        catch (e) {
+            console.error(`inventory failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
     if (cmd === "sync-status") {
         syncScope(project.key, "cli");
         syncScope(PERSONAL_SCOPE.key, "cli");

package/dist/distill-agents.js

@@ -62,7 +62,10 @@ export function distillAgentsMarkdown(opts) {
     // inferred captures source: "inference"; this footer omitted it, so
     // opencode agents saved distilled conclusions as if the user had
     // stated them ("tool"). Keep the rubric one voice across surfaces.
-    `- Mark captures you infer (rather than the user stating) with`, `  \`source: "inference"\` — provenance matters more than polish.`);
+    `- Mark captures you infer (rather than the user stating) with`, `  \`source: "inference"\` — provenance matters more than polish.`, 
+    // D68: same voice for the visibility surface — opencode agents reading
+    // this footer never see the MCP handshake either.
+    `- When the user asks what you remember, list it conversationally`, `  (\`memory_list\` with scope both, or \`open-memex inventory\`) — plain`, `  words, not raw ids. Before deleting an entry they point at, read it`, `  back in full and confirm; deletion is permanent. Offer hiding`, `  (\`memory_forget\` soft / \`forget --soft\`) when they hesitate.`);
     lines.push(``);
     return lines.join("\n");
 }

package/dist/inventory.js

@@ -0,0 +1,138 @@
+/**
+ * `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).
+ */
+export function loadInventory(scopeKeys) {
+    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 hiddenRows = 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);
+    const hidden = { superseded: 0, retracted: 0, archived: 0 };
+    for (const r of hiddenRows) {
+        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.
+    const orderedKeys = [
+        ...scopeKeys.filter((k) => k === PERSONAL_SCOPE.key),
+        ...[...byScope.keys()].filter((k) => k !== PERSONAL_SCOPE.key).sort(),
+    ];
+    const scopes = orderedKeys
+        .filter((k) => byScope.has(k))
+        .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,
+        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) {
+    return rows
+        .map((r, i) => formatInventoryLine(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).`);
+    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));
+    }
+    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));
+    }
+    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. */
+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,
+        file: r.file_path,
+    });
+    return (JSON.stringify({
+        format: "open-memex-inventory/1",
+        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/retrieve/display.js

@@ -0,0 +1,153 @@
+/**
+ * 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).
+ */
+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. */
+export function truncationNote(shown, total) {
+    if (total <= shown)
+        return null;
+    return `… and ${total - shown} more not shown (raise limit up to 100, or use memory_search to find something specific).`;
+}