@bli-cockpit/memory-mcp 0.1.0 → 0.1.2

package/README.md

@@ -18,23 +18,94 @@ keeps working. `update_memory` is new — the vendor had no update tool at all,
 and correction there meant forget-then-save, which loses the link between the
 two.
 
+Plus three Claude Code hooks, on the same bin — see below.
+
 ## Install
 
+**Nobody installs this by hand.** It ships as a dependency of
+`@bli-cockpit/cli`, and `cockpit memory install` (which `cockpit do-everything`
+and the daily sync tick both run) registers it with both hosts. A standalone
+install is for development:
+
 ```bash
 npm i -g @bli-cockpit/memory-mcp
 ```
 
-Then register it. The server prints the exact block each host wants, so nothing
-has to be retyped:
+The server prints the exact block each host wants, so nothing has to be retyped:
 
 ```bash
-bli-memory-mcp --print-config           # both
-bli-memory-mcp --print-config=claude    # ~/.claude.json  (or a plugin's .mcp.json)
+bli-memory-mcp --print-config           # both, with headings
+bli-memory-mcp --print-config=claude    # the install contract (see below)
 bli-memory-mcp --print-config=codex     # ~/.codex/config.toml
 ```
 
-`cockpit memory install` (a later slice of BLI-3580) consumes those two blocks
-verbatim rather than keeping its own copy of them.
+`--print-config --claude` prints the **install contract**,
+`bli-memory-install-config.v1` — the MCP server entry *and* the three hooks with
+their timeouts, because this bin is the only thing that knows which hook
+subcommands it implements:
+
+```json
+{
+  "schema": "bli-memory-install-config.v1",
+  "server_id": "bli-memory",
+  "mcp_server": { "command": "bli-memory-mcp", "args": [], "env": {} },
+  "hooks": [
+    { "event": "SessionStart",     "command": "bli-memory-mcp hook session-start", "timeout_seconds": 30 },
+    { "event": "UserPromptSubmit", "command": "bli-memory-mcp hook prompt",        "timeout_seconds": 5 },
+    { "event": "Stop",             "command": "bli-memory-mcp hook stop",          "timeout_seconds": 30 }
+  ],
+  "permissions_allow": ["mcp__bli-memory__search_memory"]
+}
+```
+
+`command` is the bare bin name; `cockpit memory install` replaces it with the
+absolute path it resolved on that machine, in every one of those strings. It is
+never `npx -y @bli-cockpit/memory-mcp`, which would re-resolve the package from
+the registry on every agent launch.
+
+By hand: `mcp_server` goes under `mcpServers.bli-memory` in `~/.claude.json`,
+each hook under `hooks.<event>` in `~/.claude/settings.json`, and the bin path
+has to be absolute or on your PATH.
+
+## The three hooks
+
+```bash
+bli-memory-mcp hook session-start   # SessionStart
+bli-memory-mcp hook prompt          # UserPromptSubmit
+bli-memory-mcp hook stop            # Stop
+```
+
+Each reads Claude Code's JSON payload on stdin and:
+
+| Hook | Reads | Calls | Prints |
+|---|---|---|---|
+| `session-start` | `cwd` | `POST /api/memory/v4/profile` | `<bli-memory-context>` with User Profile + Recent Context, `◪` per line |
+| `prompt` | `prompt` | `POST /api/memory/search` (top 5, ≥ 0.55 similarity) | `<bli-memory-recall>`, `◪` per line |
+| `stop` | `transcript_path` | `POST /api/memory/save` in `extract` mode | nothing, ever |
+
+Four rules they all keep, because a hook runs on every turn of every session on
+every machine:
+
+- **Never block.** Each has a deadline below the timeout the installer
+  registers — 8 s / 3 s / 15 s against 30 / 5 / 30 — including a hard deadline
+  on the stdin read. On any deadline it prints nothing and gives the host its
+  process back.
+- **Always exit 0.** Claude Code reads exit 2 as "block this prompt" and any
+  other non-zero as an error it shows the person. An unpaired machine, an
+  outage, a malformed payload: all quiet in the transcript.
+- **Print nothing, or one whole block.** No "no memories found" line — the model
+  would reason about it, and an empty record and an unreachable store would look
+  the same to it. Zero hits is data and prints nothing.
+- **One stderr receipt per run**, on every branch:
+  `[bli-memory hook] prompt {"status":"empty","reason":"no_hits","hits":0,"elapsed_ms":140}`.
+  Counts and reason labels only — never a prompt, a memory, a path or a token.
+
+`hook stop` sends the last user/assistant exchange (at most 12 KB, tail-read so
+a 40 MB transcript costs nothing) through the collector's own redactor —
+`redactSecretLikeContent` from `@bli-cockpit/telemetry-core`, the same function
+that masks every uploaded transcript — and lets the librarian's
+extract/reconcile decide what is worth keeping. A re-entrant Stop
+(`stop_hook_active: true`) saves nothing.
 
 ## Auth
 
