@zenera/cli 1.1.11 → 1.1.12

package/README.md

@@ -134,17 +134,27 @@ Credentials live in `$HOME`, so the project never contains a secret.
 
 ```
 my-project/
+    SPECIFICATION.md             what this is for — the intent
     INSTRUCTIONS.md              house rules, prepended to every agent
     agents.yaml                  who exists, what they may reach for
     agents/
         prompts/<name>.md        each agent's own brief
         skills/<name>/           knowledge loaded on demand, not always-on
+    assets/                      reference material, read-only at /assets
+    sandbox/Dockerfile           the container commands run in
+    scripts/_setup.sh            the one command that initialises the project
     sessions/                    one workspace, memory and trajectory each
         <id>/
             workspace/           what the agents can read and write
             runs/<id>/           input, output, state, report.html, meta
 ```
 
+`SPECIFICATION.md` comes first because the rest implements it. The one `zen init`
+writes is a true specification of the project it just scaffolded; replace it with
+what you are building, then run `/sync-with-spec` in your editor to make the
+files match. See
+[docs/specification.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/specification.md).
+
 `zen init` also writes `.github/copilot-instructions.md` — a standing brief that
 explains this runtime to whatever coding agent you have open in that folder, so
 you are not expected to hand-author `agents.yaml`.
@@ -160,6 +170,7 @@ you are not expected to hand-author `agents.yaml`.
 | `models`  | What this machine can use — list, search, test, pick.                |
 | `run`     | Runs the project — the TUI on a terminal, a single answer otherwise. |
 | `inspect` | Opens or rebuilds a run's `report.html`.                             |
+| `memory`  | What the agents remember — size, listing, one node, or a whole page. |
 | `check`   | Validates the project and every file it names, and asks the models.  |
 | `sandbox` | Checks and prepares the container that command-line tools run in.    |
 | `cache`   | What work has been kept, and getting rid of it.                      |
@@ -459,11 +470,20 @@ terminal:
 
 ## Documentation
 
+[docs/specification.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/specification.md)
+— writing the specification the project implements ·
 [docs/projects.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/projects.md)
 — the folder a project is ·
 [docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md)
 — every key in the configuration file.
 
+[docs/knowledge.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/knowledge.md)
+— a searchable document index ·
+[docs/integrations.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/integrations.md)
+— an API description, searchable and mockable ·
+[docs/memory.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/memory.md)
+— what agents keep between sessions.
+
 ## License
 
 Early days and moving fast — issues, questions and pull requests are welcome.

package/dist/banner.js

@@ -8,64 +8,80 @@ import { dim, note } from "./term.js";
 // terminal — a pipeline asking for the answer gets the answer, and a CI log is
 // not decorated with block letters.
 //
-// The font is here rather than pulled in as a dependency because it is a
-// kilobyte of constant and the whole CLI is otherwise Node's own. Two things
-// about its shape are deliberate: the stroke is **two cells wide**, because a
-// one-cell stem in a dotted fill reads as noise rather than as a letter, and
-// the ink is the dotted block (U+2592) rather than a solid one, which makes a
-// thick stroke a screen-print instead of a slab.
+// The font is here rather than pulled in as a dependency because it is a couple
+// of kilobytes of constant and the whole CLI is otherwise Node's own. It is the
+// shadowed block face: a solid stroke lit from the top left with a box-drawing
+// bevel down its right side and along its foot, so the letters read as raised
+// rather than as a texture. Glyphs are variable width and carry their own
+// spacing, so they abut directly — the gap belongs to the letter, not the join.
 //
 // A terminal too narrow for the art gets the wordmark on one line. A banner
 // that wraps is worse than no banner.
 // ---------------------------------------------------------------------------
