@bli-cockpit/memory-mcp 0.1.9 → 0.1.11

package/dist/hooks/contract.js

@@ -42,15 +42,49 @@ 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, 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
+     * whole run is capped and the door call is capped inside it (BLI-3730). The
+     * pair before that ticket, 3,000/2,200, was sized 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.
+     * a turn that stalls before the model starts. A recall that misses this
+     * window prints NOTHING and logs `timeout` — the shelf is not worth the
+     * wait, and BLI-3788 is what that cost when nobody counted the misses.
+     *
+     * **2,500/2,000 is measured, not chosen (BLI-3788).** BLI-3730 set
+     * 2,000/1,500 while this door was one queued INSERT; BLI-3777 then put three
+     * Tower legs behind the same call and nothing re-measured the budget. QA
+     * tick 18 found the block printing on 2 of 6 identical runs, every miss at
+     * 1,535-1,543 ms — i.e. the door was losing by tens of milliseconds, not by
+     * seconds. Re-measured against production on 2026-09-05 from an ICT machine
+     * (`npm run memory:hook-bench --workspace=apps/dashboard`):
+     *
+     *     warm, ten runs back to back   printed 10/10   p50 1,072 ms  p95 1,142 ms
+     *     cold, eight runs 90 s apart   printed  5/8    p50 1,470 ms  3 × timeout at 1,535 ms
+     *
+     * A cold call is the one a person actually makes — one prompt every few
+     * minutes, a fresh lambda, an empty cache — and it lands just over the old
+     * line. So the door was made cheaper where that was free (BLI-3788 took the
+     * alias expansion out of the serial preamble and cached it) AND this budget
+     * was widened to what the door costs, both said out loud rather than one of
+     * them quietly buying the other's result.
+     *
+     * **The host ceiling was re-checked, not assumed.** Both installers write
+     * `timeout_seconds: 5` for `UserPromptSubmit` — Claude Code's
+     * `~/.claude/settings.json` and Codex's `~/.codex/hooks.json`, one constant,
+     * `MEMORY_HOOK_TIMEOUT_SECONDS` in the collector's
+     * `memory-install-contract.ts`. A 2,500 ms total leaves 2.5 s of headroom
+     * under both, which is the same margin the 2,000 ms total had against the
+     * older 3,000 ms budget it replaced. Nothing here goes near the ceiling; the
+     * person's patience is still the binding constraint, and 500 ms is what that
+     * patience is being asked for.
+     *
+     * The remaining tail is COUNTED now rather than silent: every run appends a
+     * counts-only line to this machine's hook-stats file (`hook-stats.ts`), the
+     * collector carries `hook_timeouts_24h` on the heartbeat's memory receipt,
+     * and `cockpit ops --memory` prints it. A budget nobody can see missed is a
+     * budget nobody can re-fit.
      */
