@zenera/cli 1.1.23 → 1.1.25

package/dist/commands/memory.js

@@ -1,13 +1,15 @@
-import { ALL_AGENTS, buildMemoryReport, hostPath, memoryDir, MemoryIndex, MemoryStore, MergeConflicts, mergeMemories, readProjectConfig, renderMemoryHtml, } from '@zenera/neo';
+import { ALL_AGENTS, buildMemoryReport, createEmbedder, diffMemories, GREP_FIELDS, grepMemory, hostPath, memoryDir, MemoryError, MemoryIndex, MemoryStore, MergeConflicts, mergeMemories, readProjectConfig, renderMemoryHtml, renderRecollection, } from '@zenera/neo';
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
-import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { basename, isAbsolute, join, resolve } from 'node:path';
 import { parse } from "../args.js";
+import { loadProjectEnv } from "../env.js";
+import { KeyStore } from "../keys.js";
 import { project as resolveProject } from "../resolve.js";
-import { ago, bold, bytes, CliError, confirm, count, cyan, dim, EXIT, green, isInteractive, json, note, table, usageError, write, writeAll, yellow, } from "../term.js";
-const USAGE = 'zen memory [stats|ls|show|export|merge|forget] [args] [options]';
-const SUBCOMMANDS = ['stats', 'ls', 'show', 'export', 'merge', 'forget'];
+import { ago, bold, bytes, CliError, confirm, count, cyan, dim, EXIT, green, isInteractive, json, note, plain, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen memory [stats|ls|search|grep|show|diff|export|merge|forget] [args] [options]';
+const SUBCOMMANDS = ['stats', 'ls', 'search', 'grep', 'show', 'diff', 'export', 'merge', 'forget'];
 /** Enough to see the shape of it; the rest is a number. */
 const LISTED = 30;
 // ---------------------------------------------------------------------------
@@ -24,9 +26,11 @@ const LISTED = 30;
 // an agent inside a run, and the mask exists to keep agents apart rather than
 // to keep secrets from the person who owns the files.
 //
-// Nothing here contacts a model. The store is opened without an embedder, so
-// inspection is free and works offline; the price is that `ls` filters by text
-// rather than by meaning, which is the right trade for a debugging tool.
+// `search` is the one subcommand that contacts a model, and it has to: the
+// question it answers is what an agent's recall returns, and a recall ranked
+// any other way is a different answer wearing the same shape. Everything else
+// is offline, so inspecting a graph whose credentials have gone missing —
+// which is exactly when someone is debugging — still works.
 // ---------------------------------------------------------------------------
 export const memory = {
     summary: 'What the agents remember, and getting rid of it.',
@@ -35,7 +39,10 @@ export const memory = {
     details: [
         '  stats                  Size, vocabulary, and whether it is embedded.',
         '  ls                     Nodes, newest first. Changes nothing.',
+        '  search <text>          Recall it, the way an agent does. Ranked.',
+        '  grep <pattern>         Every node containing it, with the matching lines.',
         '  show <id>              One node in full, with what it links to.',
+        '  diff <base>            What this memory holds that <base> did not.',
         '  export [file]          The whole graph as one HTML page.',
         '  merge <dir...>         Fold other memories into this one.',
         '  forget <id...>         Remove nodes, their vectors and their files.',
@@ -46,7 +53,16 @@ export const memory = {
         '  --audience <name>      Only nodes committed under this label.',
         '  --files                Only nodes that remember a file.',
         '  --stale                Only nodes something has superseded.',
-        '  --limit <n>            Rows to list. Default 30.',
+        '  --all                  For `search` and `grep`: superseded nodes too, marked.',
+        '  --regex                Read the pattern as a regular expression, per line.',
+        '  --case-sensitive       Match case exactly. Off by default.',
+        '  --in <text|metadata|file>  Where to look. Repeatable. All three by default.',
+        '  --ids-only             Print bare ids, for piping into `zen memory show`.',
+        '  --limit <n>            Rows to list, or seeds to rank. Default 30, search 10.',
+        '  --hops <n>             How far `search` follows links from a seed. Default 2.',
+        '  --nodes <n>            Cap on the subgraph `search` returns. Default 25.',
+        '  --min-score <n>        Drop seeds scoring below this. Default 0.15.',
+        '  --embedding <ref>      Rank `search` with this model, not the project’s.',
         '  --out <file>           Where `export` writes. Default memory.html.',
         '  --open                 Open the exported page.',
         '  --dry-run              Say what `merge` would do, and stop.',
@@ -62,10 +78,39 @@ export const memory = {
         'page: the node list on the left, the graph in the middle, and whatever',
         'you click on the right, file contents and all.',
         '',
+        '`search` is recall itself, run from here. It embeds the query with the',
+        'project’s own model and prints the block a model would have been given,',
+        'scores and all — so *why did it recall that?* has an answer, and so does',
+        '*why did it not?*:',
+        '',
+        '  zen memory search ‘how do we deploy’ --audience reviewer',
+        '',
+        'Passing `--audience` recalls as an agent that sees only that label,',
+        'which is how a memory that is present but invisible gives itself away.',
+        '',
+        '`grep` is the counterpart. Recall ranks, so it answers “what is closest”',
+        'and can never answer “is this in here at all”; `grep` reads every node',
+        'exactly — text, metadata and the bytes of remembered files — and the',
+        'count it reports is the true one even when the list was cut:',
+        '',
+        '  zen memory grep ‘staging.example.com’ --in metadata --in file',
+        '',
+        'Nothing that only reads takes the directory lock, so every subcommand',
+        'here but `merge` and `forget` works on a memory a run is writing, and on',
+        'the read-only /memory mount inside a sandbox.',
+        '',
         '`merge` is for warming a memory in parallel. The lock is per directory,',
         'so N runs write N memories; this folds them back into one:',
         '',
-        '  zen memory merge .tmp/warmup-*/memory',
+        '  zen memory merge <batch-dir>/*/memory',
+        '',
+        'which is where `zen run batch` leaves them.',
+        '',
+        '`diff` is the question after a run that started from a copy: what it',
+        'added, which of those `merge` would fold onto a node <base> already held',
+        '(a re-commit), what it revised, and which nodes `memory_load` read:',
+        '',
+        '  zen memory diff <candidate> --dir <batch-dir>/<id>/memory',
     ],
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
@@ -75,7 +120,16 @@ export const memory = {
             audience: { type: 'string' },
             files: { type: 'boolean' },
             stale: { type: 'boolean' },
+            all: { type: 'boolean' },
+            regex: { type: 'boolean' },
+            'case-sensitive': { type: 'boolean' },
+            in: { type: 'string', multiple: true },
+            'ids-only': { type: 'boolean' },
             limit: { type: 'string' },
+            hops: { type: 'string' },
+            nodes: { type: 'string' },
+            'min-score': { type: 'string' },
+            embedding: { type: 'string' },
             out: { type: 'string' },
             open: { type: 'boolean' },
             yes: { type: 'boolean' },
@@ -90,15 +144,27 @@ export const memory = {
         const rest = positionals.slice(1);
         // `merge` is the one subcommand that may write a memory into existence;
         // every other one is an inspector and a missing manifest is a mistake.
-        const opened = await open(ctx.cwd, values.project, values.dir, what === 'merge');
+        // And only the two that write take the lock: the moments a reader is
+        // most wanted are while a run is writing and against the read-only
+        // /memory mount, in both of which claiming it fails.
+        const opened = await open(ctx.cwd, values.project, values.dir, {
+            create: what === 'merge',
+            lock: what === 'merge' || what === 'forget',
+        });
         try {
             switch (what) {
                 case 'stats':
                     return stats(opened, ctx.json);
                 case 'ls':
                     return list(opened, values, ctx.json);
+                case 'search':
+                    return await search(opened, rest, values, ctx.json);
+                case 'grep':
+                    return await grep(opened, rest, values, ctx.json);
                 case 'show':
                     return show(opened, rest, ctx.json);
+                case 'diff':
+                    return await diff(opened, rest, ctx.cwd, ctx.json);
                 case 'export':
                     return await write_(opened, rest, values, ctx.cwd, ctx.json);
                 case 'merge':
@@ -125,14 +191,19 @@ export const memory = {
  * `create` drops the requirement that anything be there yet, for `merge`,
  * which has somewhere to put what it reads even when the destination is a name
  * nothing has written to.
+ *
+ * `lock` is off for a read that must not fail on a busy or read-only memory.
+ * The lock exists to stop two writers losing each other's edges; a reader that
+ * took it would only be refusing itself.
  */
-async function open(cwd, want, at, create = false) {
+async function open(cwd, want, at, opts = {}) {
+    const { create = false, lock = true } = opts;
     if (at) {
         const dir = resolve(cwd, at);
         if (!create && !existsSync(join(dir, 'manifest.json'))) {
             throw usageError(`${dir} is not a memory`, 'no manifest.json in it');
         }
-        return { store: await MemoryStore.open(dir), dir, project: basename(dir) };
+        return { store: await MemoryStore.open(dir, { lock }), dir, project: basename(dir) };
     }
     const project = await resolveProject({ cwd, project: want });
     const { config } = readProjectConfig(project.dir);
@@ -143,7 +214,12 @@ async function open(cwd, want, at, create = false) {
     if (!create && !existsSync(join(dir, 'manifest.json'))) {
         throw usageError(`${project.name} has a memory configured but nothing in it yet`, 'it is written the first time an agent commits something');
     }
-    return { store: await MemoryStore.open(dir), dir, project: project.name };
+    return {
+        store: await MemoryStore.open(dir, { lock }),
+        dir,
+        project: project.name,
+        at: { root: project.dir, config },
+    };
 }
 // ---------------------------------------------------------------------------
 // stats
@@ -242,29 +318,291 @@ function list(o, flags, asJson) {
         .filter((n) => !flags.stale || stale.has(n.id))
         .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
     if (asJson) {
-        json({ total: all.length, nodes: all.slice(0, limit) });
+        json({ total: all.length, nodes: all.slice(0, limit).map((n) => onHost(o, n)) });
         return;
     }
     if (!all.length) {
         note('nothing matches');
         return;
     }
-    writeAll(table(all
+    writeAll(textLast(all
         .slice(0, limit)
         .map((n) => [
         cyan(n.id),
-        n.kind,
-        n.file ? dim('⎘ ' + n.file.format) : '',
-        clip(n.text, 56),
-        dim(ago(n.createdAt)),
-        stale.has(n.id) ? yellow('superseded') : '',
-    ])));
+        n.kind + (n.file ? dim(' ⎘ ' + n.file.format) : ''),
+        n.audience.join(','),
+        dim(`r${n.revision}`),
+        dim(ago(n.createdAt)) + (stale.has(n.id) ? ' ' + yellow('superseded') : ''),
+    ]), all.slice(0, limit).map((n) => n.text)));
     if (all.length > limit) {
         write();
         note(dim(`${all.length - limit} more — raise --limit, or use \`zen memory export\``));
     }
 }
 // ---------------------------------------------------------------------------
+// search
+// ---------------------------------------------------------------------------
+/**
+ * Recall, run from outside a run. `ls` and `grep` read the graph; this asks it
+ * the question an agent asks, through the same ranker, the same traversal and
+ * the same renderer — so what it prints is the block a model would have been
+ * handed, scores and all.
+ *
+ * That is the only way to answer *why did it recall that*, and the harder *why
+ * did it not*: a memory that is present but ranked sixth looks exactly like a
+ * memory that was never written, until the score is on the screen.
+ */
+async function search(o, rest, flags, asJson) {
+    // Joined rather than taken singly. A query is prose, and this is the one
+    // subcommand whose whole argument is prose, so quoting it is the step
+    // everybody forgets.
+    const text = rest.join(' ').trim();
+    if (!text) {
+        throw usageError('search takes something to recall', 'zen memory search <text>');
+    }
+    // Recall either includes what has been superseded or does not; there is no
+    // "only", because a correction alone is not the subgraph anyone wanted.
+    if (flags.stale) {
+        throw usageError('search has no --stale', 'use --all to recall superseded nodes too');
+    }
+    const query = {
+        text,
+        kinds: flags.kind ? [flags.kind] : undefined,
+        limit: whole(flags.limit, '--limit'),
+        // Zero hops is a real request — the seeds and nothing they dragged in.
+        maxHops: whole(flags.hops, '--hops', 0),
+        maxNodes: whole(flags.nodes, '--nodes'),
+        minScore: threshold(flags['min-score']),
+    };
+    const ranker = await vectoriser(o, flags.embedding);
+    const sees = flags.audience ? [flags.audience] : audiences(o);
+    let rec;
+    try {
+        const index = new MemoryIndex({ store: o.store, embedder: ranker.embedder });
+        rec = await index.search(query, sees, { stale: flags.all });
+    }
+    catch (err) {
+        if (err instanceof MemoryError) {
+            throw new CliError(err.message, EXIT.usage, err.hint);
+        }
+        throw err;
+    }
+    if (asJson) {
+        json({
+            query,
+            sees,
+            // Named field by field: the ranker carries the embedder itself,
+            // which is a client object and no part of an answer.
+            ranking: { by: ranker.by, model: ranker.model, reason: ranker.reason },
+            seeds: rec.seeds,
+            truncated: rec.truncated,
+            nodes: rec.nodes.map((n) => ({
+                id: n.node.id,
+                kind: n.node.kind,
+                score: n.score,
+                seed: n.seed,
+                via: n.via,
+                text: n.node.text,
+                file: n.node.file ? hostPath(o.dir, n.node.file) : undefined,
+            })),
+            edges: rec.edges,
+            // Verbatim, because it is the thing that went into a prompt.
+            block: renderRecollection(rec, { tagged: false }),
+        });
+        return;
+    }
+    if (flags['ids-only']) {
+        writeAll(rec.nodes.map((n) => n.node.id));
+        return;
+    }
+    if (!rec.nodes.length) {
+        note(`nothing recalled for ${text}`);
+        ranking(ranker);
+        return;
+    }
+    write(renderRecollection(rec, { tagged: false }));
+    write();
+    ranking(ranker);
+}
+/**
+ * The embedder the project ranks with. Reproducing a recall means reproducing
+ * its vectors, so the ref is resolved through the same alias table a run uses
+ * and the keyring is materialised the same way.
+ *
+ * What cannot be built falls back to term overlap rather than failing, because
+ * a graph whose credentials have gone missing is one worth looking at. The
+ * fallback is a different ranking, though, so it is reported rather than passed
+ * off as recall.
+ */
+async function vectoriser(o, override) {
+    // A memory with no vectors cannot be ranked by meaning whatever we build:
+    // embedding a query against an empty block finds nothing, which would read
+    // as "nothing is remembered" rather than "there is nothing to rank with".
+    if (!o.store.embedding) {
+        return { by: 'term overlap', reason: 'this memory holds no vectors' };
+    }
+    const config = o.at?.config;
+    const declared = override ?? config?.memory?.embedding ?? config?.embedding ?? o.store.embedding.model;
+    // The project's own file first, then the keyring — the order `zen run`
+    // uses, so a query embeds here exactly when it would embed there.
+    if (o.at) {
+        loadProjectEnv(o.at.root);
+    }
+    (await KeyStore.open()).materialize();
+    try {
+        const ref = config?.embeddings?.[declared] ?? declared;
+        const embedder = createEmbedder(ref);
+        return { embedder, by: 'meaning', model: embedder.id };
+    }
+    catch (err) {
+        return { by: 'term overlap', reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Which ranking that was. A lexical fallback is not what an agent sees, and a
+ * block that looked like recall without being it would send someone chasing a
+ * difference that exists only in this command.
+ */
+function ranking(r) {
+    if (r.by === 'meaning') {
+        note(dim(`ranked by meaning · ${r.model}`));
+        return;
+    }
+    note(yellow('ranked by term overlap — this is not the order an agent sees'));
+    if (r.reason) {
+        note(dim(`  ${r.reason}`));
+    }
+}
+/**
+ * Every label the graph uses. `recall` masks against a list rather than taking
+ * `undefined` for "no mask", so reading unmasked has to be spelled out — and
+ * spelling it out from the graph is exact, since a label nothing carries can
+ * hide nothing.
+ */
+function audiences(o) {
+    return [...new Set(o.store.graph.nodes().flatMap((n) => n.audience))];
+}
+/** Absent stays absent, so the engine's own default is the one on display. */
+function whole(value, flag, min = 1) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < min) {
+        throw usageError(`${flag} wants a whole number ${min} or more, got ${value}`, USAGE);
+    }
+    return n;
+}
+function threshold(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0 || n > 1) {
+        throw usageError(`--min-score wants a number from 0 to 1, got ${value}`, USAGE);
+    }
+    return n;
+}
+// ---------------------------------------------------------------------------
+// grep
+// ---------------------------------------------------------------------------
+/**
+ * The exhaustive read, and the counterpart to recall rather than a variant of
+ * it. Recall ranks, and a ranking returns the top of a list, so it cannot tell
+ * "there is nothing" from "nothing was close enough" — which is the question
+ * anyone actually has when they come to a memory looking for a name, a path or
+ * a command they think an agent wrote down.
+ */
+async function grep(o, rest, flags, asJson) {
+    const pattern = rest[0];
+    if (!pattern || rest.length > 1) {
+        throw usageError('grep takes exactly one pattern', 'zen memory grep <pattern>');
+    }
+    const limit = Number(flags.limit ?? LISTED);
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw usageError(`--limit wants a positive whole number, got ${flags.limit}`, USAGE);
+    }
+    for (const field of flags.in ?? []) {
+        if (!GREP_FIELDS.includes(field)) {
+            throw usageError(`--in wants one of ${GREP_FIELDS.join(', ')}, got ${field}`, USAGE);
+        }
+    }
+    let res;
+    try {
+        res = await grepMemory(o.store, pattern, {
+            // Unmasked, like everything else here: this is the person who owns
+            // the files, not an agent inside a run.
+            kinds: flags.kind ? [flags.kind] : undefined,
+            audience: flags.audience,
+            files: flags.files,
+            in: flags.in,
+            stale: flags.stale ? 'only' : flags.all ? 'include' : 'exclude',
+            regex: flags.regex,
+            caseSensitive: flags['case-sensitive'],
+            limit,
+        });
+    }
+    catch (err) {
+        if (err instanceof MemoryError) {
+            throw new CliError(err.message, EXIT.usage, err.hint);
+        }
+        throw err;
+    }
+    if (asJson) {
+        json({
+            found: res.found,
+            truncated: res.truncated,
+            matches: res.matches.map((m) => ({
+                id: m.node.id,
+                kind: m.node.kind,
+                stale: m.stale,
+                file: m.node.file ? hostPath(o.dir, m.node.file) : undefined,
+                hits: m.hits,
+                more: m.more,
+            })),
+            unsearched: res.skipped.map((s) => ({ ...s, path: hostPath(o.dir, s) })),
+        });
+        return;
+    }
+    if (flags['ids-only']) {
+        writeAll(res.matches.map((m) => m.node.id));
+        return;
+    }
+    if (!res.found) {
+        note(`nothing matches ${pattern}`);
+        unsearched(o, res.skipped);
+        return;
+    }
+    for (const m of res.matches) {
+        write(cyan(m.node.id) +
+            ' ' +
+            m.node.kind +
+            (m.stale ? ' ' + yellow('superseded') : '') +
+            (m.node.file ? ' ' + dim(hostPath(o.dir, m.node.file)) : ''));
+        writeAll(table(m.hits.map((h) => [`  ${dim(h.where + ':' + h.line)}`, clip(h.text, 120)])));
+        if (m.more) {
+            write(dim(`  … ${count(m.more, 'more line')} in this node`));
+        }
+        write();
+    }
+    if (res.truncated) {
+        note(dim(`${res.found - res.matches.length} more nodes — raise --limit`));
+    }
+    unsearched(o, res.skipped);
+}
+/**
+ * Named rather than counted. A file that was not read is a hole in an answer
+ * whose whole value is that it has none, so the ids have to be printable.
+ */
+function unsearched(o, skipped) {
+    if (!skipped.length) {
+        return;
+    }
+    write();
+    note(yellow(`${count(skipped.length, 'file')} not searched`));
+    writeAll(table(skipped.map((s) => [`  ${cyan(s.id)}`, dim(s.reason), hostPath(o.dir, s)])));
+}
+// ---------------------------------------------------------------------------
 // show
 // ---------------------------------------------------------------------------
 function show(o, ids, asJson) {
@@ -278,7 +616,11 @@ function show(o, ids, asJson) {
     }
     const links = o.store.graph.neighbors(id);
     if (asJson) {
-        json({ node, links, file: node.file ? hostPath(o.dir, node.file) : undefined });
+        json({
+            node: onHost(o, node),
+            links,
+            file: node.file ? hostPath(o.dir, node.file) : undefined,
+        });
         return;
     }
     write(bold(node.id) + ' ' + cyan(node.kind));
@@ -323,6 +665,82 @@ function show(o, ids, asJson) {
     })));
 }
 // ---------------------------------------------------------------------------
+// diff
+// ---------------------------------------------------------------------------
+async function diff(o, rest, cwd, asJson) {
+    if (rest.length !== 1) {
+        throw usageError('diff takes exactly one base memory', 'zen memory diff <base> [--dir <dir>]');
+    }
+    const at = resolve(cwd, rest[0]);
+    if (!existsSync(join(at, 'manifest.json'))) {
+        throw usageError(`${at} is not a memory`, 'no manifest.json in it');
+    }
+    const base = await MemoryStore.open(at, { lock: false });
+    try {
+        const d = diffMemories(base, o.store);
+        const mine = (n) => onHost(o, n);
+        const theirs = (n) => n.file ? { ...n, file: { ...n.file, path: hostPath(at, n.file) } } : n;
+        if (asJson) {
+            json({
+                ...d,
+                added: d.added.map((a) => ({ ...a, node: mine(a.node) })),
+                revised: d.revised.map((r) => ({ before: theirs(r.before), after: mine(r.after) })),
+                used: d.used.map((u) => ({ ...u, node: mine(u.node) })),
+                removed: d.removed.map(theirs),
+            });
+            return;
+        }
+        const twins = d.added.filter((a) => a.twin).length;
+        write(bold(o.dir) + dim(` against ${at} · nearest by ${d.by}`));
+        write();
+        write(`${bold('added')} ${d.added.length}` +
+            (twins ? ` · ${yellow(`${twins} already held`)}` : '') +
+            ` · ${bold('revised')} ${d.revised.length}` +
+            ` · ${bold('used')} ${d.used.length}` +
+            ` · ${bold('removed')} ${d.removed.length}` +
+            ` · ${bold('edges')} +${d.edges}`);
+        if (d.added.length) {
+            write();
+            write(dim('added'));
+            writeAll(textLast(d.added.map((a) => [
+                `  ${cyan(a.node.id)}`,
+                a.node.kind,
+                a.node.audience.join(','),
+                a.nearest
+                    ? `${a.twin ? yellow('twin of') : dim('near')} ${a.nearest.id} ${dim(a.nearest.score.toFixed(2))}`
+                    : dim('nothing near'),
+            ]), d.added.map((a) => a.node.text)));
+        }
+        if (d.revised.length) {
+            write();
+            write(dim('revised'));
+            writeAll(textLast(d.revised.map((r) => [
+                `  ${cyan(r.after.id)}`,
+                r.after.kind,
+                dim(`r${r.before.revision} → r${r.after.revision}`),
+            ]), d.revised.map((r) => r.after.text)));
+        }
+        if (d.used.length) {
+            write();
+            write(dim('used — returned by memory_load'));
+            writeAll(textLast(d.used.map((u) => [`  ${cyan(u.node.id)}`, u.node.kind, `${u.loads}×`]), d.used.map((u) => u.node.text)));
+        }
+        if (d.removed.length) {
+            write();
+            write(dim('removed'));
+            writeAll(textLast(d.removed.map((n) => [`  ${cyan(n.id)}`, n.kind]), d.removed.map((n) => n.text)));
+        }
+        if (d.supersedes.length) {
+            write();
+            write(dim('supersedes'));
+            writeAll(table(d.supersedes.map((s) => [`  ${cyan(s.source)}`, '→', cyan(s.target)])));
+        }
+    }
+    finally {
+        base.release();
+    }
+}
+// ---------------------------------------------------------------------------
 // export
 // ---------------------------------------------------------------------------
 async function write_(o, rest, flags, cwd, asJson) {
@@ -331,7 +749,8 @@ async function write_(o, rest, flags, cwd, asJson) {
     }
     const named = rest[0] ?? flags.out ?? 'memory.html';
     const target = isAbsolute(named) ? named : resolve(cwd, named);
-    const report = await buildMemoryReport(o.store, { title: `${o.project} · memory` });
+    const built = await buildMemoryReport(o.store, { title: `${o.project} · memory` });
+    const report = { ...built, nodes: built.nodes.map((n) => onHost(o, n)) };
     await writeFile(target, renderMemoryHtml(report), 'utf8');
     if (asJson) {
         json({ path: target, nodes: report.nodes.length, edges: report.edges.length });
@@ -390,7 +809,7 @@ async function merge(o, dirs, flags, cwd, asJson) {
     }
     catch (err) {
         if (err instanceof MergeConflicts) {
-            throw diverged(err, cwd, asJson);
+            throw diverged(err, asJson);
         }
         throw err;
     }
@@ -401,7 +820,7 @@ async function merge(o, dirs, flags, cwd, asJson) {
     writeAll(table([
         [dim('memory'), dim('nodes'), dim('new'), dim('shared'), dim('folded'), dim('files')],
         ...report.sources.map((s) => [
-            near(s.dir, cwd),
+            s.dir,
             String(s.nodes),
             s.added ? green(String(s.added)) : '0',
             String(s.shared),
@@ -422,7 +841,7 @@ async function merge(o, dirs, flags, cwd, asJson) {
  * point of stopping is that a person decides, and they cannot decide from a
  * count.
  */
-function diverged(err, cwd, asJson) {
+function diverged(err, asJson) {
     if (asJson) {
         json({ error: err.message, conflicts: err.conflicts });
     }
@@ -431,7 +850,7 @@ function diverged(err, cwd, asJson) {
             cyan(c.id),
             dim(`r${c.mine} ↔ r${c.theirs}`),
             clip(c.text, 48),
-            dim(near(c.dir, cwd)),
+            dim(c.dir),
         ])));
         write();
     }
@@ -488,9 +907,19 @@ function clip(text, n) {
     const one = text.replace(/\s+/g, ' ').trim();
     return one.length > n ? one.slice(0, n - 1) + '…' : one;
 }
-/** A path as it was probably typed: relative when it is below here, absolute when it is not. */
-function near(dir, cwd) {
-    const rel = relative(cwd, dir);
-    return rel && !rel.startsWith('..') ? rel : dir;
+/**
+ * A table whose last column is the text: cut to what the terminal has left,
+ * and whole when nobody is looking at a terminal — a pipe or an agent wants all of it.
+ */
+function textLast(rows, texts) {
+    const widths = rows[0]?.map((_, c) => Math.max(...rows.map((r) => plain(r[c] ?? '').length)));
+    const room = process.stdout.isTTY
+        ? Math.max(24, (process.stdout.columns || 120) - (widths ?? []).reduce((t, w) => t + w + 2, 0))
+        : Infinity;
+    return table(rows.map((r, i) => [...r, clip(texts[i] ?? '', room)]));
+}
+/** The stored `/memory/<id>.<ext>` is the agent's mount path; a terminal needs the host one. */
+function onHost(o, n) {
+    return n.file ? { ...n, file: { ...n.file, path: hostPath(o.dir, n.file) } } : n;
 }
 //# sourceMappingURL=memory.js.map