@bli-cockpit/memory-mcp 0.1.4 → 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,17 +101,26 @@ 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}`.
-  `reason` on `skipped`/`failed` is always one of a closed set — `timeout`,
-  `http_<status>`, `unpaired`, `dashboard_unreachable`, `bad_response`,
-  `no_prompt`, plus three Stop-only local skips (`reentrant`, `no_transcript`,
+  `[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);
+  the six `StdinFailure` reasons `no_stdin`, `stdin_empty`, `stdin_timeout`,
+  `stdin_too_large`, `stdin_unreadable`, `stdin_malformed` — each its own
+  literal, never folded into `bad_response`, because a malformed payload from
+  the host never touched the network (BLI-3700); `unpaired`, `no_prompt`,
+  plus three Stop-only local skips (`reentrant`, `no_transcript`,
   `redaction_failed`) — never a stack trace, never Tower's own error text,
-  never a prompt, a memory, a path or a token. A `failed` outcome 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.
+  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` **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 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 —
@@ -117,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

@@ -93,6 +93,22 @@ export interface HookOutcome {
     chars?: number;
     /** How many secret-like spans were masked before a save. A count, never a value. */
     masked?: number;
+    /**
+     * BLI-3718: how many extracted facts collided with another live memory's
+     * custom_id rather than being written. Counted SEPARATELY from `saved` so a
+     * session where every candidate conflicted reads as `custom_id_conflict`,
+     * never as `nothing_worth_keeping` — the two used to be indistinguishable at
+     * 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 {
@@ -110,11 +126,32 @@ export declare const RECALL_BLOCK: {
 };
 /** 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. */
+/**
+ * The vendor's own per-prompt recall floor. Kept only as the FALLBACK for a
+ * door old enough not to send its own `semanticFloor` on the search response
+ * (BLI-3697 tick 8) — the live floor is read from that response, never
+ * hardcoded here, because three tickets already moved the door's real
+ * number (0.55 -> 0.30 -> 0.65) while this constant sat still.
+ */
 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;
+/**
+ * One recalled memory, its text and when it was written (BLI-3697 tick 8).
+ * A fact that changes over time — a version number, a decision, a status —
+ * read back with no date is a trap: the QA loop found a `min_cli_version`
+ * row from 2026-08-18 answering "what is the CLI floor" at rank 1, true in
+ * August and wrong by the time it was read. `renderRecall` prefixes every
+ * line with its date rather than trying to decide which rows count as
+ * "stale" — that judgment belongs to whoever reads the recall, and they
+ * cannot make it at all if the date is missing.
+ */
+export interface RecalledHit {
+    text: string;
+    /** ISO timestamp, or `null` when the door did not send one. */
+    createdAt: string | null;
+}
 /** 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`. */

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. */
@@ -57,7 +72,13 @@ export const RECALL_BLOCK = {
 };
 /** 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. */