-    prompt: { totalMs: 2_000, stdinMs: 600, requestMs: 1_500, gitMs: 500 },
+    prompt: { totalMs: 2_500, stdinMs: 600, requestMs: 2_000, 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

package/dist/hooks/hook-stats.d.ts

@@ -0,0 +1,67 @@
+/**
+ * HOW OFTEN DOES A HOOK MISS? — the writing half (BLI-3788).
+ *
+ * A prompt hook that loses its race prints NOTHING. That is the design, and it
+ * is right: a person cannot act on "your recall was 40 ms late" and a
+ * half-injected block is worse than none. The cost of that design is that the
+ * feature can be broken for two thirds of somebody's turns with the only
+ * evidence in a stderr line Claude Code shows nobody (QA tick 18: the block
+ * printed on 2 of 6 identical runs, each miss at ~1,535 ms against a 1,500 ms
+ * budget, and no operator surface counted one).
+ *
+ * So every run adds one to a counts-only file on this machine. The collector
+ * reads it once a sync tick and carries the last 24 hours on the heartbeat's
+ * memory receipt; `cockpit ops --memory` prints it. This module writes; the
+ * SHAPE, the path and the windowing rule live in
+ * `@bli-cockpit/telemetry-core`'s `memory-hook-stats.ts`, because the reader
+ * is a different published package and two copies of a JSON contract kept in
+ * step by comment is the BLI-2541 failure.
+ *
+ * ## Three properties, all defended by tests
+ *
+ * **Nothing here may fail a hook.** Every path catches everything and returns
+ * a reason label. A machine with a read-only home keeps recalling memories and
+ * stops counting, and says which on stderr.
+ *
+ * **It is a FLOOR.** Two hooks finishing in the same millisecond both read,
+ * both add one, and one of them wins the rename — a count can be short and can
+ * never be invented. A lock would be the wrong trade: a filesystem wait in
+ * front of a hook whose whole problem is latency, to protect a number that
+ * only needs to be right to within a few percent.
+ *
+ * **Counts only.** No prompt, no memory, no container tag, no path, no token,
+ * no reason string that did not come from the hook's own closed vocabulary.
+ */
+import { type MemoryHookCounts, type MemoryHookStatsFile } from "@bli-cockpit/telemetry-core";
+import type { HookEvent, HookOutcome } from "./contract.js";
+/** Buckets kept. 48 hours is twice the window anybody reads. */
+export declare const HOOK_STATS_MAX_BUCKETS = 48;
+export declare function hookStatsFilePath(homeDir?: string): string;
+/**
+ * Which column this outcome lands in.
+ *
+ * A deadline is a deadline wherever it fired: the whole-run race in `run.ts`
+ * reports `deadline_exceeded` and the door call inside it reports `timeout`,
+ * and an operator counting "how often did a person lose their recall to the
+ * clock" wants one number, not two words for one event.
+ */
+export declare function columnFor(outcome: HookOutcome): keyof MemoryHookCounts;
+export declare function applyRun(file: MemoryHookStatsFile, event: HookEvent, outcome: HookOutcome, at: Date): MemoryHookStatsFile;
+export interface RecordHookRunOptions {
+    homeDir?: string;
+    now?: Date;
+    /** Test seam. Real runs use the filesystem. */
+    io?: {
+        read: (file: string) => string | null;
+        write: (file: string, contents: string) => void;
+    };
+}
+/**
+ * Count one run. Returns a reason label — `recorded`, or why not — so the
+ * caller can say something rather than swallow it.
+ *
+ * A file that does not parse is REPLACED rather than merged: the alternative
+ * is guessing at somebody else's shape and publishing a number nobody can
+ * explain, and the whole history this protects is 48 hours long.
+ */
+export declare function recordHookRun(event: HookEvent, outcome: HookOutcome, options?: RecordHookRunOptions): string;

package/dist/hooks/hook-stats.js

@@ -0,0 +1,127 @@
+/**
+ * HOW OFTEN DOES A HOOK MISS? — the writing half (BLI-3788).
+ *
+ * A prompt hook that loses its race prints NOTHING. That is the design, and it
+ * is right: a person cannot act on "your recall was 40 ms late" and a
+ * half-injected block is worse than none. The cost of that design is that the
+ * feature can be broken for two thirds of somebody's turns with the only
+ * evidence in a stderr line Claude Code shows nobody (QA tick 18: the block
+ * printed on 2 of 6 identical runs, each miss at ~1,535 ms against a 1,500 ms
+ * budget, and no operator surface counted one).
+ *
+ * So every run adds one to a counts-only file on this machine. The collector
+ * reads it once a sync tick and carries the last 24 hours on the heartbeat's
+ * memory receipt; `cockpit ops --memory` prints it. This module writes; the
+ * SHAPE, the path and the windowing rule live in
+ * `@bli-cockpit/telemetry-core`'s `memory-hook-stats.ts`, because the reader
+ * is a different published package and two copies of a JSON contract kept in
+ * step by comment is the BLI-2541 failure.
+ *
+ * ## Three properties, all defended by tests
+ *
+ * **Nothing here may fail a hook.** Every path catches everything and returns
+ * a reason label. A machine with a read-only home keeps recalling memories and
+ * stops counting, and says which on stderr.
+ *
+ * **It is a FLOOR.** Two hooks finishing in the same millisecond both read,
+ * both add one, and one of them wins the rename — a count can be short and can
+ * never be invented. A lock would be the wrong trade: a filesystem wait in
+ * front of a hook whose whole problem is latency, to protect a number that
+ * only needs to be right to within a few percent.
+ *
+ * **Counts only.** No prompt, no memory, no container tag, no path, no token,
+ * no reason string that did not come from the hook's own closed vocabulary.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { MEMORY_HOOK_STATS_SCHEMA_VERSION, emptyMemoryHookCounts, memoryHookHourBucket, memoryHookStatsFilePath, parseMemoryHookStats, } from "@bli-cockpit/telemetry-core";
+/** Buckets kept. 48 hours is twice the window anybody reads. */
+export const HOOK_STATS_MAX_BUCKETS = 48;
+export function hookStatsFilePath(homeDir = os.homedir()) {
+    return memoryHookStatsFilePath(homeDir);
+}
+function emptyFile() {
+    return { schema_version: MEMORY_HOOK_STATS_SCHEMA_VERSION, buckets: {} };
+}
+/**
+ * Which column this outcome lands in.
+ *
+ * A deadline is a deadline wherever it fired: the whole-run race in `run.ts`
+ * reports `deadline_exceeded` and the door call inside it reports `timeout`,
+ * and an operator counting "how often did a person lose their recall to the
+ * clock" wants one number, not two words for one event.
+ */
+export function columnFor(outcome) {
+    if (outcome.status === "ok")
+        return "printed";
+    if (outcome.status === "empty")
+        return "empty";
+    if (outcome.status === "skipped")
+        return "skipped";
+    const reason = outcome.reason.split(":")[0] ?? "";
+    return reason === "timeout" || reason === "deadline_exceeded" ? "timeouts" : "failed";
+}
+export function applyRun(file, event, outcome, at) {
+    const bucket = memoryHookHourBucket(at);
+    const buckets = { ...file.buckets };
+    const forHour = { ...(buckets[bucket] ?? {}) };
+    const counts = { ...(forHour[event] ?? emptyMemoryHookCounts()) };
+    counts.runs += 1;
+    counts[columnFor(outcome)] += 1;
+    forHour[event] = counts;
+    buckets[bucket] = forHour;
+    // Newest kept, oldest dropped. Lexical order is chronological for this key.
+    const kept = Object.keys(buckets).sort().slice(-HOOK_STATS_MAX_BUCKETS);
+    const pruned = {};
+    for (const key of kept) {
+        const value = buckets[key];
+        if (value)
+            pruned[key] = value;
+    }
+    return { schema_version: MEMORY_HOOK_STATS_SCHEMA_VERSION, buckets: pruned };
+}
+/**
+ * Count one run. Returns a reason label — `recorded`, or why not — so the
+ * caller can say something rather than swallow it.
+ *
+ * A file that does not parse is REPLACED rather than merged: the alternative
+ * is guessing at somebody else's shape and publishing a number nobody can
+ * explain, and the whole history this protects is 48 hours long.
+ */
+export function recordHookRun(event, outcome, options = {}) {
+    const at = options.now ?? new Date();
+    const file = hookStatsFilePath(options.homeDir ?? os.homedir());
+    const io = options.io ?? defaultIo();
+    try {
+        const existing = io.read(file);
+        const parsed = existing === null ? null : parseMemoryHookStats(existing);
+        const current = parsed && parsed.ok ? parsed.file : emptyFile();
+        io.write(file, `${JSON.stringify(applyRun(current, event, outcome, at))}\n`);
+        return "recorded";
+    }
+    catch (error) {
+        const code = error?.code;
+        return `hook_stats_unwritable:${typeof code === "string" ? code : "unknown"}`;
+    }
+}
+function defaultIo() {
+    return {
+        read: (file) => {
+            try {
+                return fs.readFileSync(file, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+        write: (file, contents) => {
+            fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+            // Written whole and renamed into place: a hook killed by its host
+            // mid-write must not leave the collector a truncated file to read.
+            const temporary = `${file}.${process.pid}.tmp`;
+            fs.writeFileSync(temporary, contents, { mode: 0o600 });
+            fs.renameSync(temporary, file);
+        },
+    };
+}

package/dist/hooks/run.d.ts

@@ -58,6 +58,8 @@ export interface RunHookDeps {
     /** Test seams. */
     payload?: HookPayload;
     stopOptions?: StopHookOptions;
+    /** BLI-3788. Counts one run; the default writes this machine's stats file. */
+    recordRun?: (event: HookEvent, outcome: HookOutcome) => string;
 }
 /**
  * Runs one hook and returns its outcome. The caller (`index.ts`) exits 0

package/dist/hooks/run.js

@@ -41,7 +41,8 @@ import path from "node:path";
 import { resolveContainerTag } from "../container-tag.js";
 import { loadMemorySession } from "../session.js";
 import { HOOK_BUDGETS, } from "./contract.js";
-import { buildLogLine, buildSystemMessage, renderSystemMessageBlock } from "./log-line.js";
+import { HOOK_LOG_TAG, buildLogLine, buildSystemMessage, renderSystemMessageBlock } from "./log-line.js";
+import { recordHookRun } from "./hook-stats.js";
 import { readHookPayload } from "./stdin.js";
 export { HOOK_LOG_TAG } from "./log-line.js";
 /**
@@ -71,6 +72,19 @@ export async function runHook(event, deps = {}) {
         }
     }
     stderr.write(buildLogLine(event, outcome, elapsedMs, budget.totalMs));
+    // 5. COUNT IT (BLI-3788). A miss prints nothing by design, so this file is
+    // the only place a person's lost recall is ever recorded; the collector
+    // carries the last 24 hours of it on the heartbeat and `cockpit ops
+    // --memory` prints it. It happens AFTER stdout and the receipt, so a slow
+    // or unwritable disk can delay this process's exit and can never delay,
+    // truncate or change what the person's session was given. A write that did
+    // not happen says so on stderr rather than leaving the count quietly short.
+    const recorded = deps.recordRun
+        ? deps.recordRun(event, outcome)
+        : recordHookRun(event, outcome, deps.now ? { now: new Date(now()) } : {});
+    if (recorded !== "recorded") {
+        stderr.write(`${HOOK_LOG_TAG} ${event} stats not counted ${JSON.stringify({ reason: recorded })}\n`);
+    }
     return outcome;
 }
 async function resolveOutcome(event, deps) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bli-cockpit/memory-mcp",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "private": false,
-  "description": "BLI Memory — an MCP server for the memory layer BLI owns (save, search, update, forget).",
+  "description": "BLI Memory \u2014 an MCP server for the memory layer BLI owns (save, search, update, forget).",
   "type": "module",
   "bin": {
     "bli-memory-mcp": "dist/index.js"
@@ -28,7 +28,7 @@
     "start": "node dist/index.js"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.30",
+    "@bli-cockpit/telemetry-core": "0.1.32",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6"
   },