@bli-cockpit/memory-mcp 0.1.5 → 0.1.6

package/README.md

@@ -81,15 +81,18 @@ Each reads Claude Code's JSON payload on stdin and:
 |---|---|---|---|
 | `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 |
+| `stop` | `transcript_path` | `POST /api/memory/save` in `extract` mode — the door answers **202 queued** and distils after the response (BLI-3730) | 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.
+  registers — 8 s / **2 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. The prompt hook's budget is sized to the PERSON
+  waiting with a prompt already typed, not to the host's 5 s ceiling
+  (BLI-3730): nobody notices a recall that gives up under its timeout,
+  everybody notices a turn that stalls before the model starts.
 - **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.
@@ -98,9 +101,9 @@ every machine:
   the same to it. Zero hits is data and prints nothing.
 - **One stderr receipt per run**, on every branch, one of three shapes
   (BLI-3664, `hooks/log-line.ts`):
-  `[bli-memory] prompt ok {"hits":0,"elapsed_ms":140,"deadline_ms":3000}`,
+  `[bli-memory] prompt ok {"hits":0,"elapsed_ms":140,"deadline_ms":2000}`,
   `[bli-memory] prompt skipped {"reason":"no_prompt"}`, or
-  `[bli-memory] prompt failed {"reason":"dashboard_unreachable","elapsed_ms":2201,"deadline_ms":3000}`.
+  `[bli-memory] prompt failed {"reason":"dashboard_unreachable","elapsed_ms":1502,"deadline_ms":2000}`.
   `reason` on `skipped`/`failed` is always one of a closed set — the four
   network reasons `timeout`, `http_<status>`, `dashboard_unreachable`,
   `bad_response` (Tower answered with a body that was not readable JSON);
@@ -112,10 +115,12 @@ every machine:
   `redaction_failed`) — never a stack trace, never Tower's own error text,
   never a prompt, a memory, a path or a token. A reason `toLogReason` has not
   been taught becomes `unknown_internal:<name>`, never a silent
-  `bad_response`. A `failed` outcome also gets a one-line `systemMessage` (the
+  `bad_response`. A `failed` **stop** also gets a one-line `systemMessage` (the
   same JSON-on-stdout shape the Supermemory plugin's own banner uses),
   because Claude Code does not surface a hook's stderr anywhere a person
-  reads it.
+  reads it and a failed save means the turn was not kept. A failed RECALL is
+  silent (BLI-3730): it costs the person nothing and a banner on every prompt
+  during an outage is noise they cannot act on.
 
 `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 —
@@ -124,6 +129,15 @@ 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.
 
+Since BLI-3730 the door **queues** that work: it writes one durable
+`memory_extract_jobs` row, answers 202, and distils after the response, so the
+hook reports `ok {"chars":…,"masked":…,"queued":true}` and never claims a save
+it cannot see. `saved` is absent on that branch rather than 0 — "accepted,
+pending" and "nothing was worth keeping" must never read as the same line. The
+outcome lands on the job row and in Tower's own
+`[bli-memory] extract job done {added, updated, unchanged, conflicted,
+extract_ms, reconcile_ms}`.
+
 ## Auth
 
 None to set up. The server reads the collector's existing paired session at

package/dist/hooks/contract.d.ts

@@ -101,6 +101,14 @@ export interface HookOutcome {
      * HTTP 200.
      */
     conflicts?: number;
+    /**
+     * BLI-3730: the door accepted the turn and will distil it after the
+     * response (HTTP 202). The hook cannot say what was saved — nothing has been
+     * yet — so it says the true thing instead of guessing, and `saved` stays
+     * absent rather than being reported as 0, which would read as "nothing was
+     * worth keeping".
+     */
+    queued?: boolean;
 }
 /** The container this hook's memories live in, and how it was derived. */
 export interface HookContainer {

package/dist/hooks/contract.js

@@ -40,10 +40,25 @@ export const HOOK_EVENTS = ["session-start", "prompt", "stop"];
  */
 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.
+    /**
+     * A person is waiting on this one with their prompt already typed, so the
+     * whole run is capped at TWO SECONDS and the door call at 1,500 ms
+     * (BLI-3730). The old 3,000/2,200 pair was chosen against the installer's
+     * 5 s host timeout, which is the wrong number to size against: nobody
+     * notices a hook that gives up under its host's ceiling, everybody notices
+     * a turn that stalls for three seconds before the model starts. A recall
+     * that misses this window prints NOTHING and logs `timeout` — the shelf is
+     * not worth the wait, and the person never finds out, by design.
+     */
+    prompt: { totalMs: 2_000, stdinMs: 600, requestMs: 1_500, gitMs: 500 },
+    /**
+     * `extract` mode is queued server-side now (BLI-3730): the door writes a
+     * durable job, answers 202 and does the model work after the response, so
+     * this hook is waiting on one INSERT rather than on two model calls and
+     * twelve neighbour searches. The generous budget stays anyway — it prints
+     * nothing either way, and the one thing worse than a slow Stop hook is a
+     * Stop hook that abandons a save the door was about to accept.
+     */
     stop: { totalMs: 15_000, stdinMs: 3_000, requestMs: 13_000, gitMs: 2_500 },
 };
 /** The wrappers Claude Code injects verbatim. Kept in one place, tested. */