+/**
+ * The vendor's own per-prompt recall floor. Kept only as the FALLBACK for a
+ * door old enough not to send its own `semanticFloor` on the search response
+ * (BLI-3697 tick 8) — the live floor is read from that response, never
+ * hardcoded here, because three tickets already moved the door's real
+ * number (0.55 -> 0.30 -> 0.65) while this constant sat still.
+ */
 export const RECALL_MIN_SIMILARITY = 0.55;
 export const RECALL_LIMIT = 5;
 /** One recalled line, capped. The vendor truncated at 300 characters. */

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`,
@@ -23,28 +24,42 @@
  *     same shape so a real failure — not a quiet turn — is the one case a
  *     person actually sees something.
  *
- * **The reason vocabulary is closed and lives HERE, in one module.** Six
- * members answer the ticket's own question (can a timeout, a 5xx, a dead
- * dashboard and "nothing to say" be told apart?): `timeout`, `http_<status>`,
- * `unpaired`, `dashboard_unreachable`, `bad_response`, `no_prompt`. Three more
- * cover skip states that are local to one hook and never touch the network —
- * `reentrant` (Stop, re-entrant), `no_transcript` (Stop, nothing to read yet)
- * and `redaction_failed` (Stop, the masking pass itself failed) — kept as
- * their own fixed literals rather than folded into a network bucket, because
- * calling a re-entrant Stop hook `bad_response` would tell an operator a
- * request failed when nothing was even attempted. Every one of the nine is a
- * compile-time literal from OUR OWN code; none of them is `response.body`
- * text, an `error.message`, or a stack trace (`door.ts`'s `doorReason` already
- * enforces that at the source for the network four). `toLogReason` maps every
- * other internal reason string this package can produce onto one of the nine,
- * and anything it does not recognise — a future reason nobody wired in here —
- * falls back to `bad_response` rather than printing unbounded text.
+ * **The reason vocabulary is closed and lives HERE, in one module.** Four
+ * members answer the network half of the ticket's own question (can a
+ * timeout, a 5xx and a dead dashboard be told apart?): `timeout`,
+ * `http_<status>`, `dashboard_unreachable`, `bad_response` — the last of
+ * those meaning specifically "Tower answered with a status but a body that
+ * was not readable JSON" (`door.ts`'s `doorReason`). Six more are the
+ * **caller's own stdin**, one per `stdin.ts` `StdinFailure` member —
+ * `no_stdin`, `stdin_empty`, `stdin_timeout`, `stdin_too_large`,
+ * `stdin_unreadable`, `stdin_malformed` — kept as their OWN literals rather
+ * than folded into `bad_response`, because a malformed payload from the host
+ * never touched the network at all (BLI-3700, QA tick 6 NEW-9: a plain-text
+ * stdin payload printed `bad_response` and read as a Tower outage for four
+ * runs that never made a request). `unpaired` and `no_prompt` round those
+ * out, and three more cover skip states local to one hook that never touch
+ * the network either — `reentrant` (Stop, re-entrant), `no_transcript`
+ * (Stop, nothing to read yet) and `redaction_failed` (Stop, the masking pass
+ * itself failed). Every member is a compile-time literal from OUR OWN code;
+ * none of them is `response.body` text, an `error.message`, or a stack trace
+ * (`door.ts`'s `doorReason` already enforces that at the source for the
+ * network four). `toLogReason` maps every other internal reason string this
+ * package can produce onto one of these, and anything it does not recognise —
+ * a future reason nobody wired in here — becomes `unknown_internal:<name>`,
+ * never a silent `bad_response`: a reason this table has not been taught must
+ * say so, not point at the wrong system.
  */
 import type { HookEvent, HookOutcome, HookStatus } from "./contract.js";
 import type { DoorFailureReason } from "../door.js";
+import type { StdinFailure } from "./stdin.js";
 export declare const HOOK_LOG_TAG = "[bli-memory]";
-/** The closed set. Nine literals plus the parameterised `http_<status>` family. */
-export type HookLogReason = DoorFailureReason | "unpaired" | "no_prompt" | "reentrant" | "no_transcript" | "redaction_failed";
+/**
+ * The closed set: the door's four network members, the six `StdinFailure`
+ * members (BLI-3700 — never folded into a door reason), five more fixed
+ * local literals, and the `unknown_internal:<name>` escape hatch for a
+ * reason `toLogReason` has not been taught.
+ */
+export type HookLogReason = DoorFailureReason | StdinFailure | "unpaired" | "no_prompt" | "reentrant" | "no_transcript" | "redaction_failed" | `unknown_internal:${string}`;
 /** The word printed after the event name. `empty` (ran fine, nothing to say) prints as `ok`. */
 export type HookLogWord = "ok" | "skipped" | "failed";
 export declare function logWordFor(status: HookStatus): HookLogWord;
@@ -67,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`,
@@ -23,22 +24,30 @@
  *     same shape so a real failure — not a quiet turn — is the one case a
  *     person actually sees something.
  *