-const HEIGHT = 5;
-const WIDTH = 6;
+const HEIGHT = 6;
+/** Between the two words. Wide enough that they read as two, not as one. */
+const GAP = 3;
+/** A left margin, so the art does not start against the edge of the screen. */
+const INDENT = 2;
 const FONT = {
-    A: [' ▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒', '▒▒  ▒▒'],
-    B: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ '],
-    C: [' ▒▒▒▒▒', '▒▒    ', '▒▒    ', '▒▒    ', ' ▒▒▒▒▒'],
-    D: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒▒▒▒ '],
-    E: ['▒▒▒▒▒▒', '▒▒    ', '▒▒▒▒▒ ', '▒▒    ', '▒▒▒▒▒▒'],
-    F: ['▒▒▒▒▒▒', '▒▒    ', '▒▒▒▒▒ ', '▒▒    ', '▒▒    '],
-    G: [' ▒▒▒▒▒', '▒▒    ', '▒▒ ▒▒▒', '▒▒  ▒▒', ' ▒▒▒▒▒'],
-    H: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒', '▒▒  ▒▒'],
-    I: ['▒▒▒▒▒▒', '  ▒▒  ', '  ▒▒  ', '  ▒▒  ', '▒▒▒▒▒▒'],
-    J: ['▒▒▒▒▒▒', '   ▒▒ ', '   ▒▒ ', '▒▒ ▒▒ ', ' ▒▒▒  '],
-    K: ['▒▒  ▒▒', '▒▒ ▒▒ ', '▒▒▒▒  ', '▒▒ ▒▒ ', '▒▒  ▒▒'],
-    L: ['▒▒    ', '▒▒    ', '▒▒    ', '▒▒    ', '▒▒▒▒▒▒'],
-    M: ['▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒', '▒▒  ▒▒'],
-    N: ['▒▒  ▒▒', '▒▒▒ ▒▒', '▒▒▒▒▒▒', '▒▒ ▒▒▒', '▒▒  ▒▒'],
-    O: [' ▒▒▒▒ ', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', ' ▒▒▒▒ '],
-    P: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ ', '▒▒    ', '▒▒    '],
-    Q: [' ▒▒▒▒ ', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒ ▒▒ ', ' ▒▒ ▒▒'],
-    R: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ ', '▒▒ ▒▒ ', '▒▒  ▒▒'],
-    S: [' ▒▒▒▒▒', '▒▒    ', ' ▒▒▒▒ ', '    ▒▒', '▒▒▒▒▒ '],
-    T: ['▒▒▒▒▒▒', '  ▒▒  ', '  ▒▒  ', '  ▒▒  ', '  ▒▒  '],
-    U: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', ' ▒▒▒▒ '],
-    V: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', ' ▒▒▒▒ ', '  ▒▒  '],
-    W: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒'],
-    X: ['▒▒  ▒▒', ' ▒▒▒▒ ', '  ▒▒  ', ' ▒▒▒▒ ', '▒▒  ▒▒'],
-    Y: ['▒▒  ▒▒', ' ▒▒▒▒ ', '  ▒▒  ', '  ▒▒  ', '  ▒▒  '],
-    Z: ['▒▒▒▒▒▒', '   ▒▒ ', '  ▒▒  ', ' ▒▒   ', '▒▒▒▒▒▒'],
+    A: [' █████╗ ', '██╔══██╗', '███████║', '██╔══██║', '██║  ██║', '╚═╝  ╚═╝'],
+    B: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔══██╗', '██████╔╝', '╚═════╝ '],
+    C: [' ██████╗', '██╔════╝', '██║     ', '██║     ', '╚██████╗', ' ╚═════╝'],
+    D: ['██████╗ ', '██╔══██╗', '██║  ██║', '██║  ██║', '██████╔╝', '╚═════╝ '],
+    E: ['███████╗', '██╔════╝', '█████╗  ', '██╔══╝  ', '███████╗', '╚══════╝'],
+    F: ['███████╗', '██╔════╝', '█████╗  ', '██╔══╝  ', '██║     ', '╚═╝     '],
+    G: [' ██████╗ ', '██╔════╝ ', '██║  ███╗', '██║   ██║', '╚██████╔╝', ' ╚═════╝ '],
+    H: ['██╗  ██╗', '██║  ██║', '███████║', '██╔══██║', '██║  ██║', '╚═╝  ╚═╝'],
+    I: ['██╗', '██║', '██║', '██║', '██║', '╚═╝'],
+    J: ['     ██╗', '     ██║', '     ██║', '██   ██║', '╚█████╔╝', ' ╚════╝ '],
+    K: ['██╗  ██╗', '██║ ██╔╝', '█████╔╝ ', '██╔═██╗ ', '██║  ██╗', '╚═╝  ╚═╝'],
+    L: ['██╗     ', '██║     ', '██║     ', '██║     ', '███████╗', '╚══════╝'],
+    M: ['███╗   ███╗', '████╗ ████║', '██╔████╔██║', '██║╚██╔╝██║', '██║ ╚═╝ ██║', '╚═╝     ╚═╝'],
+    N: ['███╗   ██╗', '████╗  ██║', '██╔██╗ ██║', '██║╚██╗██║', '██║ ╚████║', '╚═╝  ╚═══╝'],
+    O: [' ██████╗ ', '██╔═══██╗', '██║   ██║', '██║   ██║', '╚██████╔╝', ' ╚═════╝ '],
+    P: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔═══╝ ', '██║     ', '╚═╝     '],
+    Q: [' ██████╗ ', '██╔═══██╗', '██║   ██║', '██║▄▄ ██║', '╚██████╔╝', ' ╚══▀▀═╝ '],
+    R: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔══██╗', '██║  ██║', '╚═╝  ╚═╝'],
+    S: ['███████╗', '██╔════╝', '███████╗', '╚════██║', '███████║', '╚══════╝'],
+    T: ['████████╗', '╚══██╔══╝', '   ██║   ', '   ██║   ', '   ██║   ', '   ╚═╝   '],
+    U: ['██╗   ██╗', '██║   ██║', '██║   ██║', '██║   ██║', '╚██████╔╝', ' ╚═════╝ '],
+    V: ['██╗   ██╗', '██║   ██║', '██║   ██║', '╚██╗ ██╔╝', ' ╚████╔╝ ', '  ╚═══╝  '],
+    W: ['██╗    ██╗', '██║    ██║', '██║ █╗ ██║', '██║███╗██║', '╚███╔███╔╝', ' ╚══╝╚══╝ '],
+    X: ['██╗  ██╗', '╚██╗██╔╝', ' ╚███╔╝ ', ' ██╔██╗ ', '██╔╝ ██╗', '╚═╝  ╚═╝'],
+    Y: ['██╗   ██╗', '╚██╗ ██╔╝', ' ╚████╔╝ ', '  ╚██╔╝  ', '   ██║   ', '   ╚═╝   '],
+    Z: ['███████╗', '╚══███╔╝', '  ███╔╝ ', ' ███╔╝  ', '███████╗', '╚══════╝'],
 };
-const BLANK = ' '.repeat(WIDTH);
-/** One word as five rows of equal length — so two words line up when joined. */
+const BLANK = ['    ', '    ', '    ', '    ', '    ', '    '];
+/** One word as six rows of equal length — so two words line up when joined. */
 function big(word) {
     const rows = new Array(HEIGHT).fill('');
     for (const ch of word.toUpperCase()) {
-        const glyph = FONT[ch];
+        const glyph = FONT[ch] ?? BLANK;
         for (let r = 0; r < HEIGHT; r++) {
-            rows[r] += `${glyph?.[r] ?? BLANK} `;
+            rows[r] += glyph[r];
         }
     }
     return rows;
 }
 /** A wordmark rather than a sentence, so the letters are set apart. */
 const spaced = (s) => [...s.toUpperCase()].join(' ');
-/** The name, in the brightest thing the terminal has. */
-const bright = (s) => styleText(['bold', 'whiteBright'], s);
-/** The half that carries the colour. */
-const neon = (s) => styleText(['bold', 'magentaBright'], s);
+/** Whether anything should be coloured at all — `styleText`'s own answer. */
+const styling = () => styleText('dim', '.') !== '.';
+const RESET = '\u001b[0m';
+const HEAD = { face: '\u001b[1;38;5;231m', shade: '\u001b[0;38;5;244m' };
+const ACCENT = { face: '\u001b[1;38;5;208m', shade: '\u001b[0;38;5;130m' };
+/** Runs of stroke and runs of bevel, alternating; spaces stay unstyled. */
+const RUNS = /[█▀▄]+|[^█▀▄ ]+/g;
+const isStroke = (run) => /[█▀▄]/.test(run);
+/**
+ * Two tones per word — without the darker bevel the letter is a flat outline
+ * and the shadow reads as part of the stroke.
+ */
+const paint = (text, tone) => styling()
+    ? text.replace(RUNS, (run) => `${isStroke(run) ? tone.face : tone.shade}${run}${RESET}`)
+    : text;
+/** The wordmark has no bevel to shade, so it is all face. */
+const flat = (text, tone) => styling() ? `${tone.face}${text}${RESET}` : text;
 export const NEO_BANNER = {
     head: 'Zenera',
     accent: 'Neo',
@@ -76,17 +92,23 @@ export function bannerLines(text, columns = process.stderr.columns || 80) {
     // Trimmed: the widest accent row is the banner's right edge, and a pad left
     // inside a styled string cannot be trimmed away later.
     const accent = big(text.accent).map((row) => row.trimEnd());
-    const width = 2 + head[0].length + Math.max(...accent.map((row) => row.length));
-    const foot = `  ${dim(spaced(text.subtitle))}`;
+    const margin = ' '.repeat(INDENT);
+    const width = INDENT + head[0].length + GAP + Math.max(...accent.map((row) => row.length));
     if (width > columns) {
-        return [` ${bright(text.head.toUpperCase())} ${neon(text.accent.toUpperCase())}`, foot];
+        return [
+            `${margin}${flat(text.head.toUpperCase(), HEAD)} ${flat(text.accent.toUpperCase(), ACCENT)}`,
+            `${margin}${dim(spaced(text.subtitle))}`,
+        ];
     }
     const lines = [];
     for (let r = 0; r < HEIGHT; r++) {
-        lines.push(` ${bright(head[r])} ${neon(accent[r])}`);
+        lines.push(`${margin}${paint(head[r], HEAD)}${' '.repeat(GAP)}${paint(accent[r], ACCENT)}`);
     }
+    // Rules on both sides, centred under the art: the subtitle is a caption,
+    // and without them a short line of spaced capitals floats.
+    const caption = `───  ${spaced(text.subtitle)}  ───`;
     lines.push('');
-    lines.push(foot);
+    lines.push(`${' '.repeat(Math.max(INDENT, Math.round((width - caption.length) / 2)))}${dim(caption)}`);
     return lines;
 }
 /** Narration, and only for someone watching. */

package/dist/commands/index.js

@@ -4,6 +4,7 @@ import { init } from "./init.js";
 import { inspect } from "./inspect.js";
 import { key } from "./key.js";
 import { list } from "./list.js";
+import { memory } from "./memory.js";
 import { models } from "./models.js";
 import { open } from "./open.js";
 import { run } from "./run.js";
@@ -23,6 +24,7 @@ export const COMMANDS = {
     models,
     check,
     inspect,
+    memory,
     sandbox,
     cache,
     version,
@@ -36,6 +38,7 @@ export const ALIASES = {
     validate: 'check',
     doctor: 'check',
     report: 'inspect',
+    mem: 'memory',
     edit: 'open',
     code: 'open',
     mock: 'faker',

package/dist/commands/init.js

@@ -96,10 +96,14 @@ export const init = {
     summary: 'Create a project here, or in <dir>, and register it.',
     usage: USAGE,
     details: [
-        'Writes INSTRUCTIONS.md, agents.yaml and agents/, then records the',
-        'directory so `zen list` and `zen open` can find it by name. Editor files',
-        '(.vscode/settings.json and the .github/ tree) are written',
-        'alongside, replacing any already there.',
+        'Writes SPECIFICATION.md, INSTRUCTIONS.md, agents.yaml, agents/ and',
+        'scripts/, then records the directory so `zen list` and `zen open` can',
+        'find it by name. Editor files (.vscode/settings.json and the .github/',
+        'tree) are written alongside, replacing any already there.',
+        '',
+        'SPECIFICATION.md states what the project is for and what it may do,',
+        'and describes the one that was just written. Say what you are building',
+        'there, then run /sync-with-spec in your editor to make the rest match.',
         '',
         'The default agent gets the file tools and a sandboxed shell, plus',
         '`exa:*` when the keyring holds an Exa key. Without --model, the',

package/dist/commands/memory.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../command.ts';
+export declare const memory: Command;
+//# sourceMappingURL=memory.d.ts.map

package/dist/commands/memory.js

@@ -0,0 +1,375 @@
+import { ALL_AGENTS, buildMemoryReport, hostPath, memoryDir, MemoryIndex, MemoryStore, readProjectConfig, renderMemoryHtml, } from '@zenera/neo';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { parse } from "../args.js";
+import { project as resolveProject } from "../resolve.js";
+import { ago, bold, bytes, confirm, count, cyan, dim, green, isInteractive, json, note, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen memory [stats|ls|show|export|forget] [args] [options]';
+const SUBCOMMANDS = ['stats', 'ls', 'show', 'export', 'forget'];
+/** Enough to see the shape of it; the rest is a number. */
+const LISTED = 30;
+// ---------------------------------------------------------------------------
+// zen memory
+//
+// The graph from outside the agents, and the reason it needs a command is that
+// there is otherwise no way to answer the question memory always eventually
+// raises: *why did it recall that?* Recall is masked, ranked and truncated by
+// design, so what an agent sees is never the whole picture — and when the
+// picture is what is wrong, you need the part that was hidden.
+//
+// So everything here reads the graph unmasked. That is safe because it is
+// local: this command is a person at a terminal in the project directory, not
+// 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.
+// ---------------------------------------------------------------------------
+export const memory = {
+    summary: 'What the agents remember, and getting rid of it.',
+    usage: USAGE,
+    details: [
+        '  stats                  Size, vocabulary, and whether it is embedded.',
+        '  ls                     Nodes, newest first. Changes nothing.',
+        '  show <id>              One node in full, with what it links to.',
+        '  export [file]          The whole graph as one HTML page.',
+        '  forget <id...>         Remove nodes, their vectors and their files.',
+        '',
+        '  --project <name|dir>   Which project. Defaults to the one you are in.',
+        '  --kind <name>          Only this kind of node.',
+        '  --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.',
+        '  --out <file>           Where `export` writes. Default memory.html.',
+        '  --open                 Open the exported page.',
+        '  --yes                  Do not ask before removing.',
+        '',
+        'Everything here reads the graph *unmasked* — every audience, including',
+        'what no agent can see. That is the point: when a mask is the thing',
+        'that is wrong, the hidden part is what you need to look at.',
+        '',
+        '`export` is the one to reach for. It writes a single self-contained',
+        'page: the node list on the left, the graph in the middle, and whatever',
+        'you click on the right, file contents and all.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            project: { type: 'string' },
+            kind: { type: 'string' },
+            audience: { type: 'string' },
+            files: { type: 'boolean' },
+            stale: { type: 'boolean' },
+            limit: { type: 'string' },
+            out: { type: 'string' },
+            open: { type: 'boolean' },
+            yes: { type: 'boolean' },
+        }, USAGE);
+        const what = positionals[0] ?? 'stats';
+        if (!SUBCOMMANDS.includes(what)) {
+            throw usageError(`unknown subcommand: ${what}`, USAGE);
+        }
+        const rest = positionals.slice(1);
+        const opened = await open(ctx.cwd, values.project);
+        try {
+            switch (what) {
+                case 'stats':
+                    return stats(opened, ctx.json);
+                case 'ls':
+                    return list(opened, values, ctx.json);
+                case 'show':
+                    return show(opened, rest, ctx.json);
+                case 'export':
+                    return await write_(opened, rest, values, ctx.cwd, ctx.json);
+                default:
+                    return await forget(opened, rest, values, ctx.json);
+            }
+        }
+        finally {
+            opened.store.release();
+        }
+    },
+};
+/**
+ * The store, opened directly rather than through `loadProject`. Loading the
+ * project would resolve models and read every prompt file to inspect a graph
+ * that needs none of it — and would fail on a project whose credentials are
+ * missing, which is exactly when someone is debugging.
+ */
+async function open(cwd, want) {
+    const project = await resolveProject({ cwd, project: want });
+    const { config } = readProjectConfig(project.dir);
+    const dir = memoryDir(project.dir, config);
+    if (!dir) {
+        throw usageError(`${project.name} has no memory`, 'give an agent `memory: true` in agents.yaml, or add a `memory:` block');
+    }
+    if (!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 };
+}
+// ---------------------------------------------------------------------------
+// stats
+// ---------------------------------------------------------------------------
+function stats(o, asJson) {
+    const nodes = o.store.graph.nodes();
+    const edges = o.store.graph.edges();
+    const stale = o.store.graph.superseded();
+    const vectors = o.store.vectors;
+    const files = nodes.filter((n) => n.file);
+    const byKind = tally(nodes.map((n) => n.kind));
+    const byRelation = tally(edges.map((e) => e.relation));
+    const byAudience = tally(nodes.flatMap((n) => n.audience));
+    if (asJson) {
+        json({
+            dir: o.dir,
+            nodes: nodes.length,
+            edges: edges.length,
+            superseded: stale.size,
+            files: {
+                count: files.length,
+                bytes: files.reduce((t, n) => t + (n.file?.bytes ?? 0), 0),
+            },
+            embedding: o.store.embedding,
+            vectors: vectors ? { rows: vectors.rows, dims: vectors.dims } : undefined,
+            kinds: byKind,
+            relations: byRelation,
+            audiences: byAudience,
+        });
+        return;
+    }
+    if (!nodes.length) {
+        note(`nothing remembered yet ${dim(o.dir)}`);
+        return;
+    }
+    write(bold(o.project) + dim(' · ' + o.dir));
+    write();
+    writeAll(table([
+        [dim('nodes'), String(nodes.length)],
+        [dim('edges'), String(edges.length)],
+        [dim('superseded'), String(stale.size)],
+        [
+            dim('files'),
+            files.length
+                ? `${files.length} · ${bytes(files.reduce((t, n) => t + (n.file?.bytes ?? 0), 0))}`
+                : '0',
+        ],
+        [
+            dim('embedding'),
+            o.store.embedding
+                ? `${o.store.embedding.model} ${dim(o.store.embedding.dimensions + 'd')}`
+                : yellow('none — recall falls back to term overlap'),
+        ],
+        [dim('vectors'), vectors ? `${vectors.rows} rows` : dim('—')],
+    ]));
+    // A node without a vector cannot be found by meaning, only by luck. It is
+    // the one silent failure this store has, so it is called out by name.
+    if (vectors && vectors.rows < nodes.length) {
+        write();
+        note(yellow(`${count(nodes.length - vectors.rows, 'node')} with no vector`));
+    }
+    section('kinds', byKind);
+    section('relations', byRelation);
+    section('audiences', byAudience);
+}
+function section(title, counts) {
+    const rows = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+    if (!rows.length) {
+        return;
+    }
+    write();
+    write(dim(title));
+    writeAll(table(rows.map(([k, n]) => [`  ${cyan(k)}`, String(n)])));
+}
+function tally(values) {
+    const out = {};
+    for (const v of values) {
+        out[v] = (out[v] ?? 0) + 1;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// ls
+// ---------------------------------------------------------------------------
+function list(o, flags, asJson) {
+    const stale = o.store.graph.superseded();
+    const limit = Number(flags.limit ?? LISTED);
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw usageError(`--limit wants a positive whole number, got ${flags.limit}`, USAGE);
+    }
+    const all = o.store.graph
+        .nodes()
+        .filter((n) => !flags.kind || n.kind === flags.kind)
+        .filter((n) => !flags.audience || n.audience.includes(flags.audience))
+        .filter((n) => !flags.files || n.file)
+        .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) });
+        return;
+    }
+    if (!all.length) {
+        note('nothing matches');
+        return;
+    }
+    writeAll(table(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') : '',
+    ])));
+    if (all.length > limit) {
+        write();
+        note(dim(`${all.length - limit} more — raise --limit, or use \`zen memory export\``));
+    }
+}
+// ---------------------------------------------------------------------------
+// show
+// ---------------------------------------------------------------------------
+function show(o, ids, asJson) {
+    const id = ids[0];
+    if (!id || ids.length > 1) {
+        throw usageError('show takes exactly one id', 'zen memory show <id>');
+    }
+    const node = o.store.graph.get(id);
+    if (!node) {
+        throw usageError(`no node ${id}`, 'list them with `zen memory ls`');
+    }
+    const links = o.store.graph.neighbors(id);
+    if (asJson) {
+        json({ node, links, file: node.file ? hostPath(o.dir, node.file) : undefined });
+        return;
+    }
+    write(bold(node.id) + ' ' + cyan(node.kind));
+    write();
+    writeAll(table([
+        [dim('revision'), String(node.revision)],
+        [dim('used'), `${node.useCount}× · last ${ago(node.lastUsedAt)}`],
+        [dim('created'), `${node.createdAt} ${dim(ago(node.createdAt))}`],
+        [dim('updated'), node.updatedAt],
+        [dim('audience'), node.audience.join(', ')],
+    ]));
+    write();
+    write(node.text);
+    if (node.metadata) {
+        write();
+        write(dim('metadata'));
+        write(JSON.stringify(node.metadata, null, 2));
+    }
+    if (node.file) {
+        write();
+        write(dim('file'));
+        writeAll(table([
+            [dim('  path'), hostPath(o.dir, node.file)],
+            [dim('  size'), bytes(node.file.bytes)],
+            [dim('  sha256'), node.file.sha256],
+        ]));
+    }
+    write();
+    write(dim(`links (${links.length})`));
+    if (!links.length) {
+        note(dim('  nothing points here and it points nowhere'));
+        return;
+    }
+    writeAll(table(links.map((e) => {
+        const out = e.source === id;
+        const other = out ? e.target : e.source;
+        return [
+            `  ${out ? '→' : '←'} ${yellow(e.relation)}`,
+            cyan(other),
+            clip(o.store.graph.get(other)?.text ?? '', 48),
+        ];
+    })));
+}
+// ---------------------------------------------------------------------------
+// export
+// ---------------------------------------------------------------------------
+async function write_(o, rest, flags, cwd, asJson) {
+    if (rest.length > 1) {
+        throw usageError('export takes at most one file name', 'zen memory export [file]');
+    }
+    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` });
+    await writeFile(target, renderMemoryHtml(report), 'utf8');
+    if (asJson) {
+        json({ path: target, nodes: report.nodes.length, edges: report.edges.length });
+    }
+    else {
+        note(`${green('wrote')} ${target} ${dim(`· ${count(report.nodes.length, 'node')}, ${count(report.edges.length, 'edge')}`)}`);
+    }
+    if (flags.open) {
+        reveal(target);
+    }
+}
+/**
+ * Handing a path to the platform opener. `spawn` without a shell, so the path
+ * is an argument rather than something a shell gets to interpret.
+ */
+function reveal(target) {
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'explorer'
+            : 'xdg-open';
+    spawn(command, [target], { stdio: 'ignore', detached: true }).unref();
+}
+// ---------------------------------------------------------------------------
+// forget
+// ---------------------------------------------------------------------------
+/**
+ * The only destructive thing here, and it is deliberately not the way to fix a
+ * memory that turned out wrong — that is a new node and a `SUPERSEDES` edge,
+ * which keeps the reason it changed. This is for what should never have been
+ * written down: it takes the node, its vector and its file bytes together.
+ */
+async function forget(o, ids, flags, asJson) {
+    if (!ids.length) {
+        throw usageError('forget takes at least one id', 'zen memory forget <id...>');
+    }
+    const found = [];
+    for (const id of ids) {
+        const node = o.store.graph.get(id);
+        if (!node) {
+            throw usageError(`no node ${id}`, 'list them with `zen memory ls`');
+        }
+        found.push(node);
+    }
+    if (!flags.yes) {
+        if (!isInteractive()) {
+            throw usageError('refusing to remove without confirmation', 'pass --yes');
+        }
+        writeAll(table(found.map((n) => [cyan(n.id), n.kind, clip(n.text, 56)])));
+        write();
+        if (!(await confirm(`Forget ${count(found.length, 'node')}?`))) {
+            note('nothing removed');
+            return;
+        }
+    }
+    // The vector and the bytes go with the node, which `MemoryIndex` already
+    // guarantees; `sees` is every audience in the graph, because this command
+    // is the person who owns the files rather than an agent inside a run.
+    const index = new MemoryIndex({ store: o.store });
+    await index.forget(found.map((n) => n.id), [ALL_AGENTS, ...new Set(o.store.graph.nodes().flatMap((n) => n.audience))]);
+    if (asJson) {
+        json({ forgotten: found.map((n) => n.id) });
+    }
+    else {
+        note(`${green('forgot')} ${count(found.length, 'node')}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Shared
+// ---------------------------------------------------------------------------
+function clip(text, n) {
+    const one = text.replace(/\s+/g, ' ').trim();
+    return one.length > n ? one.slice(0, n - 1) + '…' : one;
+}
+//# sourceMappingURL=memory.js.map