package/dist/hooks/log-line.d.ts

@@ -15,7 +15,8 @@
  *  1. **stderr, on every branch, one line, one shape.** `buildLogLine` below.
  *     This is what an operator tailing a launchd-style log — or a future
  *     collector upload of hook logs — can grep.
- *  2. **`systemMessage`, on `failed` only.** Claude Code does not surface a
+ *  2. **`systemMessage`, on a failed STOP only** (narrowed in BLI-3730 — see
+ *     `buildSystemMessage`; a failed recall is silent). Claude Code does not surface a
  *     hook's stderr as a visible line; the Supermemory plugin's own banner
  *     (`~/.claude/plugins/.../recall-directive.js`) is a JSON object on
  *     STDOUT carrying a `systemMessage` field (`hooks/stdin.js:writeOutput`,
@@ -81,13 +82,14 @@ export declare function toLogReason(reason: string): HookLogReason;
  */
 export declare function buildLogLine(event: HookEvent, outcome: HookOutcome, elapsedMs: number, deadlineMs: number): string;
 /**
- * One short sentence for a `failed` outcome only, in the JSON envelope the
- * host actually renders (`{"systemMessage": "…"}` on stdout — see the
+ * One short sentence for a `failed` STOP outcome only, in the JSON envelope
+ * the host actually renders (`{"systemMessage": "…"}` on stdout — see the
  * Supermemory mechanism cited in this file's header). `null` on every other
  * branch: `ok`/`empty` already say their piece through the injected block,
- * and `skipped` is a deliberate no-op nobody needs interrupted for.
+ * `skipped` is a deliberate no-op nobody needs interrupted for, and a failed
+ * RECALL is not a person's problem (BLI-3730).
  */
-export declare function buildSystemMessage(outcome: HookOutcome): string | null;
+export declare function buildSystemMessage(event: HookEvent, outcome: HookOutcome): string | null;
 /** Renders one JSON block to stdout — the only shape a hook may emit there
  * besides plain injected context. Used by `run.ts` on `failed` only, so the
  * "one block or nothing" stdout contract for every other branch is untouched. */

package/dist/hooks/log-line.js

@@ -15,7 +15,8 @@
  *  1. **stderr, on every branch, one line, one shape.** `buildLogLine` below.
  *     This is what an operator tailing a launchd-style log — or a future
  *     collector upload of hook logs — can grep.
- *  2. **`systemMessage`, on `failed` only.** Claude Code does not surface a
+ *  2. **`systemMessage`, on a failed STOP only** (narrowed in BLI-3730 — see
+ *     `buildSystemMessage`; a failed recall is silent). Claude Code does not surface a
  *     hook's stderr as a visible line; the Supermemory plugin's own banner
  *     (`~/.claude/plugins/.../recall-directive.js`) is a JSON object on
  *     STDOUT carrying a `systemMessage` field (`hooks/stdin.js:writeOutput`,
@@ -138,21 +139,35 @@ export function buildLogLine(event, outcome, elapsedMs, deadlineMs) {
                 // nothing AND conflicted with nothing is a materially different
                 // fact from one that conflicted on every candidate.
                 ...(outcome.conflicts === undefined ? {} : { conflicts: outcome.conflicts }),
+                // BLI-3730: the door took the turn and will distil it after the
+                // response. Printed so `ok {queued:true}` and `ok {saved:0}` —
+                // "accepted, pending" and "nothing worth keeping" — can never be
+                // read as the same line.
+                ...(outcome.queued === undefined ? {} : { queued: outcome.queued }),
                 elapsed_ms: elapsedMs,
                 deadline_ms: deadlineMs,
             };
     return `${HOOK_LOG_TAG} ${event} ${word} ${JSON.stringify(fields)}\n`;
 }
 /**
- * One short sentence for a `failed` outcome only, in the JSON envelope the
- * host actually renders (`{"systemMessage": "…"}` on stdout — see the
+ * One short sentence for a `failed` STOP outcome only, in the JSON envelope
+ * the host actually renders (`{"systemMessage": "…"}` on stdout — see the
  * Supermemory mechanism cited in this file's header). `null` on every other
  * branch: `ok`/`empty` already say their piece through the injected block,
- * and `skipped` is a deliberate no-op nobody needs interrupted for.
+ * `skipped` is a deliberate no-op nobody needs interrupted for, and a failed
+ * RECALL is not a person's problem (BLI-3730).
  */
-export function buildSystemMessage(outcome) {
+export function buildSystemMessage(event, outcome) {
     if (outcome.status !== "failed")
         return null;
+    // BLI-3730: RECALL is silent, always. A `UserPromptSubmit` or `SessionStart`
+    // hook that could not reach Tower has cost the person nothing — the turn
+    // runs, the model simply has one fewer source — and a banner on every
+    // prompt during an outage is noise a person cannot act on and cannot turn
+    // off. The Stop hook is different in kind: it is the only hook that WRITES,
+    // and a failure there means the turn was not kept. That is worth one line.
+    if (event !== "stop")
+        return null;
     return `BLI Memory: ${failureSentence(toLogReason(outcome.reason))}`;
 }
 function failureSentence(reason) {

package/dist/hooks/run.d.ts

@@ -15,10 +15,12 @@
  *     memory recall may never do either.
  *  3. **stdout discipline.** Nothing is written until the hook has finished and
  *     produced a whole block. A partial injection is worse than none — with
- *     ONE exception, added in BLI-3664: a `failed` outcome also gets a single
- *     `{"systemMessage": "…"}` JSON block, because that is the one shape
- *     Claude Code actually renders to a person (see `log-line.ts`'s header).
- *     Every other status's stdout is exactly as before.
+ *     ONE exception, added in BLI-3664 and narrowed in BLI-3730: a `failed`
+ *     STOP outcome also gets a single `{"systemMessage": "…"}` JSON block,
+ *     because that is the one shape Claude Code actually renders to a person
+ *     (see `log-line.ts`'s header) and a lost SAVE is worth a line. A failed
+ *     recall is silent — it costs the person nothing and they cannot act on
+ *     it. Every other status's stdout is exactly as before.
  *  4. **One stderr receipt per run, on every branch.** `[bli-memory] <event>
  *     ok|skipped|failed {…}` (`log-line.ts:buildLogLine`) — metadata only,
  *     never a prompt, a memory, a path or a token, and a `reason` drawn from a

package/dist/hooks/run.js

@@ -15,10 +15,12 @@
  *     memory recall may never do either.
  *  3. **stdout discipline.** Nothing is written until the hook has finished and
  *     produced a whole block. A partial injection is worse than none — with
- *     ONE exception, added in BLI-3664: a `failed` outcome also gets a single
- *     `{"systemMessage": "…"}` JSON block, because that is the one shape
- *     Claude Code actually renders to a person (see `log-line.ts`'s header).
- *     Every other status's stdout is exactly as before.
+ *     ONE exception, added in BLI-3664 and narrowed in BLI-3730: a `failed`
+ *     STOP outcome also gets a single `{"systemMessage": "…"}` JSON block,
+ *     because that is the one shape Claude Code actually renders to a person
+ *     (see `log-line.ts`'s header) and a lost SAVE is worth a line. A failed
+ *     recall is silent — it costs the person nothing and they cannot act on
+ *     it. Every other status's stdout is exactly as before.
  *  4. **One stderr receipt per run, on every branch.** `[bli-memory] <event>
  *     ok|skipped|failed {…}` (`log-line.ts:buildLogLine`) — metadata only,
  *     never a prompt, a memory, a path or a token, and a `reason` drawn from a
@@ -63,7 +65,7 @@ export async function runHook(event, deps = {}) {
         // prints nothing to the model (no additionalContext), but DOES get a
         // `systemMessage` block, which is a status banner, not a memory. Every
         // other status's stdout is unchanged from before BLI-3664.
-        const systemMessage = buildSystemMessage(outcome);
+        const systemMessage = buildSystemMessage(event, outcome);
         if (systemMessage) {
             stdout.write(`${renderSystemMessageBlock(systemMessage)}\n`);
         }

package/dist/hooks/stop.d.ts

@@ -16,6 +16,13 @@
  *    nothing saved, `reentrant`.
  *  - Nothing is printed on stdout, ever. Stop's stdout is shown to the person
  *    in transcript mode, and "I saved a memory" on every turn is noise.
+ *
+ * BLI-3730: the door answers **202** for `mode: "extract"` — it writes a
+ * durable job and distils it after the response — so the normal successful
+ * outcome here is `queued`, with no decisions to count. The synchronous
+ * branch below is kept for a `wait: true` caller and for a Tower old enough
+ * to still answer 200 with decisions; it is not dead code, it is the older
+ * half of a wire contract that has to keep working during a rollout.
  */
 import { type HookOutcome } from "./contract.js";
 import type { HookRunContext } from "./run-context.js";

package/dist/hooks/stop.js

@@ -16,6 +16,13 @@
  *    nothing saved, `reentrant`.
  *  - Nothing is printed on stdout, ever. Stop's stdout is shown to the person
  *    in transcript mode, and "I saved a memory" on every turn is noise.
+ *
+ * BLI-3730: the door answers **202** for `mode: "extract"` — it writes a
+ * durable job and distils it after the response — so the normal successful
+ * outcome here is `queued`, with no decisions to count. The synchronous
+ * branch below is kept for a `wait: true` caller and for a Tower old enough
+ * to still answer 200 with decisions; it is not dead code, it is the older
+ * half of a wire contract that has to keep working during a rollout.
  */
 import { createHash } from "node:crypto";
 import { doorReason, postMemoryDoor } from "../door.js";
@@ -75,6 +82,25 @@ export async function runStopHook(context, options = {}) {
     if (!response.ok) {
         return { status: "failed", reason: doorReason(response), stdout: "", saved: 0 };
     }
+    // BLI-3730: the door queued it. Extraction is one model call (two on the
+    // BLI-3713 retry) plus one embed and one neighbour search per fact, and on
+    // 2026-09-05 twelve facts outran this hook's whole 15 s deadline — every
+    // turn ended with "BLI Memory: Tower did not answer in time" while the work
+    // was still in flight. The door writes a durable job row, answers 202 and
+    // does the work after the response, so this hook is now waiting on one
+    // INSERT. Nothing is claimed saved, because nothing is yet: `queued` is the
+    // true thing to report, and `saved` stays absent rather than 0, which would
+    // read as "nothing was worth keeping".
+    if (response.status === 202 || response.body["queued"] === true) {
+        return {
+            status: "ok",
+            reason: "queued",
+            stdout: "",
+            queued: true,
+            chars: masked.text.length,
+            masked: masked.masked,
+        };
+    }
     const decisionsRaw = response.body["decisions"];
     const decisions = Array.isArray(decisionsRaw)
         ? decisionsRaw.filter((decision) => Boolean(decision) && typeof decision === "object")

package/dist/server.js

@@ -229,6 +229,12 @@ export function createServer(deps) {
             containerTag,
             customId: args.customId,
             mode: args.extract ? "extract" : "verbatim",
+            // BLI-3730: `extract` is queued by default (the Stop hook cannot hold
+            // a connection through two model calls). An agent that ASKED for
+            // distillation is a different caller: it is waiting for the answer and
+            // its host allows far longer than a Stop hook does, so this tool takes
+            // the synchronous branch and can still report what was written.
+            ...(args.extract ? { wait: true } : {}),
             sourceRef: { kind: "mcp", device_id: deps.session.deviceId },
         });
         if (!response.ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/memory-mcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "private": false,
   "description": "BLI Memory — an MCP server for the memory layer BLI owns (save, search, update, forget).",
   "type": "module",