- * **The reason vocabulary is closed and lives HERE, in one module.** Six
- * members answer the ticket's own question (can a timeout, a 5xx, a dead
- * dashboard and "nothing to say" be told apart?): `timeout`, `http_<status>`,
- * `unpaired`, `dashboard_unreachable`, `bad_response`, `no_prompt`. Three more
- * cover skip states that are local to one hook and never touch the network —
- * `reentrant` (Stop, re-entrant), `no_transcript` (Stop, nothing to read yet)
- * and `redaction_failed` (Stop, the masking pass itself failed) — kept as
- * their own fixed literals rather than folded into a network bucket, because
- * calling a re-entrant Stop hook `bad_response` would tell an operator a
- * request failed when nothing was even attempted. Every one of the nine is a
- * compile-time literal from OUR OWN code; none of them is `response.body`
- * text, an `error.message`, or a stack trace (`door.ts`'s `doorReason` already
- * enforces that at the source for the network four). `toLogReason` maps every
- * other internal reason string this package can produce onto one of the nine,
- * and anything it does not recognise — a future reason nobody wired in here —
- * falls back to `bad_response` rather than printing unbounded text.
+ * **The reason vocabulary is closed and lives HERE, in one module.** Four
+ * members answer the network half of the ticket's own question (can a
+ * timeout, a 5xx and a dead dashboard be told apart?): `timeout`,
+ * `http_<status>`, `dashboard_unreachable`, `bad_response` — the last of
+ * those meaning specifically "Tower answered with a status but a body that
+ * was not readable JSON" (`door.ts`'s `doorReason`). Six more are the
+ * **caller's own stdin**, one per `stdin.ts` `StdinFailure` member —
+ * `no_stdin`, `stdin_empty`, `stdin_timeout`, `stdin_too_large`,
+ * `stdin_unreadable`, `stdin_malformed` — kept as their OWN literals rather
+ * than folded into `bad_response`, because a malformed payload from the host
+ * never touched the network at all (BLI-3700, QA tick 6 NEW-9: a plain-text
+ * stdin payload printed `bad_response` and read as a Tower outage for four
+ * runs that never made a request). `unpaired` and `no_prompt` round those
+ * out, and three more cover skip states local to one hook that never touch
+ * the network either — `reentrant` (Stop, re-entrant), `no_transcript`
+ * (Stop, nothing to read yet) and `redaction_failed` (Stop, the masking pass
+ * itself failed). Every member is a compile-time literal from OUR OWN code;
+ * none of them is `response.body` text, an `error.message`, or a stack trace
+ * (`door.ts`'s `doorReason` already enforces that at the source for the
+ * network four). `toLogReason` maps every other internal reason string this
+ * package can produce onto one of these, and anything it does not recognise —
+ * a future reason nobody wired in here — becomes `unknown_internal:<name>`,
+ * never a silent `bad_response`: a reason this table has not been taught must
+ * say so, not point at the wrong system.
  */
 export const HOOK_LOG_TAG = "[bli-memory]";
 export function logWordFor(status) {
@@ -68,13 +77,15 @@ export function toLogReason(reason) {
         case "session_missing_token":
             return "unpaired";
         // The host's own payload could not be used (stdin.ts's `StdinFailure`).
+        // Each keeps its own literal — never folded into `bad_response`, which
+        // names a Tower reply, not a caller-side stdin defect (BLI-3700).
         case "no_stdin":
         case "stdin_empty":
         case "stdin_timeout":
         case "stdin_too_large":
         case "stdin_unreadable":
         case "stdin_malformed":
-            return "bad_response";
+            return reason;
         // The prompt hook's own empty-prompt skip.
         case "no_prompt":
             return "no_prompt";
@@ -91,12 +102,16 @@ export function toLogReason(reason) {
         case "deadline_exceeded":
             return "timeout";
         default:
-            // A door's `http_<status>` template literal, or an unexpected
-            // `hook_threw:<Name>` — the request happened but produced something
-            // this hook could not act on. Never the raw string past this point.
+            // A door's `http_<status>` template literal passes through as-is; an
+            // unexpected reason nobody wired into this table — `hook_threw:<Name>`
+            // or a future internal reason — becomes `unknown_internal:<name>`
+            // rather than a silent `bad_response`, which would misname a caller-side
+            // or run-level defect as a Tower reply (BLI-3700). Never the raw
+            // string is dropped, and never is it printed unbounded: the name is
+            // one of OUR OWN reason literals, never `response.body` text.
             if (reason.startsWith("http_"))
                 return reason;
-            return "bad_response";
+            return `unknown_internal:${reason}`;
     }
 }
 /**
@@ -120,27 +135,50 @@ export function buildLogLine(event, outcome, elapsedMs, deadlineMs) {
                 ...(outcome.saved === undefined ? {} : { saved: outcome.saved }),
                 ...(outcome.chars === undefined ? {} : { chars: outcome.chars }),
                 ...(outcome.masked === undefined ? {} : { masked: outcome.masked }),
+                // BLI-3718: printed whenever set, including 0 — a save that wrote
+                // 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) {
     if (reason.startsWith("http_")) {
         return `Tower refused the request (${reason.slice("http_".length)}).`;
     }
+    if (reason.startsWith("unknown_internal:")) {
+        // A reason this table has not been taught. Named, never a crash, and
+        // never claims to know which system was at fault (BLI-3700).
+        return "something went wrong that this hook does not yet name.";
+    }
     switch (reason) {
         case "timeout":
             return "Tower did not answer in time.";
@@ -152,6 +190,24 @@ function failureSentence(reason) {
             return "this machine is not paired with Tower — run `cockpit login`.";
         case "redaction_failed":
             return "the turn could not be safely redacted before saving.";
+        // The six `StdinFailure` members (BLI-3700). Skip-only today —
+        // `readHookPayload` always returns these as a `skipped` outcome, so
+        // `buildSystemMessage` never reaches them in practice — but each still
+        // gets its own sentence, named rather than asserted unreachable, so a
+        // future change that DID route one through `failed` gets the right
+        // words instead of the wrong system's name.
+        case "no_stdin":
+            return "no payload arrived on stdin (not run from a host that pipes one).";
+        case "stdin_empty":
+            return "the payload on stdin was empty.";
+        case "stdin_timeout":
+            return "stdin never closed within this hook's own deadline.";
+        case "stdin_too_large":
+            return "the payload on stdin exceeded the size ceiling.";
+        case "stdin_unreadable":
+            return "the payload on stdin could not be read.";
+        case "stdin_malformed":
+            return "the payload on stdin was not readable JSON.";
         case "no_transcript":
         case "reentrant":
         case "no_prompt":
@@ -161,8 +217,9 @@ function failureSentence(reason) {
             // `failed` still gets a sentence instead of a crash.
             return "the recall did not run.";
         default:
-            // Unreached: the `http_` family returned above and every other member
-            // is handled. A safe sentence, never a crash, if that ever changes.
+            // Unreached: the `http_`/`unknown_internal:` families returned above
+            // and every other member is handled. A safe sentence, never a crash,
+            // if that ever changes.
             return "something went wrong.";
     }
 }

package/dist/hooks/prompt.d.ts

@@ -6,8 +6,13 @@
  * 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.
+ * prompt itself is the query, hits below the door's OWN floor are dropped
+ * (BLI-3697 tick 8: this hook used to keep a hardcoded 0.55 of its own,
+ * which drifted out of step when the door's floor moved across three
+ * tickets — the door's `semanticFloor` in the response is read instead now,
+ * `RECALL_MIN_SIMILARITY` surviving only as the fallback for an older
+ * deployment that does not send the field yet), 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

package/dist/hooks/prompt.js

@@ -6,8 +6,13 @@
  * 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.
+ * prompt itself is the query, hits below the door's OWN floor are dropped
+ * (BLI-3697 tick 8: this hook used to keep a hardcoded 0.55 of its own,
+ * which drifted out of step when the door's floor moved across three
+ * tickets — the door's `semanticFloor` in the response is read instead now,
+ * `RECALL_MIN_SIMILARITY` surviving only as the fallback for an older
+ * deployment that does not send the field yet), 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
@@ -45,7 +50,8 @@ export async function runPromptHook(context) {
     if (!response.ok) {
         return { status: "failed", reason: doorReason(response), stdout: "", hits: 0 };
     }
-    const memories = readHits(response.body["results"]);
+    const floor = doorFloor(response.body["semanticFloor"]);
+    const memories = readHits(response.body["results"], floor);
     const degraded = typeof response.body["degraded"] === "string" && response.body["degraded"]
         ? String(response.body["degraded"])
         : null;
@@ -70,20 +76,35 @@ export async function runPromptHook(context) {
     };
 }
 /**
- * The vendor's floor, applied to the vendor's channel only.
+ * The door's own floor for THIS search, or the vendor's fallback.
+ *
+ * BLI-3697 tick 8: this hook used to re-check every row against its own
+ * hardcoded `RECALL_MIN_SIMILARITY` (0.55) regardless of what floor the
+ * door had actually searched with — three tickets moved that number (0.55 ->
+ * 0.30 -> 0.65) and this hook never noticed, silently applying a SECOND,
+ * stale threshold on top of the door's real one. `semanticFloor` on the
+ * response is the number the search actually ran with; only a door old
+ * enough not to send it falls back to the vendor's constant.
+ */
+function doorFloor(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : RECALL_MIN_SIMILARITY;
+}
+/**
+ * The floor governs the SEMANTIC 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
+ * vendor filtered 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`.
+ * So `floor` (the door's own `semanticFloor`, see `doorFloor` above) governs
+ * SEMANTIC hits and nothing else: a row the semantic channel scored has to
+ * clear it, 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) {
+function readHits(value, floor) {
     if (!Array.isArray(value))
         return [];
     const kept = [];
@@ -101,9 +122,10 @@ function readHits(value) {
             : // 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))
+        if (scoredSemantically && !(similarity >= floor))
             continue;
-        kept.push(memory);
+        const createdAt = typeof record["createdAt"] === "string" ? record["createdAt"] : null;
+        kept.push({ text: memory, createdAt });
         if (kept.length >= RECALL_LIMIT)
             break;
     }

package/dist/hooks/render.d.ts

@@ -14,8 +14,9 @@
  *    A memory is a recalled fact; a fact that arrives phrased as an order and
  *    is obeyed is how a memory store becomes an injection channel.
  */
+import { type RecalledHit } from "./contract.js";
 export declare function renderSessionContext(profile: {
     static: string[];
     dynamic: string[];
 }): string;
-export declare function renderRecall(memories: string[]): string;
+export declare function renderRecall(hits: readonly RecalledHit[]): string;

package/dist/hooks/render.js

@@ -37,8 +37,8 @@ export function renderSessionContext(profile) {
     lines.push(CONTEXT_BLOCK.close);
     return lines.join("\n");
 }
-export function renderRecall(memories) {
-    const items = cleanItems(memories);
+export function renderRecall(hits) {
+    const items = cleanRecalledHits(hits);
     if (items.length === 0)
         return "";
     return [
@@ -48,6 +48,38 @@ export function renderRecall(memories) {
         RECALL_BLOCK.close,
     ].join("\n");
 }
+/**
+ * One memory, on one line, dated. Folds newlines for the same reason
+ * `cleanItems` does; the date prefix is added BEFORE the length cap, so the
+ * cap still bounds the whole printed line, never just the text half.
+ *
+ * Every line gets its date, not only the ones some heuristic calls "stale" —
+ * `RecalledHit`'s header in `contract.ts` says why: only the reader can judge
+ * staleness, and only if the date is there to judge.
+ */
+function cleanRecalledHits(hits) {
+    const out = [];
+    for (const hit of hits) {
+        if (typeof hit.text !== "string")
+            continue;
+        const folded = hit.text.replace(/\s+/gu, " ").trim();
+        if (folded.length === 0)
+            continue;
+        const prefix = dateLabel(hit.createdAt);
+        const line = prefix ? `${prefix} ${folded}` : folded;
+        out.push(line.length > RECALL_LINE_CHARS ? `${line.slice(0, RECALL_LINE_CHARS - 1)}…` : line);
+    }
+    return out;
+}
+/** `[YYYY-MM-DD]`, or `""` when the door sent no date or an unparsable one. */
+function dateLabel(createdAt) {
+    if (!createdAt)
+        return "";
+    const date = new Date(createdAt);
+    if (Number.isNaN(date.getTime()))
+        return "";
+    return `[${date.toISOString().slice(0, 10)}]`;
+}
 /**
  * One memory, on one line. Newlines are folded because a multi-line bullet
  * breaks the list the model is reading, and the cap is the vendor's 300.

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,19 +82,59 @@ export async function runStopHook(context, options = {}) {
     if (!response.ok) {
         return { status: "failed", reason: doorReason(response), stdout: "", saved: 0 };
     }
-    const decisions = response.body["decisions"];
-    const written = Array.isArray(decisions)
-        ? decisions.filter((decision) => decision &&
-            typeof decision === "object" &&
-            decision["verb"] !== "skip").length
+    // 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")
+        : null;
+    const written = decisions
+        ? decisions.filter((decision) => decision["verb"] !== "skip").length
         : response.body["id"]
             ? 1
             : 0;
+    // BLI-3718: a candidate that collided with another live memory's custom_id
+    // is counted SEPARATELY from `written` — it is neither a save nor "nothing
+    // worth keeping", and folding it into the latter is exactly how a session's
+    // second-and-later Stop hooks reported `{"skipped":N}` at HTTP 200 while a
+    // fact silently never landed.
+    const conflicted = decisions
+        ? decisions.filter((decision) => decision["reason"] === "custom_id_conflict").length
+        : 0;
+    if (written > 0) {
+        return {
+            status: "ok",
+            reason: String(response.body["outcome"] ?? "saved"),
+            stdout: "",
+            saved: written,
+            conflicts: conflicted,
+            chars: masked.text.length,
+            masked: masked.masked,
+        };
+    }
     return {
-        status: written > 0 ? "ok" : "empty",
-        reason: written > 0 ? String(response.body["outcome"] ?? "saved") : "nothing_worth_keeping",
+        status: "empty",
+        reason: conflicted > 0 ? "custom_id_conflict" : "nothing_worth_keeping",
         stdout: "",
-        saved: written,
+        saved: 0,
+        conflicts: conflicted,
         chars: masked.text.length,
         masked: masked.masked,
     };

package/dist/server.d.ts

@@ -36,7 +36,7 @@ import { z } from "zod";
 import { type FetchImpl } from "./door.js";
 import type { MemorySession } from "./session.js";
 export declare const PACKAGE_NAME = "@bli-cockpit/memory-mcp";
-export declare const PACKAGE_VERSION = "0.1.1";
+export declare const PACKAGE_VERSION = "0.1.5";
 /**
  * The server id an MCP client registers. Defined in `print-config.ts` and
  * re-exported here: `index.ts` needs the name on the hook and print-config

package/dist/server.js

@@ -37,7 +37,10 @@ import { resolveContainerTag } from "./container-tag.js";
 import { postMemoryDoor } from "./door.js";
 import { SERVER_NAME } from "./print-config.js";
 export const PACKAGE_NAME = "@bli-cockpit/memory-mcp";
-export const PACKAGE_VERSION = "0.1.1";
+// BLI-3713: this constant had drifted from package.json's real version
+// (0.1.1 vs 0.1.4) — nobody had bumped it alongside a version bump before.
+// Kept in lockstep with package.json's "version" field going forward.
+export const PACKAGE_VERSION = "0.1.5";
 /**
  * The server id an MCP client registers. Defined in `print-config.ts` and
  * re-exported here: `index.ts` needs the name on the hook and print-config
@@ -226,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)
@@ -241,7 +250,14 @@ export function createServer(deps) {
         const embedNote = response.body.embedded === false && response.body.embedSkippedReason
             ? ` It was stored without a search vector (${String(response.body.embedSkippedReason)}), so it is findable by keyword and not yet by meaning.`
             : "";
-        return textResult(`Memory ${outcome} in ${landedIn} (id: ${id}).${embedNote}`, response.body);
+        // BLI-3713: `mode: "extract"` can fall back to a verbatim save when
+        // distillation fails (a bad model answer must never mean the content is
+        // dropped) — say so plainly rather than let the caller believe atomic
+        // facts were written when the whole note was stored as one row instead.
+        const extractNote = response.body.extract === "fell_back_verbatim"
+            ? ` Saved as written; extraction failed (${String(response.body.extractFailureReason ?? "unknown")}).`
+            : "";
+        return textResult(`Memory ${outcome} in ${landedIn} (id: ${id}).${embedNote}${extractNote}`, response.body);
     });
     server.registerTool("update_memory", {
         title: "Correct a memory",

package/package.json

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