@@ -61,6 +132,14 @@ memories it has today. The **remote** is the identity, so every worktree of one
 repo shares a space. A folder that is not a git repository still gets its own
 space (`dir_<name>__<sha16>`), because a folder is a legitimate workspace.
 
+One repository can still have TWO tags on the shelf — the vendor's, kept
+verbatim when its memories were imported, and the one derived above. Tower
+reconciles them server-side (`agent_memory_container_aliases`, BLI-3620):
+`search_memory` is answered from every tag that names the same space, and
+`save_memory` lands in the canonical one. That is why a saved memory can report
+a space you did not pass — the tool names where the row actually went, not what
+it asked for.
+
 ## The stdio contract
 
 **stdout carries the JSON-RPC stream and nothing else.** Every operational

package/dist/container-tag.d.ts

@@ -34,6 +34,20 @@ export interface ContainerTagOptions {
     /** Injected in tests. Returns stdout, or null when git said no. */
     git?: (args: string[], cwd: string) => string | null;
     realpath?: (value: string) => string;
+    /**
+     * Ceiling on ONE `git` call, in ms. Default 5 s, which is right for the MCP
+     * server (it resolves the tag once, at startup, before any client is
+     * waiting).
+     *
+     * The hooks pass a much smaller number, and the reason is that `spawnSync`
+     * BLOCKS the event loop: a git that stalls on a network filesystem or a held
+     * index lock would sit here past the hook's own deadline, and the deadline
+     * timer cannot fire while the loop is blocked. That is the same class of hang
+     * this whole slice exists to remove, so the budget has to reach the syscall
+     * that can actually stall. Two calls happen at most, so the worst case is
+     * twice this.
+     */
+    gitTimeoutMs?: number;
 }
 export interface ContainerTagResult {
     containerTag: string;
@@ -47,3 +61,4 @@ export declare function resolveContainerTag(options?: ContainerTagOptions): Cont
  * `https://github.com/org/repo` are one identity, which is the point.
  */
 export declare function normalizeRemote(remote: string): string;
+export declare const DEFAULT_GIT_TIMEOUT_MS = 5000;

package/dist/container-tag.js

@@ -35,7 +35,8 @@ export const CONTAINER_TAG_MAX_NAME = 72;
 export function resolveContainerTag(options = {}) {
     const env = options.env ?? process.env;
     const cwd = options.cwd ?? process.cwd();
-    const git = options.git ?? runGit;
+    const gitTimeoutMs = options.gitTimeoutMs ?? DEFAULT_GIT_TIMEOUT_MS;
+    const git = options.git ?? ((args, dir) => runGit(args, dir, gitTimeoutMs));
     const realpath = options.realpath ?? ((value) => fs.realpathSync(value));
     const override = (env.BLI_MEMORY_CONTAINER_TAG ?? env.SUPERMEMORY_REPO_TAG ?? "").trim();
     if (override.length > 0)
@@ -93,13 +94,14 @@ function safeRealpath(value, realpath) {
         return value;
     }
 }
-function runGit(args, cwd) {
+export const DEFAULT_GIT_TIMEOUT_MS = 5_000;
+function runGit(args, cwd, timeoutMs) {
     const result = spawnSync("git", args, {
         cwd,
         encoding: "utf8",
         shell: false,
         windowsHide: true,
-        timeout: 5_000,
+        timeout: timeoutMs,
     });
     if (result.status !== 0 || typeof result.stdout !== "string")
         return null;

package/dist/door.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One way to knock on a Tower memory door (BLI-3580).
+ *
+ * The MCP server and the three Claude Code hooks both POST to
+ * `/api/memory/*` with this machine's collector device token. That was one
+ * implementation living privately inside `server.ts` until the hooks needed the
+ * same thing with a deadline on it; two copies of an auth header and an
+ * error-shape reader is how one of them ends up sending the token the wrong way
+ * a release later, so it lives here once.
+ *
+ * Two contracts this module keeps:
+ *
+ *  - **A transport failure is not an empty answer.** `transportError` is set
+ *    ONLY when no JSON answer was produced at all — DNS, TLS, a timeout, a body
+ *    that is not JSON. A 404 with a reason in it is a refusal, not an outage,
+ *    and the caller must be able to tell those apart (`server.ts` turns one
+ *    into `isError`; a hook prints nothing and logs the reason).
+ *  - **The token never travels into a message.** It goes in one header and is
+ *    never logged, echoed, or included in an error string.
+ *
+ * `timeoutMs` exists for the hooks. Claude Code kills a hook that outlives its
+ * configured timeout, and a hook killed mid-`fetch` reports nothing at all — so
+ * every hook budgets its own request below its own deadline and aborts rather
+ * than being killed.
+ */
+import type { MemorySession } from "./session.js";
+export type FetchImpl = typeof fetch;
+export interface DoorResponse {
+    ok: boolean;
+    status: number;
+    body: Record<string, unknown>;
+    /** Set when the request never produced a JSON answer at all. */
+    transportError: string | null;
+}
+export interface DoorRequest {
+    session: MemorySession;
+    fetchImpl: FetchImpl;
+    /** A leading-slash path, e.g. `/api/memory/search`. */
+    path: string;
+    body: Record<string, unknown>;
+    /** Abort the request after this many ms. Omitted means no deadline. */
+    timeoutMs?: number;
+}
+export declare function postMemoryDoor(request: DoorRequest): Promise<DoorResponse>;
+/** The reason label for a failed door call: the refusal's own, or `transport`. */
+export declare function doorReason(response: DoorResponse): string;

package/dist/door.js

@@ -0,0 +1,99 @@
+/**
+ * One way to knock on a Tower memory door (BLI-3580).
+ *
+ * The MCP server and the three Claude Code hooks both POST to
+ * `/api/memory/*` with this machine's collector device token. That was one
+ * implementation living privately inside `server.ts` until the hooks needed the
+ * same thing with a deadline on it; two copies of an auth header and an
+ * error-shape reader is how one of them ends up sending the token the wrong way
+ * a release later, so it lives here once.
+ *
+ * Two contracts this module keeps:
+ *
+ *  - **A transport failure is not an empty answer.** `transportError` is set
+ *    ONLY when no JSON answer was produced at all — DNS, TLS, a timeout, a body
+ *    that is not JSON. A 404 with a reason in it is a refusal, not an outage,
+ *    and the caller must be able to tell those apart (`server.ts` turns one
+ *    into `isError`; a hook prints nothing and logs the reason).
+ *  - **The token never travels into a message.** It goes in one header and is
+ *    never logged, echoed, or included in an error string.
+ *
+ * `timeoutMs` exists for the hooks. Claude Code kills a hook that outlives its
+ * configured timeout, and a hook killed mid-`fetch` reports nothing at all — so
+ * every hook budgets its own request below its own deadline and aborts rather
+ * than being killed.
+ */
+export async function postMemoryDoor(request) {
+    const url = `${request.session.dashboardUrl}${request.path}`;
+    const controller = typeof request.timeoutMs === "number" && request.timeoutMs > 0
+        ? new AbortController()
+        : null;
+    const timer = controller && typeof request.timeoutMs === "number"
+        ? setTimeout(() => controller.abort(), request.timeoutMs)
+        : null;
+    // Never keep the process alive for a deadline timer: a hook that has already
+    // printed its answer must exit, not linger until the abort fires.
+    timer?.unref?.();
+    let response;
+    try {
+        response = await request.fetchImpl(url, {
+            method: "POST",
+            headers: {
+                // The device token. Never logged, never echoed into a message.
+                authorization: `Bearer ${request.session.deviceToken}`,
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            body: JSON.stringify(request.body),
+            ...(controller ? { signal: controller.signal } : {}),
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 0,
+            body: {},
+            transportError: describeTransportError(error, request.timeoutMs),
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+    let parsed = {};
+    try {
+        const text = await response.text();
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        return {
+            ok: false,
+            status: response.status,
+            body: {},
+            transportError: `Tower answered ${response.status} with a body this server could not read as JSON.`,
+        };
+    }
+    return { ok: response.ok, status: response.status, body: parsed, transportError: null };
+}
+/**
+ * An abort reads as a timeout with its budget named, because "The operation was
+ * aborted" tells an operator nothing about which limit they hit.
+ */
+function describeTransportError(error, timeoutMs) {
+    const name = error?.name;
+    if (name === "AbortError" || name === "TimeoutError") {
+        return timeoutMs
+            ? `Tower did not answer within ${timeoutMs} ms; the request was abandoned.`
+            : "The request was aborted before Tower answered.";
+    }
+    return error instanceof Error ? (error.message.split("\n")[0] ?? "unknown") : String(error);
+}
+/** The reason label for a failed door call: the refusal's own, or `transport`. */
+export function doorReason(response) {
+    if (response.transportError)
+        return "transport_failed";
+    const label = response.body["error"];
+    if (typeof label === "string" && label.trim())
+        return label.trim();
+    return `http_${response.status}`;
+}

package/dist/hooks/contract.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The three Claude Code hooks — the vocabulary they all share (BLI-3580).
+ *
+ * `cockpit memory install` registers three hook commands on every machine
+ * (`memory-install-contract.ts`):
+ *
+ *   SessionStart      bli-memory-mcp hook session-start   timeout 30 s
+ *   UserPromptSubmit  bli-memory-mcp hook prompt          timeout  5 s
+ *   Stop              bli-memory-mcp hook stop            timeout 30 s
+ *
+ * **A hook that hangs is worse than a hook that does nothing.** Claude Code
+ * runs `UserPromptSubmit` on every prompt a person types and waits for it, so a
+ * hook that blocks on stdin, or on a dashboard that is not answering, costs
+ * every person on the fleet its timeout on every turn. That is the failure this
+ * file's budgets exist to make impossible: each event has a TOTAL deadline
+ * strictly below the installer's timeout for it, a stdin read deadline inside
+ * that, and a request deadline inside that. On any deadline the hook prints
+ * nothing and exits 0.
+ *
+ * **Exit 0, always.** Claude Code treats exit 2 as "block this" and any other
+ * non-zero as an error it shows the person. Neither is ever the right answer
+ * for a memory recall: an unpaired machine, an outage or a malformed payload
+ * must be invisible in the transcript and visible in stderr. `hook.ts` is the
+ * one place that decides the exit code, and it only ever decides 0.
+ *
+ * **Print nothing, or print exactly one block.** stdout of a SessionStart or
+ * UserPromptSubmit hook is injected into the model's context verbatim, so an
+ * empty result prints NOTHING rather than a "no memories found" line the model
+ * would then reason about.
+ */
+/** The three subcommands, exactly as the installer writes them. */
+export declare const HOOK_EVENTS: readonly ["session-start", "prompt", "stop"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+export interface HookBudget {
+    /** The whole run. Below the installer's timeout for this event, always. */
+    totalMs: number;
+    /** Waiting for Claude Code's payload on stdin. */
+    stdinMs: number;
+    /** One door call. */
+    requestMs: number;
+    /**
+     * One `git` call while deriving the container tag. It has its own budget
+     * because `resolveContainerTag` uses `spawnSync`, which BLOCKS the event
+     * loop — the total deadline below cannot fire while git is stalling, so this
+     * is the only bound that reaches it. At most two calls happen.
+     */
+    gitMs: number;
+}
+/**
+ * Deadlines, in ms, against the installer's timeouts of 30 s / 5 s / 30 s.
+ *
+ * Each total leaves the host real headroom rather than racing it: a hook killed
+ * by its host reports NOTHING — no stderr line, no reason — and that is exactly
+ * the kind of silence this repo's logging rule exists to prevent. Better to
+ * abandon the recall ourselves and say why.
+ */
+export declare const HOOK_BUDGETS: Record<HookEvent, HookBudget>;
+/**
+ * Claude Code's hook payload, as documented, with every field optional because
+ * a hook must survive a host that adds, renames or omits one.
+ *
+ *   SessionStart      { session_id, transcript_path, cwd, hook_event_name, source }
+ *   UserPromptSubmit  … + { prompt }
+ *   Stop              … + { stop_hook_active }
+ */
+export interface HookPayload {
+    session_id?: string;
+    transcript_path?: string;
+    cwd?: string;
+    hook_event_name?: string;
+    source?: string;
+    prompt?: string;
+    stop_hook_active?: boolean;
+}
+export type HookStatus = 
+/** Something was printed. */
+"ok"
+/** Ran fine, had nothing to print. Zero hits is this, not a failure. */
+ | "empty"
+/** Deliberately did not run: no payload, no session, re-entrant Stop. */
+ | "skipped"
+/** Tried and could not: an outage, a refusal, a deadline. */
+ | "failed";
+export interface HookOutcome {
+    status: HookStatus;
+    /** Named on every branch, success included. Never a bare "failed". */
+    reason: string;
+    /** Printed to stdout, or empty. Never partial. */
+    stdout: string;
+    /** Counts for the receipt line. Metadata only — never any text. */
+    hits?: number;
+    saved?: number;
+    chars?: number;
+    /** How many secret-like spans were masked before a save. A count, never a value. */
+    masked?: number;
+}
+/** The container this hook's memories live in, and how it was derived. */
+export interface HookContainer {
+    containerTag: string;
+    basis: string;
+}
+/** The wrappers Claude Code injects verbatim. Kept in one place, tested. */
+export declare const CONTEXT_BLOCK: {
+    readonly open: "<bli-memory-context>";
+    readonly close: "</bli-memory-context>";
+};
+export declare const RECALL_BLOCK: {
+    readonly open: "<bli-memory-recall>";
+    readonly close: "</bli-memory-recall>";
+};
+/** The vendor plugin's bullet, kept byte for byte so the injection reads the same. */
+export declare const BULLET = "\u25EA";
+/** The per-prompt recall shape the `/v4/profile` shim documents: top 5, ≥ 0.55. */
+export declare const RECALL_MIN_SIMILARITY = 0.55;
+export declare const RECALL_LIMIT = 5;
+/** One recalled line, capped. The vendor truncated at 300 characters. */
+export declare const RECALL_LINE_CHARS = 300;
+/** The search door refuses a query over 1000 characters; a long prompt is trimmed, not dropped. */
+export declare const MAX_QUERY_CHARS = 1000;
+/** At most the final 12 KB of the last exchange travels to `save`. */
+export declare const STOP_CHUNK_CHARS = 12000;
+export declare function hookEventFromArgv(argv: readonly string[]): HookEvent | null;

package/dist/hooks/contract.js

@@ -0,0 +1,72 @@
+/**
+ * The three Claude Code hooks — the vocabulary they all share (BLI-3580).
+ *
+ * `cockpit memory install` registers three hook commands on every machine
+ * (`memory-install-contract.ts`):
+ *
+ *   SessionStart      bli-memory-mcp hook session-start   timeout 30 s
+ *   UserPromptSubmit  bli-memory-mcp hook prompt          timeout  5 s
+ *   Stop              bli-memory-mcp hook stop            timeout 30 s
+ *
+ * **A hook that hangs is worse than a hook that does nothing.** Claude Code
+ * runs `UserPromptSubmit` on every prompt a person types and waits for it, so a
+ * hook that blocks on stdin, or on a dashboard that is not answering, costs
+ * every person on the fleet its timeout on every turn. That is the failure this
+ * file's budgets exist to make impossible: each event has a TOTAL deadline
+ * strictly below the installer's timeout for it, a stdin read deadline inside
+ * that, and a request deadline inside that. On any deadline the hook prints
+ * nothing and exits 0.
+ *
+ * **Exit 0, always.** Claude Code treats exit 2 as "block this" and any other
+ * non-zero as an error it shows the person. Neither is ever the right answer
+ * for a memory recall: an unpaired machine, an outage or a malformed payload
+ * must be invisible in the transcript and visible in stderr. `hook.ts` is the
+ * one place that decides the exit code, and it only ever decides 0.
+ *
+ * **Print nothing, or print exactly one block.** stdout of a SessionStart or
+ * UserPromptSubmit hook is injected into the model's context verbatim, so an
+ * empty result prints NOTHING rather than a "no memories found" line the model
+ * would then reason about.
+ */
+/** The three subcommands, exactly as the installer writes them. */
+export const HOOK_EVENTS = ["session-start", "prompt", "stop"];
+/**
+ * Deadlines, in ms, against the installer's timeouts of 30 s / 5 s / 30 s.
+ *
+ * Each total leaves the host real headroom rather than racing it: a hook killed
+ * by its host reports NOTHING — no stderr line, no reason — and that is exactly
+ * the kind of silence this repo's logging rule exists to prevent. Better to
+ * abandon the recall ourselves and say why.
+ */
+export const HOOK_BUDGETS = {
+    "session-start": { totalMs: 8_000, stdinMs: 2_000, requestMs: 6_000, gitMs: 2_500 },
+    // A person is waiting on this one with their prompt already typed.
+    prompt: { totalMs: 3_000, stdinMs: 1_000, requestMs: 2_200, gitMs: 700 },
+    // `extract` mode runs one model call server-side, so this one is allowed to
+    // be slow — it prints nothing either way, so nobody is waiting on it.
+    stop: { totalMs: 15_000, stdinMs: 3_000, requestMs: 13_000, gitMs: 2_500 },
+};
+/** The wrappers Claude Code injects verbatim. Kept in one place, tested. */
+export const CONTEXT_BLOCK = {
+    open: "<bli-memory-context>",
+    close: "</bli-memory-context>",
+};
+export const RECALL_BLOCK = {
+    open: "<bli-memory-recall>",
+    close: "</bli-memory-recall>",
+};
+/** The vendor plugin's bullet, kept byte for byte so the injection reads the same. */
+export const BULLET = "◪";
+/** The per-prompt recall shape the `/v4/profile` shim documents: top 5, ≥ 0.55. */
+export const RECALL_MIN_SIMILARITY = 0.55;
+export const RECALL_LIMIT = 5;
+/** One recalled line, capped. The vendor truncated at 300 characters. */
+export const RECALL_LINE_CHARS = 300;
+/** The search door refuses a query over 1000 characters; a long prompt is trimmed, not dropped. */
+export const MAX_QUERY_CHARS = 1_000;
+/** At most the final 12 KB of the last exchange travels to `save`. */
+export const STOP_CHUNK_CHARS = 12_000;
+export function hookEventFromArgv(argv) {
+    const value = (argv[0] ?? "").trim();
+    return HOOK_EVENTS.includes(value) ? value : null;
+}

package/dist/hooks/prompt.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `bli-memory-mcp hook prompt` (BLI-3580).
+ *
+ * UserPromptSubmit fires on EVERY prompt a person types, and Claude Code waits
+ * for it. This is the hook whose budget matters most: 3 s total against the
+ * installer's 5 s timeout, one search, print or print nothing.
+ *
+ * The recall shape is the vendor's, kept so the injection reads the same: the
+ * prompt itself is the query, hits below 0.55 similarity are dropped, at most
+ * five survive, each capped at 300 characters.
+ *
+ * **Zero hits is data.** It prints nothing and exits 0 with `no_hits`. A search
+ * that could NOT run is a different line with a different reason, because an
+ * agent (or a person reading stderr) that cannot tell those apart will read an
+ * outage as an empty shelf — the wire contract the search door states in its
+ * own header.
+ */
+import { type HookOutcome } from "./contract.js";
+import type { HookRunContext } from "./run-context.js";
+export declare function runPromptHook(context: HookRunContext): Promise<HookOutcome>;

package/dist/hooks/prompt.js

@@ -0,0 +1,111 @@
+/**
+ * `bli-memory-mcp hook prompt` (BLI-3580).
+ *
+ * UserPromptSubmit fires on EVERY prompt a person types, and Claude Code waits
+ * for it. This is the hook whose budget matters most: 3 s total against the
+ * installer's 5 s timeout, one search, print or print nothing.
+ *
+ * The recall shape is the vendor's, kept so the injection reads the same: the
+ * prompt itself is the query, hits below 0.55 similarity are dropped, at most
+ * five survive, each capped at 300 characters.
+ *
+ * **Zero hits is data.** It prints nothing and exits 0 with `no_hits`. A search
+ * that could NOT run is a different line with a different reason, because an
+ * agent (or a person reading stderr) that cannot tell those apart will read an
+ * outage as an empty shelf — the wire contract the search door states in its
+ * own header.
+ */
+import { doorReason, postMemoryDoor } from "../door.js";
+import { HOOK_BUDGETS, MAX_QUERY_CHARS, RECALL_LIMIT, RECALL_MIN_SIMILARITY, } from "./contract.js";
+import { renderRecall } from "./render.js";
+export async function runPromptHook(context) {
+    const budget = HOOK_BUDGETS.prompt;
+    const prompt = (context.payload.prompt ?? "").trim();
+    if (prompt.length === 0) {
+        return { status: "skipped", reason: "no_prompt", stdout: "" };
+    }
+    const response = await postMemoryDoor({
+        session: context.session,
+        fetchImpl: context.fetchImpl,
+        path: "/api/memory/search",
+        body: {
+            // The door refuses a query over 1000 characters. A long prompt is
+            // trimmed rather than dropped: its opening is what names the subject.
+            query: prompt.slice(0, MAX_QUERY_CHARS),
+            // A list of one, because the door takes a list — a second space (a
+            // person's, an org's) unions in later with no change on this wire.
+            containerTags: [context.container.containerTag],
+            limit: RECALL_LIMIT,
+            // The recency channel is a session-start concern; a per-turn recall that
+            // always carries the same newest rows trains the model to ignore it.
+            includeProfile: false,
+        },
+        timeoutMs: budget.requestMs,
+    });
+    if (!response.ok) {
+        return { status: "failed", reason: doorReason(response), stdout: "", hits: 0 };
+    }
+    const memories = readHits(response.body["results"]);
+    const degraded = typeof response.body["degraded"] === "string" && response.body["degraded"]
+        ? String(response.body["degraded"])
+        : null;
+    const stdout = renderRecall(memories);
+    if (stdout.length === 0) {
+        // Zero hits and a degraded search are different facts, and an operator
+        // reading the log needs to tell them apart: the first says the record is
+        // silent, the second says one channel did not run.
+        return {
+            status: "empty",
+            reason: degraded ? `no_hits:${degraded}` : "no_hits",
+            stdout: "",
+            hits: 0,
+        };
+    }
+    return {
+        status: "ok",
+        reason: degraded ? `recall_injected:${degraded}` : "recall_injected",
+        stdout,
+        hits: memories.length,
+        chars: stdout.length,
+    };
+}
+/**
+ * The vendor's floor, applied to the vendor's channel only.
+ *
+ * `similarity` on our door is **cosine similarity, zero when a row came only
+ * from the lexical or recency channel** (`agent-memories/search.ts:74`). The
+ * vendor filtered at 0.55 against a store where every hit was semantic; doing
+ * that here would drop every keyword match, and on a deployment with no
+ * embedding credential it would drop EVERY hit — a recall that silently returns
+ * nothing forever while the door reports `degraded` and nobody reads it.
+ *
+ * So the floor governs SEMANTIC hits and nothing else: a row the semantic
+ * channel scored has to clear 0.55, and a row it did not score at all is judged
+ * by the door's own ranking, which already put it in the top `limit`.
+ */
+function readHits(value) {
+    if (!Array.isArray(value))
+        return [];
+    const kept = [];
+    for (const row of value) {
+        if (!row || typeof row !== "object")
+            continue;
+        const record = row;
+        const memory = record["memory"];
+        if (typeof memory !== "string" || memory.trim().length === 0)
+            continue;
+        const similarity = Number(record["similarity"] ?? 0);
+        const channels = record["channels"];
+        const scoredSemantically = Array.isArray(channels)
+            ? channels.includes("semantic")
+            : // An older door that does not report channels: a non-zero similarity is
+                // the only evidence the semantic channel scored this row.
+                Number.isFinite(similarity) && similarity > 0;
+        if (scoredSemantically && !(similarity >= RECALL_MIN_SIMILARITY))
+            continue;
+        kept.push(memory);
+        if (kept.length >= RECALL_LIMIT)
+            break;
+    }
+    return kept;
+}

package/dist/hooks/redact.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Mask the secret, keep the memory (BLI-3580).
+ *
+ * The Stop hook sends a slice of a real conversation to `save`, and a
+ * conversation is exactly where a pasted API key lives. This is the SAME
+ * redaction the collector applies to every transcript it uploads — literally
+ * the same function, `redactSecretLikeContent` from `@bli-cockpit/telemetry-core`
+ * — rather than a second pattern list that drifts from it. That package is
+ * published, tiny (zod only) and already a dependency of the public CLI, so
+ * this package can depend on it without dragging the collector along.
+ *
+ * The collector's doctrine holds here too (`raw-evidence-sanitize.ts`,
+ * BLI-2581): **masking never drops the payload.** A match replaces the matched
+ * span with `[REDACTED:<rule>]` and everything else travels. A crash inside the
+ * redactor is caught and the hook saves nothing rather than saving unmasked
+ * text — the one place this file is stricter than the collector, because a
+ * memory is stored forever and read by a model, while a transcript upload is
+ * read by a pipeline that tracks its own gaps.
+ */
+export interface RedactionOutcome {
+    ok: boolean;
+    text: string;
+    /** How many secret-like spans were masked. A count, never the values. */
+    masked: number;
+    /** Set only when the redactor itself failed; then `ok` is false. */
+    reason?: string;
+}
+export declare function maskSecretsForMemory(text: string): RedactionOutcome;