@bli-cockpit/cli 0.2.97 → 0.2.98

package/dist/commands/local-args-collector-status.js

@@ -11,6 +11,7 @@
 import { DEFAULT_AUTOSTART_INTERVAL_SECONDS } from "../autostart.js";
 import { assertNoPositionals, normalizeUrl, optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, workRootFlagValue, } from "./local-arg-values.js";
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+import { MEMORY_STORE_ACTIONS, parseMemoryStoreArgs, } from "./local-args-tower-memory.js";
 export function parseStatusArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -164,11 +165,30 @@ export function parseAgentRulesArgs(args) {
     };
 }
 /**
- * BLI-3580. `install` is the default action on purpose: this command exists to
- * be run unasked (by `do-everything` and by the sync tick), and a bare
- * `cockpit memory` should do the thing rather than print usage.
+ * BLI-3580, amended by BLI-4047.
+ *
+ * `cockpit memory` is now SIX verbs behind one noun: the two that configure
+ * this machine (`install`, `status`), the experience log (`log`), and the four
+ * that read and write the memory store itself (`search`, `save`, `update`,
+ * `forget`, parsed next door in `local-args-tower-memory.ts`).
+ *
+ * **A bare `cockpit memory` prints the verb list; it no longer installs.**
+ * BLI-3580 made `install` the default because the command is run unasked by
+ * `do-everything` and by the sync tick — but those callers build
+ * `{ kind: "memory", action: "install" }` in code (`doctor-registration.ts`,
+ * `sync-followups-memory.ts`, `onboard-completion.ts`) and never pass through
+ * this parser. The only caller the default ever served was a PERSON typing the
+ * noun to find out what it does, and what they got was an MCP server and three
+ * hooks registered on their machine. Installing stays one word away.
  */
 export function parseMemoryArgs(args) {
+    // The verb word first, always: reading it off `args[0]` rather than "the
+    // first token without a leading dash" is what keeps `cockpit memory --home
+    // /tmp/x status` from being read as the verb `/tmp/x`.
+    const first = args[0];
+    if (first !== undefined && MEMORY_STORE_ACTIONS.has(first)) {
+        return parseMemoryStoreArgs(first, args);
+    }
     const values = parseNamedArgs(args, {
         allowedFlags: ["--home", "--dashboard-url", "--dry-run", "--json", "--store", "--reason-stdin"],
         valueFlags: ["--home", "--dashboard-url", "--store"],
@@ -192,9 +212,10 @@ export function parseMemoryArgs(args) {
     if (values.positionals.length > 1) {
         throw new Error("memory accepts at most one action (install|status).");
     }
-    const action = values.positionals[0] ?? "install";
-    if (action !== "install" && action !== "status") {
-        throw new Error("memory action must be install or status.");
+    // BLI-4047: no positional means "tell me what this noun does", not "install".
+    const action = values.positionals[0] ?? "help";
+    if (action !== "install" && action !== "status" && action !== "help") {
+        throw new Error("memory action must be install, status, help, log, search, save, update, or forget.");
     }
     return {
         kind: "memory",

package/dist/commands/local-args-tower-memory.js

@@ -0,0 +1,151 @@
+/**
+ * `cockpit memory search|save|update|forget` — the argument table (BLI-4047).
+ *
+ * BLI Memory was the one Tower surface with no command-line door: the browser
+ * had one, the `bli-memory` MCP server had one, and a person or a script at a
+ * terminal had nothing. These four verbs are the twins of that server's four
+ * tools, over the SAME `/api/memory/*` doors.
+ *
+ * Two rules this table exists to enforce, both of them the same discipline
+ * `cockpit docs create` and `cockpit notes paste` already follow:
+ *
+ *  - **A body never travels on the command line.** `save`, `update` and
+ *    `forget --content` read their text from stdin (or `--file`, which is the
+ *    safest way to say it on Windows). An argument list is visible in `ps`,
+ *    lands in a shell history file, and is quoted wrong on the first line that
+ *    contains a newline. A QUERY is not a body — `search` takes one
+ *    positional, the same way `cockpit search` and `cockpit docs list --query`
+ *    do — but the text of a memory always is.
+ *  - **The container tag is derived, not typed.** Omit `--container` and the
+ *    tag comes from this repository, resolved by `@bli-cockpit/memory-mcp`'s
+ *    own resolver, so a memory saved from the terminal lands in the same space
+ *    the MCP server and the hooks write to. `--container` may be repeated on
+ *    `search` alone, because searching two spaces is meaningful and saving
+ *    into two is not.
+ *
+ * The verbs live in their own `kind` (`memory-store`) rather than widening
+ * `kind: "memory"`, because that command acts on THIS MACHINE (it registers an
+ * MCP server and three hooks) and these act on Tower. `memory-store.ts` runs
+ * them; `parseMemoryArgs` in `local-args-collector-status.ts` routes to here.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs, workRootFlagValue, } from "./local-arg-values.js";
+export const MEMORY_STORE_ACTIONS = new Set([
+    "search",
+    "save",
+    "update",
+    "forget",
+]);
+const ALLOWED_FLAGS = [
+    "--home",
+    "--dashboard-url",
+    "--workspace",
+    "--repo",
+    "--container",
+    "--limit",
+    "--no-recent",
+    "--custom-id",
+    "--extract",
+    "--file",
+    "--content-stdin",
+    "--reason",
+    "--json",
+];
+const VALUE_FLAGS = [
+    "--home",
+    "--dashboard-url",
+    "--workspace",
+    "--repo",
+    "--container",
+    "--limit",
+    "--custom-id",
+    "--file",
+    "--reason",
+];
+export function parseMemoryStoreArgs(action, args) {
+    const values = parseNamedArgs(args, { allowedFlags: ALLOWED_FLAGS, valueFlags: VALUE_FLAGS });
+    const rest = values.positionals.slice(1);
+    const containers = values.flagValues.get("--container") ?? [];
+    if (action !== "search" && containers.length > 1) {
+        throw new Error(`memory ${action} takes at most one --container.`);
+    }
+    if (action !== "search" && (values.flags.has("--limit") || values.booleans.has("--no-recent"))) {
+        throw new Error("--limit and --no-recent only apply to memory search.");
+    }
+    if (action !== "save" && (values.flags.has("--custom-id") || values.booleans.has("--extract"))) {
+        throw new Error("--custom-id and --extract only apply to memory save.");
+    }
+    if (action !== "forget" && (values.flags.has("--reason") || values.booleans.has("--content-stdin"))) {
+        throw new Error("--reason and --content-stdin only apply to memory forget.");
+    }
+    if (values.flags.has("--file") && action !== "save" && action !== "update") {
+        throw new Error("--file only applies to memory save and memory update.");
+    }
+    const command = {
+        kind: "memory-store",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        workspace: optionalNonEmpty(workRootFlagValue(values)),
+        containerTags: containers
+            .map((tag) => tag.trim())
+            .filter((tag) => tag.length > 0),
+        json: values.booleans.has("--json"),
+    };
+    if (action === "search") {
+        // Every remaining positional joined, so `cockpit memory search what did we
+        // decide about pagination` needs no quotes — the same shape `cockpit
+        // search` and `cockpit cal find` already have.
+        const query = rest.join(" ").trim();
+        if (!query)
+            throw new Error("memory search needs a question, e.g. `cockpit memory search \"pagination rule\"`.");
+        return { ...command, action, query, limit: readLimit(values.flags.get("--limit")), includeRecent: !values.booleans.has("--no-recent") };
+    }
+    if (action === "save") {
+        if (rest.length > 0) {
+            throw new Error("memory save reads the memory from stdin or --file, never from the command line: `echo \"...\" | cockpit memory save`.");
+        }
+        return {
+            ...command,
+            action,
+            customId: optionalNonEmpty(values.flags.get("--custom-id")),
+            extract: values.booleans.has("--extract"),
+            filePath: optionalNonEmpty(values.flags.get("--file")),
+        };
+    }
+    if (action === "update") {
+        const memoryId = optionalNonEmpty(rest[0]);
+        if (!memoryId)
+            throw new Error("memory update needs the memory id `cockpit memory search` printed.");
+        if (rest.length > 1) {
+            throw new Error("memory update takes one id; the replacement text comes from stdin or --file, never from the command line.");
+        }
+        return { ...command, action, memoryId, filePath: optionalNonEmpty(values.flags.get("--file")) };
+    }
+    const memoryId = optionalNonEmpty(rest[0]);
+    if (rest.length > 1)
+        throw new Error("memory forget takes one id, or --content-stdin with a --container.");
+    const contentStdin = values.booleans.has("--content-stdin");
+    if (memoryId && contentStdin) {
+        throw new Error("memory forget takes an id OR --content-stdin, never both — they name different rows.");
+    }
+    if (!memoryId && !contentStdin) {
+        throw new Error("memory forget needs an id, or --content-stdin plus --container to forget by exact text.");
+    }
+    return {
+        ...command,
+        action,
+        memoryId,
+        contentStdin,
+        reason: optionalNonEmpty(values.flags.get("--reason")),
+    };
+}
+/** 1..20, the same window the MCP tool and the door both accept. */
+function readLimit(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 1 || parsed > 20) {
+        throw new Error("--limit must be between 1 and 20.");
+    }
+    return parsed;
+}

package/dist/commands/local-command-shapes-memory.js

@@ -0,0 +1,22 @@
+/**
+ * The `cockpit memory` family's command shapes (BLI-4047).
+ *
+ * Split out of `local-command-shapes.ts` the same way `SearchCommandShape` and
+ * the product shapes were: that file crossed the repo's 500-line band floor
+ * when the store verbs arrived, and one noun's shapes are exactly the kind of
+ * thing that reads better in its own file than as a third of a 540-line union.
+ *
+ * Three kinds, and the difference between them is the point:
+ *
+ *   `memory`        install / status / help — acts on THIS MACHINE, writing an
+ *                   MCP registration and three hooks into a home directory.
+ *   `memory-store`  search / save / update / forget — acts on TOWER, over
+ *                   `/api/memory/*`, the same doors the `bli-memory` MCP
+ *                   server and the browser call.
+ *   `memory-log`    the agent-experience opinion, part local file part Tower.
+ *
+ * They are separate kinds rather than one widening `action` union because they
+ * refuse different things, run on different credentials, and one of them can
+ * be run unasked by a scheduler while the others never are.
+ */
+export {};

package/dist/commands/local-help-commands.js

@@ -555,15 +555,32 @@ export function localSubcommandHelp(command) {
         [
             "memory",
             [
-                "Usage: cockpit memory [install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--dashboard-url <url>] [--dry-run] [--json]",
-                "",
-                "Registers BLI Memory on this machine: the `bli-memory` MCP server plus the",
+                "Usage: cockpit memory [search|save|update|forget|install|status|log] [flags]",
+                "",
+                "The STORE, over the same /api/memory/* doors the bli-memory MCP server calls:",
+                "  search \"<question>\" [--container <tag>] [--limit 1..20] [--no-recent]",
+                "      repeat --container to search more than one space; omit it for this repository's own.",
+                "  save [--container <tag>] [--custom-id <id>] [--extract] [--file <path>]",
+                "      the memory comes from stdin or --file, never from the command line:",
+                "      `echo \"Edward decided X on 2026-09-10\" | cockpit memory save`.",
+                "      --custom-id makes a repeat save update instead of duplicating;",
+                "      --extract distils atomic facts first (one model call) instead of storing as given.",
+                "  update <id> [--file <path>]   replacement text on stdin; the old row is kept as history.",
+                "  forget <id> [--reason <label>]",
+                "  forget --content-stdin --container <tag> [--reason <label>]   forget by exact text.",
+                "Refusals keep the door's own label — needs_rls_client, unknown_memory,",
+                "already_superseded, no_match — and --json prints the door's answer unchanged.",
+                "",
+                "BARE `cockpit memory` PRINTS THIS LIST AND DOES NOTHING ELSE (BLI-4047).",
+                "It used to run the installer; installing is now `cockpit memory install`.",
+                "",
+                "install/status register BLI Memory on this machine: the `bli-memory` MCP server plus the",
                 "recall/save hooks, for Claude Code (~/.claude.json, ~/.claude/settings.json)",
                 "and for Codex (~/.codex/config.toml, ~/.codex/skills/bli-memory/).",
                 "Idempotent: it merges with what is already there, never duplicates its own",
                 "entries, and reads the stored config back before reporting success.",
                 "`do-everything` runs it, and the sync tick re-runs it at most once a day.",
-                "Action defaults to `install`. See docs/runbooks/bli-memory-install.md.",
+                "See docs/runbooks/bli-memory-install.md.",
                 "log appends an opinion to ~/.codex/AGENT-EXPERIENCE.md and posts it to Tower.",
                 "Use --reason-stdin instead of a quoted reason; --json reports shipped status.",
                 "Reasons: one line, max 500 characters; no prompts, memory bodies or secrets.",

package/dist/commands/local-help.js

@@ -88,7 +88,7 @@ export function localCommandHelp(command) {
         "  cockpit serve [--port <port>] [--workspace <path>]",
         "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
         "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
-        "  cockpit memory [install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--dashboard-url <url>] [--dry-run] [--json]",
+        "  cockpit memory [search \"<question>\"|save|update <id>|forget <id>|install|status|log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"] [--container <tag>] [--limit <n>] [--no-recent] [--custom-id <id>] [--extract] [--content-stdin] [--reason <label>] [--file <path>] [--dashboard-url <url>] [--dry-run] [--json]",
         "  cockpit clean [--dry-run] [--all-committed] [--reconcile] [--dashboard-url <url>] [--json]",
         "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>] [--parent <id>|root|--clear-parent] [--query <text>] [--limit <n>] [--visibility org|private] [--file <path>|--body-stdin] [--allow-empty] [--dashboard-url <url>] [--json]",
         "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",

package/dist/commands/local.js

@@ -33,6 +33,7 @@ import { runAutostart } from "./autostart-command.js";
 import { runAgentRules } from "./agent-rules-command.js";
 import { runMemoryLog } from "./memory-log.js";
 import { runMemoryInstall } from "./memory-install.js";
+import { runMemoryStore, runMemoryVerbList } from "./memory-store.js";
 import { runClean } from "./clean.js";
 import { runDocs } from "./docs.js";
 import { runMsg } from "./msg.js";
@@ -148,7 +149,14 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
             case "memory-log":
                 return await runMemoryLog(command, io);
             case "memory":
+                // BLI-4047: a bare `cockpit memory` says what the noun does. It used
+                // to install; `install` is still one word away and every unattended
+                // caller asks for it by name in code.
+                if (command.action === "help")
+                    return runMemoryVerbList(io, command.json);
                 return await runMemoryInstall(command, io);
+            case "memory-store":
+                return await runMemoryStore(command, io);
             case "clean":
                 return await runClean(command, io);
             case "docs":

package/dist/commands/memory-store.js

@@ -0,0 +1,331 @@
+/**
+ * `cockpit memory search|save|update|forget` — BLI Memory at a terminal
+ * (BLI-4047).
+ *
+ * Memory was the one Tower surface with no command-line door. The browser had
+ * one, the `bli-memory` MCP server had four tools, and a person or a script
+ * had nothing — so a machine without an agent host could not read or write the
+ * store at all, and `cockpit memory` typed on its own registered an MCP server
+ * instead of saying what the noun does. These four verbs are the twins of that
+ * server's four tools.
+ *
+ * **The same doors, never a second store.** `POST /api/memory/{search,save,
+ * update,forget}`, with this machine's collector device token, through
+ * `agent-door.ts` — the identical route the MCP server calls in
+ * `packages/cockpit-memory-mcp/src/server.ts` and the browser calls from
+ * `lib/memory/agent-memories/`. Nothing here talks to Postgres, embeds
+ * anything, or knows what a container alias is; every ranking, redaction and
+ * lifecycle decision stays server-side where its one implementation lives.
+ *
+ * **A refusal keeps the door's own reason label.** `needs_rls_client`,
+ * `unknown_memory`, `already_forgotten`, `already_superseded`,
+ * `needs_container_tag`, `no_match`, `custom_id_conflict`, `search_timed_out`
+ * — printed verbatim by `failAgentDoor`, never rephrased here. A CLI that
+ * invents its own prose for a server's refusal is a CLI whose error messages
+ * lie one release later.
+ *
+ * **The container tag is `@bli-cockpit/memory-mcp`'s, not a second copy.**
+ * `resolveContainerTag` is imported from that package rather than
+ * reimplemented, so a memory saved by `cockpit memory save` lands in exactly
+ * the space the MCP server and the three hooks read from. The scheme is the
+ * vendor plugin's byte for byte and two implementations of it would strand
+ * memories in a space nothing asks about — see that module's header.
+ *
+ * **A body never comes from the command line.** `save`, `update` and
+ * `forget --content-stdin` read stdin (or `--file`). Same discipline as
+ * `cockpit docs create` and `cockpit notes paste`, and for the same reasons:
+ * `ps` shows an argument list, shell history keeps it, and a memory with a
+ * newline in it cannot be quoted correctly anyway.
+ */
+import { resolveContainerTag } from "@bli-cockpit/memory-mcp/dist/container-tag.js";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+const TAG = "[memory cli]";
+const SEARCH_DEADLINE_MS = 60_000;
+/** `--extract` is one model call, sometimes two; the door waits for it when asked to. */
+const WRITE_DEADLINE_MS = 120_000;
+/** The door's own ceiling on a memory (`saveMemoryInput`, 200k characters). */
+const BODY_MAX_CHARS = 200_000;
+/** The door's own ceiling on forget-by-text. */
+const FORGET_MAX_CHARS = 10_000;
+export async function runMemoryStore(command, io) {
+    const door = await openAgentDoor("memory", command, io);
+    switch (command.action) {
+        case "search":
+            return searchMemory(command, door);
+        case "save":
+            return saveMemory(command, door);
+        case "update":
+            return updateMemory(command, door);
+        case "forget":
+            return forgetMemory(command, door);
+    }
+}
+/**
+ * The verb list a bare `cockpit memory` prints (BLI-4047).
+ *
+ * It used to run the installer. Typing a noun to find out what it does is the
+ * single most common thing a person does with a new CLI, and this was the one
+ * command in the collector that answered that by writing five files in a home
+ * directory. Installing is still one word away, and every unattended caller
+ * asks for `install` by name in code.
+ */
+export function runMemoryVerbList(io, json) {
+    if (json) {
+        writeLine(io.stdout, JSON.stringify({
+            ok: true,
+            noun: "memory",
+            machine_verbs: ["install", "status"],
+            store_verbs: ["search", "save", "update", "forget"],
+            log_verbs: ["log"],
+        }));
+        return 0;
+    }
+    for (const line of [
+        "cockpit memory — BLI Memory: the store, and this machine's registration.",
+        "",
+        "The store (Tower, over /api/memory/*):",
+        "  cockpit memory search \"<question>\" [--container <tag>] [--limit 1..20] [--no-recent] [--json]",
+        "  cockpit memory save [--container <tag>] [--custom-id <id>] [--extract] [--file <path>] [--json]",
+        "      the memory comes from stdin, or --file; never from the command line",
+        "  cockpit memory update <id> [--file <path>] [--json]        replacement text on stdin",
+        "  cockpit memory forget <id> [--reason <label>] [--json]",
+        "  cockpit memory forget --content-stdin --container <tag> [--reason <label>] [--json]",
+        "",
+        "This machine:",
+        "  cockpit memory install [--dry-run] [--json]   register the MCP server and the three hooks",
+        "  cockpit memory status [--json]                read the stored config back",
+        "",
+        "The experience log:",
+        "  cockpit memory log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"",
+        "",
+        "Omit --container and this repository's own memory space is used — the same",
+        "space the bli-memory MCP server and its hooks read and write.",
+    ]) {
+        writeLine(io.stdout, line);
+    }
+    return 0;
+}
+/**
+ * This repository's memory space, resolved by the MCP server's own resolver.
+ * `--container` wins; `--workspace` says which directory to derive it from.
+ */
+function containerTagsFor(command) {
+    if (command.containerTags.length > 0)
+        return command.containerTags;
+    return [resolveContainerTag({ cwd: command.workspace ?? process.cwd() }).containerTag];
+}
+async function searchMemory(command, door) {
+    const containerTags = containerTagsFor(command);
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/search",
+        method: "POST",
+        label: "memory search",
+        timeoutMs: SEARCH_DEADLINE_MS,
+        body: {
+            query: command.query,
+            containerTag: containerTags,
+            ...(command.limit === undefined ? {} : { limit: command.limit }),
+            includeProfile: command.includeRecent !== false,
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const results = body.results ?? [];
+    const recent = body.recent ?? [];
+    // Counts and labels only: a memory body never enters a log line.
+    writeLine(door.io.stderr, `${TAG} searched ${JSON.stringify({
+        requested_containers: containerTags.length,
+        searched_containers: body.containerTags?.length ?? containerTags.length,
+        results: results.length,
+        recent: recent.length,
+        dropped_below_floor: body.dropped_below_floor ?? 0,
+        degraded: body.degraded ?? null,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    if (results.length === 0) {
+        // The distinction the whole store is built on: silence is not an outage.
+        // A failure took the `!answer.ok` branch above and named itself there.
+        writeLine(door.io.stdout, "No memories matched. The record is silent on this — it does not mean the store is down.");
+    }
+    else {
+        for (const row of results) {
+            writeLine(door.io.stdout, `${similarityLabel(row)}${oneLine(row["memory"])}`);
+            writeLine(door.io.stdout, `    ${String(row["id"] ?? "")}  ${String(row["containerTag"] ?? "")}`);
+        }
+    }
+    if (recent.length > 0) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "Recent context:");
+        for (const row of recent)
+            writeLine(door.io.stdout, `  - ${oneLine(row["preview"] ?? row["memory"])}`);
+    }
+    if (body.degraded) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, `This answer is thinner than usual (${body.degraded}) — one search channel did not run.`);
+    }
+    return 0;
+}
+async function saveMemory(command, door) {
+    const containerTag = containerTagsFor(command)[0];
+    const body = await readBody(command, door, BODY_MAX_CHARS, "A memory");
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (!body.text.trim()) {
+        return failAgentDoor(door, TAG, "content_empty", "There is nothing to save. Pipe the memory in: `echo \"...\" | cockpit memory save`, or pass --file.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/save",
+        method: "POST",
+        label: "memory save",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            content: body.text,
+            containerTag,
+            ...(command.customId ? { customId: command.customId } : {}),
+            mode: command.extract ? "extract" : "verbatim",
+            // Same reason the MCP tool sets it: a caller that ASKED for distillation
+            // is waiting for the answer, so take the synchronous branch instead of
+            // the 202 the Stop hook wants.
+            ...(command.extract ? { wait: true } : {}),
+            sourceRef: { kind: "cli" },
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const saved = answer.body;
+    writeLine(door.io.stderr, `${TAG} saved ${JSON.stringify({
+        outcome: saved["outcome"] ?? null,
+        chars: body.text.length,
+        embedded: saved["embedded"] ?? null,
+        embed_skipped_reason: saved["embedSkippedReason"] ?? null,
+        extract: saved["extract"] ?? null,
+        masked_spans: saved["maskedSpans"] ?? 0,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    // The container the SERVER used, which is the canonical one when this
+    // repository has more than one tag on the shelf; saying the tag we sent
+    // would name a space the row is not in.
+    const landedIn = String(saved["containerTag"] ?? containerTag);
+    writeLine(door.io.stdout, `Memory ${String(saved["outcome"] ?? "created")} in ${landedIn} (id: ${String(saved["id"] ?? "—")}).`);
+    if (saved["embedded"] === false && saved["embedSkippedReason"]) {
+        writeLine(door.io.stdout, `Stored without a search vector (${String(saved["embedSkippedReason"])}): findable by keyword, not yet by meaning.`);
+    }
+    if (saved["extract"] === "fell_back_verbatim") {
+        writeLine(door.io.stdout, `Saved as written; extraction failed (${String(saved["extractFailureReason"] ?? "unknown")}).`);
+    }
+    return 0;
+}
+async function updateMemory(command, door) {
+    const body = await readBody(command, door, BODY_MAX_CHARS, "A memory");
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (!body.text.trim()) {
+        return failAgentDoor(door, TAG, "content_empty", "An update needs replacement text on stdin or --file. To remove a memory, use `cockpit memory forget`.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/update",
+        method: "POST",
+        label: "memory update",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { id: command.memoryId, content: body.text },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const updated = answer.body;
+    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({
+        chars: body.text.length,
+        re_embedded: updated["reEmbedded"] ?? null,
+        embed_skipped_reason: updated["embedSkippedReason"] ?? null,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    writeLine(door.io.stdout, `Updated. The new memory is ${String(updated["id"] ?? "")}, and ${String(updated["supersededId"] ?? command.memoryId ?? "")} is kept as its previous version.`);
+    return 0;
+}
+async function forgetMemory(command, door) {
+    let content;
+    if (command.contentStdin) {
+        const body = await readBody(command, door, FORGET_MAX_CHARS, "Text to forget");
+        if (!body.ok)
+            return failAgentDoor(door, TAG, body.reason, body.detail);
+        if (!body.text.trim()) {
+            return failAgentDoor(door, TAG, "needs_id_or_content", "Nothing arrived on stdin to forget.");
+        }
+        content = body.text;
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/forget",
+        method: "POST",
+        label: "memory forget",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ...(command.memoryId ? { id: command.memoryId } : {}),
+            ...(content ? { content } : {}),
+            // Only defaulted for a text match, which is the case that would
+            // otherwise sweep every space this caller can read. An id needs none.
+            ...(content ? { containerTag: containerTagsFor(command)[0] } : {}),
+            ...(command.reason ? { reason: command.reason } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} forgot ${JSON.stringify({ count: result.count ?? 0, by: content ? "content" : "id" })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    // The door answers with WHAT it removed, deliberately: a bare "done" is the
+    // only shape in which "forget X" quietly removing Y goes unnoticed.
+    writeLine(door.io.stdout, result.message ?? `Forgotten (${result.count ?? 0}).`);
+    for (const row of result.forgotten ?? []) {
+        const entry = row;
+        writeLine(door.io.stdout, `  ${String(entry["id"] ?? "")}  ${oneLine(entry["textPreview"])}`);
+    }
+    return 0;
+}
+/** A body from `--file`, else stdin. An interactive terminal yields nothing rather than hanging. */
+async function readBody(command, door, maxChars, what) {
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok) {
+            return { ok: false, reason: read.refusal, detail: `Could not read ${command.filePath}: ${read.detail}` };
+        }
+        return { ok: true, text: read.bytes.toString("utf8") };
+    }
+    if (isInteractiveStdin(door.io))
+        return { ok: true, text: "" };
+    try {
+        return {
+            ok: true,
+            text: await readPipedText(door.io.stdin, {
+                maxChars,
+                overflowMessage: `${what} is limited to ${maxChars} characters.`,
+            }),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "content_too_long",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** `[87%] ` when the row was found by meaning, empty when it was a keyword hit. */
+function similarityLabel(row) {
+    const channels = row["channels"];
+    if (Array.isArray(channels) && !channels.includes("semantic"))
+        return "";
+    const similarity = Number(row["similarity"]);
+    return Number.isFinite(similarity) && similarity >= 0 && similarity <= 1
+        ? `[${Math.round(similarity * 100)}%] `
+        : "";
+}
+/** One terminal line: newlines folded, so a long memory cannot break the listing. */
+function oneLine(value) {
+    return String(value ?? "").replace(/\s+/g, " ").trim();
+}

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.97");
+    writeLine(io?.stdout ?? process.stdout, "0.2.98");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.97",
+  "version": "0.2.98",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.25",
-    "@bli-cockpit/mcp": "0.1.28",
+    "@bli-cockpit/mcp": "0.1.29",
     "@bli-cockpit/telemetry-core": "0.1.42"
   }
 }