agent-working-memory 0.15.9 → 0.16.1

package/plugin/README.md

@@ -22,7 +22,7 @@ The launcher defaults `AWM_DB_PATH` to `~/.awm/memory.db` — **the same file
 than quietly starting an empty one. Set `AWM_DB_PATH` yourself to override.
 
 It prefers an installed copy of the package (global, or a local `node_modules`) and falls
-back to `npx -p agent-working-memory@0.15.9`. The npx path rebuilds
+back to `npx -p agent-working-memory@0.16.1`. The npx path rebuilds
 `better-sqlite3` on a cold cache, which is slow enough to look like a hang, so a real
 install is worth having:
 

package/plugin/bin/awm-mcp-launcher.cjs

@@ -6,7 +6,7 @@
 //
 // This is a REAL source file, not a string inside the generator, because it is real code:
 // it gets syntax-checked, linted and tested like everything else. `npm run build:plugin`
-// copies it to plugin/bin/ and substitutes 0.15.9.
+// copies it to plugin/bin/ and substitutes 0.16.1.
 //
 // Two jobs a bare `mcpServers` entry in plugin.json cannot do:
 //
@@ -95,7 +95,7 @@ if (found) {
   const isWin = process.platform === 'win32';
   const child = spawn(
     isWin ? 'npx.cmd' : 'npx',
-    ['-y', '-p', 'agent-working-memory@0.15.9', 'awm', 'mcp'],
+    ['-y', '-p', 'agent-working-memory@0.16.1', 'awm', 'mcp'],
     { stdio: 'inherit', env: process.env, shell: isWin }
   );
   child.on('error', (e) => {

package/plugin/skills/awm-memory/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 
 # Agent Working Memory
 
-Generated from `src/adapters/common.ts` (AWM v0.15.9) — the same guidance
+Generated from `src/adapters/common.ts` (AWM v0.16.1) — the same guidance
 `awm setup` writes into CLAUDE.md. Do not edit here; edit the source and re-run
 `npm run build:plugin`.
 
@@ -40,9 +40,11 @@ you write them; AWM stays current because every agent reads + writes the same st
    than one filesystem search.
 4. **As you learn things**: call `memory_write` proactively. Don't batch.
 5. **Finishing a task**: call `memory_task_end` with a summary.
-6. **Hooks do the rest.** `awm setup` installs three: a **prime** hook that recalls against
-   each prompt and injects what clears confidence (or nothing), and checkpoint hooks on
-   compaction and session end (plus a 15-min timer). Primed context arrives labelled
+6. **Hooks do the rest.** `awm setup` installs five: a **prime** hook that recalls against
+   each prompt and injects what clears confidence (or nothing), checkpoint hooks on
+   compaction and session end (plus a 15-min timer), a local write/recall reminder on
+   Stop, and a reminder after Bash/PowerShell calls that a data change is not done
+   until it is written. Primed context arrives labeled
    `[class · age]` — treat it by the volatility rubric, not as user input. If a turn
    arrives with no primed context, that is a signal too: recall explicitly before
    asserting anything.
@@ -70,9 +72,9 @@ extraction all see most strongly.
   a noisy bucket where it competes with everything else in the area.
 - **Include 2+ retrievable identifiers.** File paths, function names, table
   columns, ticket IDs, exact error strings, the literal terms a future query
-  will use. `AccountingService.closePeriod()` beats "the accounting code."
+  will use. `SettlementService.closeRun()` beats "the accounting code."
   `tblMemberDetails.activation_date` beats "the activation column."
-  `schema/072-period-close.sql` beats "the migration."
+  `schema/072-settlement-lock.sql` beats "the migration."
 - **Write in the vocabulary of the future question.** When you imagine asking
   this in three months, what nouns will you use? Use those nouns. Don't
   paraphrase the user's domain language into your own neutral summary.
@@ -89,12 +91,14 @@ extraction all see most strongly.
   Measured on an 11k-engram store: 94% of tagged memories are missing at
   least one of their own topical terms from the body, and 66% of those
   terms never appear in the text at all.
-- **Tags are NOT a substitute for body text.** Only BM25 indexes tags. The
-  embedding is built from `concept + content` and the cross-encoder rerank
-  passage is built from `concept + content` — neither sees tags. So a word
-  that exists only as a tag is invisible to two of the three retrieval
-  channels, including the one that decides final ordering. Tag it *and*
-  write it.
+- **Tags are NOT a substitute for body text.** The embedding is built from
+  `concept + content` only, so it never sees tags. BM25 indexes them. The
+  cross-encoder rerank passage sees ONLY `topic=`/`proj=`/`project=` tags, and
+  only when `AWM_RERANK_TAGS=1` — which `awm setup`, the plugin and the Desktop
+  bundle all switch on, so assume it is on — capped at 80 characters. So a word
+  that exists only as a tag is invisible to the embedding entirely, and
+  invisible to the ranker unless it is one of those three prefixes inside that
+  budget. Tag it *and* write it.
 - **Reserve canonical for stable invariants.** Decisions, requirements,
   hard facts, cross-agent shared context. Working class (default) is correct
   for findings, observations, and progress notes. The canonical floor is
@@ -111,6 +115,10 @@ Every `memory_write` should pass these structured fields. AWM stores each as a
 prefix-tag like `proj=`, `topic=`, `intent=`, etc. and uses them for BM25
 and entity-bridge boosts at recall time.
 
+(“Required” below means *required for good recall* — the MCP schema accepts every
+one of these as optional, so a write without them succeeds and simply retrieves
+worse.)
+
 | Field | Required? | Format | Example |
 |---|---|---|---|
 | `project` | **YES** | one short word matching the current project | `"EquiHub"`, `"AWM"`, `"USEA-Agent"` |
@@ -120,12 +128,12 @@ and entity-bridge boosts at recall time.
 | `source` | recommended | `code-reading` / `debugging` / `discussion` / `research` / `testing` / `observation` | `"testing"` |
 | `memory_class` | when stable | `canonical` (source-of-truth, 0.7 floor, never staged) / `working` (default) / `ephemeral` | `"canonical"` |
 | `session_id` | recommended | current conversation ID for entity-bridge boost | autogenerated |
-| `tags` | when applicable | extra prefix-tags for IDs and dates | `["ticket=18360", "date=2026-05-11"]` |
+| `tags` | when applicable | extra prefix-tags for IDs and dates | `["ticket=10001", "date=2026-05-11"]` |
 
 **Always add identifier tags when present in the content:**
 - `ticket=<id>` for Freshdesk tickets
 - `member=<id>` for member IDs
-- `horse=<id>` for horse_member_id
+- `asset=<id>` for a domain record id
 - `usef=<id>` for USEF lookups
 - `date=YYYY-MM-DD` for temporal anchoring (ISO format)
 - `person=<Name>` for stakeholder quotes / decisions
@@ -134,7 +142,7 @@ and entity-bridge boosts at recall time.
 ### Entity index — exact-match recall for named things (default off)
 Structured identifier tags (`ticket=`, `person=`, `horse=`, `member=`, bare 4+ digit
 ids, etc.) feed a dedicated entity inverted index, separate from BM25/embedding scoring.
-A query naming an entity ("ticket 19252", "Kaleigh Collett") can reach the memory through
+A query naming an entity ("ticket 10003", "Dana Whitfield") can reach the memory through
 this index even when the wording doesn't lexically match — it's a deterministic exact
 lookup, immune to vocabulary mismatch. Keep identifier tags exact and consistent for
 this reason, not just for the BM25 boost described above.
@@ -334,14 +342,14 @@ memory_write(
 ```
 memory_write(
   concept="EquiHub period-close BLOCKED check missing server-side",
-  content="apps/web/app/(accounting)/accounting/period-close/page.tsx had client-only BLOCKED enforcement. Fixed by adding server-side check in AccountingService.closePeriod() per schema/072-period-close.sql. Without server-side check a malicious request could bypass via direct API call.",
+  content="apps/web/app/(billing)/billing/settlement-lock/page.tsx had client-only BLOCKED enforcement. Fixed by adding server-side check in SettlementService.closeRun() per schema/072-settlement-lock.sql. Without server-side check a malicious request could bypass via direct API call.",
   project="EquiHub",
   topic="accounting",
   intent="finding",
   confidence_level="verified",
   source="debugging",
   memory_class="canonical",
-  tags=["ticket=18360", "person=Robert", "date=2026-05-11", "topic=period-close", "topic=security"]
+  tags=["ticket=10001", "person=Robert", "date=2026-05-11", "topic=period-close", "topic=security"]
 )
 ```
 
@@ -389,7 +397,7 @@ For the comparison table (recall quality parity, BM25 vs `ts_rank_cd`,
 multi-process guarantees), see `docs/pglite-feature-parity.md`.
 
 ### Diagnostics / escape hatches (env vars, only if you know why)
-Each optimisation is gated by an env var so it can be disabled for A/B testing if a
+Each optimization is gated by an env var so it can be disabled for A/B testing if a
 regression appears in your workload. `memory_whoami` prints the active fingerprint.
 
 Retrieval (set ON by `awm setup` since 0.14.6 — the measured-good configuration):
@@ -411,8 +419,13 @@ Recall pipeline:
   no effect on the real-store benchmark, 0.14.5).
 - `AWM_DISABLE_SLIM_CACHE=1` — disables the in-memory slim cache.
   Reverts to per-recall SQL fetch + Buffer→Float32Array conversion.
-- `AWM_DISABLE_RERANK_SKIP=1` — disables the cross-encoder skip on
-  clear-winner queries. Forces every recall through the reranker.
+- `AWM_FEEDBACK_BM25=1` — re-enables Rocchio pseudo-relevance feedback
+  (phase 3.5), a third BM25 pass over the query plus five terms harvested from
+  the top 3 results. Default OFF since 2026-10-09: measured at 6.7–7.0% of every
+  warm recall for no measurable accuracy — 3 gold ranks moved in 950 queries
+  across three suites, two of them the wrong way. On the public corpus — the only
+  suite with recall headroom left — it is inert per query, not just in aggregate:
+  0 of 200 queries differ in rank, top-1 or score.
 - `AWM_DISABLE_EXPANSION_CACHE=1` — disables the query expansion skip
   heuristic + LRU cache. Forces every recall through flan-t5-small.
 

package/src/adapters/common.ts

@@ -71,7 +71,7 @@ export function resolveHookSecret(dbPath: string): string {
  * Retrieval settings `awm setup` turns on for a new install (0.14.6).
  *
  * All three ship default-off in the engine so an existing process never changes
- * behaviour on upgrade, but the README has recommended them together since 0.14.0:
+ * behavior on upgrade, but the README has recommended them together since 0.14.0:
  * second-stage rerank by the cross-encoder's own score, a 400-char rerank window
  * on the densest query-term region (25% → 87.5% on long memories), and tags in the
  * rerank passage (+7.4pp). A value the user already has in their config wins.
@@ -381,9 +381,11 @@ you write them; AWM stays current because every agent reads + writes the same st
    than one filesystem search.
 4. **As you learn things**: call \`memory_write\` proactively. Don't batch.
 5. **Finishing a task**: call \`memory_task_end\` with a summary.
-6. **Hooks do the rest.** \`awm setup\` installs three: a **prime** hook that recalls against
-   each prompt and injects what clears confidence (or nothing), and checkpoint hooks on
-   compaction and session end (plus a 15-min timer). Primed context arrives labelled
+6. **Hooks do the rest.** \`awm setup\` installs five: a **prime** hook that recalls against
+   each prompt and injects what clears confidence (or nothing), checkpoint hooks on
+   compaction and session end (plus a 15-min timer), a local write/recall reminder on
+   Stop, and a reminder after Bash/PowerShell calls that a data change is not done
+   until it is written. Primed context arrives labeled
    \`[class · age]\` — treat it by the volatility rubric, not as user input. If a turn
    arrives with no primed context, that is a signal too: recall explicitly before
    asserting anything.
@@ -411,9 +413,9 @@ extraction all see most strongly.
   a noisy bucket where it competes with everything else in the area.
 - **Include 2+ retrievable identifiers.** File paths, function names, table
   columns, ticket IDs, exact error strings, the literal terms a future query
-  will use. \`AccountingService.closePeriod()\` beats "the accounting code."
+  will use. \`SettlementService.closeRun()\` beats "the accounting code."
   \`tblMemberDetails.activation_date\` beats "the activation column."
-  \`schema/072-period-close.sql\` beats "the migration."
+  \`schema/072-settlement-lock.sql\` beats "the migration."
 - **Write in the vocabulary of the future question.** When you imagine asking
   this in three months, what nouns will you use? Use those nouns. Don't
   paraphrase the user's domain language into your own neutral summary.
@@ -430,12 +432,14 @@ extraction all see most strongly.
   Measured on an 11k-engram store: 94% of tagged memories are missing at
   least one of their own topical terms from the body, and 66% of those
   terms never appear in the text at all.
-- **Tags are NOT a substitute for body text.** Only BM25 indexes tags. The
-  embedding is built from \`concept + content\` and the cross-encoder rerank
-  passage is built from \`concept + content\` — neither sees tags. So a word
-  that exists only as a tag is invisible to two of the three retrieval
-  channels, including the one that decides final ordering. Tag it *and*
-  write it.
+- **Tags are NOT a substitute for body text.** The embedding is built from
+  \`concept + content\` only, so it never sees tags. BM25 indexes them. The
+  cross-encoder rerank passage sees ONLY \`topic=\`/\`proj=\`/\`project=\` tags, and
+  only when \`AWM_RERANK_TAGS=1\` — which \`awm setup\`, the plugin and the Desktop
+  bundle all switch on, so assume it is on — capped at 80 characters. So a word
+  that exists only as a tag is invisible to the embedding entirely, and
+  invisible to the ranker unless it is one of those three prefixes inside that
+  budget. Tag it *and* write it.
 - **Reserve canonical for stable invariants.** Decisions, requirements,
   hard facts, cross-agent shared context. Working class (default) is correct
   for findings, observations, and progress notes. The canonical floor is
@@ -452,6 +456,10 @@ Every \`memory_write\` should pass these structured fields. AWM stores each as a
 prefix-tag like \`proj=\`, \`topic=\`, \`intent=\`, etc. and uses them for BM25
 and entity-bridge boosts at recall time.
 
+(“Required” below means *required for good recall* — the MCP schema accepts every
+one of these as optional, so a write without them succeeds and simply retrieves
+worse.)
+
 | Field | Required? | Format | Example |
 |---|---|---|---|
 | \`project\` | **YES** | one short word matching the current project | \`"EquiHub"\`, \`"AWM"\`, \`"USEA-Agent"\` |
@@ -461,12 +469,12 @@ and entity-bridge boosts at recall time.
 | \`source\` | recommended | \`code-reading\` / \`debugging\` / \`discussion\` / \`research\` / \`testing\` / \`observation\` | \`"testing"\` |
 | \`memory_class\` | when stable | \`canonical\` (source-of-truth, 0.7 floor, never staged) / \`working\` (default) / \`ephemeral\` | \`"canonical"\` |
 | \`session_id\` | recommended | current conversation ID for entity-bridge boost | autogenerated |
-| \`tags\` | when applicable | extra prefix-tags for IDs and dates | \`["ticket=18360", "date=2026-05-11"]\` |
+| \`tags\` | when applicable | extra prefix-tags for IDs and dates | \`["ticket=10001", "date=2026-05-11"]\` |
 
 **Always add identifier tags when present in the content:**
 - \`ticket=<id>\` for Freshdesk tickets
 - \`member=<id>\` for member IDs
-- \`horse=<id>\` for horse_member_id
+- \`asset=<id>\` for a domain record id
 - \`usef=<id>\` for USEF lookups
 - \`date=YYYY-MM-DD\` for temporal anchoring (ISO format)
 - \`person=<Name>\` for stakeholder quotes / decisions
@@ -475,7 +483,7 @@ and entity-bridge boosts at recall time.
 ### Entity index — exact-match recall for named things (default off)
 Structured identifier tags (\`ticket=\`, \`person=\`, \`horse=\`, \`member=\`, bare 4+ digit
 ids, etc.) feed a dedicated entity inverted index, separate from BM25/embedding scoring.
-A query naming an entity ("ticket 19252", "Kaleigh Collett") can reach the memory through
+A query naming an entity ("ticket 10003", "Dana Whitfield") can reach the memory through
 this index even when the wording doesn't lexically match — it's a deterministic exact
 lookup, immune to vocabulary mismatch. Keep identifier tags exact and consistent for
 this reason, not just for the BM25 boost described above.
@@ -675,14 +683,14 @@ memory_write(
 \`\`\`
 memory_write(
   concept="EquiHub period-close BLOCKED check missing server-side",
-  content="apps/web/app/(accounting)/accounting/period-close/page.tsx had client-only BLOCKED enforcement. Fixed by adding server-side check in AccountingService.closePeriod() per schema/072-period-close.sql. Without server-side check a malicious request could bypass via direct API call.",
+  content="apps/web/app/(billing)/billing/settlement-lock/page.tsx had client-only BLOCKED enforcement. Fixed by adding server-side check in SettlementService.closeRun() per schema/072-settlement-lock.sql. Without server-side check a malicious request could bypass via direct API call.",
   project="EquiHub",
   topic="accounting",
   intent="finding",
   confidence_level="verified",
   source="debugging",
   memory_class="canonical",
-  tags=["ticket=18360", "person=Robert", "date=2026-05-11", "topic=period-close", "topic=security"]
+  tags=["ticket=10001", "person=Robert", "date=2026-05-11", "topic=period-close", "topic=security"]
 )
 \`\`\`
 
@@ -730,7 +738,7 @@ For the comparison table (recall quality parity, BM25 vs \`ts_rank_cd\`,
 multi-process guarantees), see \`docs/pglite-feature-parity.md\`.
 
 ### Diagnostics / escape hatches (env vars, only if you know why)
-Each optimisation is gated by an env var so it can be disabled for A/B testing if a
+Each optimization is gated by an env var so it can be disabled for A/B testing if a
 regression appears in your workload. \`memory_whoami\` prints the active fingerprint.
 
 Retrieval (set ON by \`awm setup\` since 0.14.6 — the measured-good configuration):
@@ -752,8 +760,13 @@ Recall pipeline:
   no effect on the real-store benchmark, 0.14.5).
 - \`AWM_DISABLE_SLIM_CACHE=1\` — disables the in-memory slim cache.
   Reverts to per-recall SQL fetch + Buffer→Float32Array conversion.
-- \`AWM_DISABLE_RERANK_SKIP=1\` — disables the cross-encoder skip on
-  clear-winner queries. Forces every recall through the reranker.
+- \`AWM_FEEDBACK_BM25=1\` — re-enables Rocchio pseudo-relevance feedback
+  (phase 3.5), a third BM25 pass over the query plus five terms harvested from
+  the top 3 results. Default OFF since 2026-10-09: measured at 6.7–7.0% of every
+  warm recall for no measurable accuracy — 3 gold ranks moved in 950 queries
+  across three suites, two of them the wrong way. On the public corpus — the only
+  suite with recall headroom left — it is inert per query, not just in aggregate:
+  0 of 200 queries differ in rank, top-1 or score.
 - \`AWM_DISABLE_EXPANSION_CACHE=1\` — disables the query expansion skip
   heuristic + LRU cache. Forces every recall through flan-t5-small.
 

package/src/core/embeddings.ts

@@ -3,7 +3,7 @@
 /**
  * Embedding Engine - vector embeddings via the ML worker pool.
  *
- * Default model: bge-small-en-v1.5 (384 dimensions, ~90MB, MTEB retrieval-optimized).
+ * Default model: bge-small-en-v1.5 (384 dimensions, 133MB ONNX, MTEB retrieval-optimized).
  * Configurable via AWM_EMBED_MODEL env var.
  *
  * AWM 0.8.x: inference dispatches through ml-worker.ts. The worker_threads

package/src/core/entity-extract.ts

@@ -5,7 +5,7 @@
  * Entity extraction for the entity inverted index (D9, 2026-07-30).
  *
  * v1 is deliberately conservative for precision: entities come ONLY from
- * structured sources — prefix tags (`person=Seetha`, `ticket=18999`) and
+ * structured sources — prefix tags (`person=Avery`, `ticket=10002`) and
  * auto-tagger `entity:` tags — never from free-text guessing. Each entity is
  * normalized to `key:value` lowercase so lookups are exact.
  *

package/src/core/query-expander.ts

@@ -3,8 +3,10 @@
 /**
  * Query Expander - rewrites queries with synonyms and related terms.
  *
- * Uses Xenova/flan-t5-small (~80MB ONNX) to expand search queries with
- * related terms that improve BM25 recall.
+ * Uses Xenova/flan-t5-small — a 141MB encoder plus a 233MB merged decoder, so
+ * 374MB of ONNX and a 377MB download with its tokenizer. By far the largest of
+ * the three models AWM fetches. Expands search queries with related terms that
+ * improve BM25 recall.
  *
  * AWM 0.8.x: inference dispatches through ml-worker.ts (currently in-process
  * — worker_threads reverted because onnxruntime-node bindings cross isolate

package/src/core/recall-config.ts

@@ -41,6 +41,10 @@ export const RECALL_FLAGS = [
   'AWM_RERANK_POOL',
   'AWM_RERANK_TAGS',
   'AWM_RERANK_TAGS_LEN',
+  // Cross-encoder precision — changes every reranker score, so it changes order.
+  // Omitted until 2026-10-09, during which both arms of a dtype sweep printed the
+  // SAME arm= label; the whole point of this list is that that cannot happen.
+  'AWM_RERANKER_DTYPE',
   // Derived retrieval text (embedding side)
   'AWM_RETRIEVAL_TEXT',
   // Project-dialect alias expansion
@@ -49,7 +53,8 @@ export const RECALL_FLAGS = [
   // Embedding model — changes every stored vector, so it belongs here
   'AWM_EMBED_MODEL',
   'AWM_EMBED_DIMS',
-  'AWM_DISABLE_RERANK_SKIP',
+  // Rocchio pseudo-relevance feedback (phase 3.5)
+  'AWM_FEEDBACK_BM25',
   // Spreading activation (D11 — parked)
   'AWM_SPREAD',
   'AWM_SPREAD_INJECT',

package/src/core/recall-telemetry.ts

@@ -0,0 +1,131 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Recall-path telemetry — per-stage wall time for one `activate()` call.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The write path has had phase telemetry since D1 (`write-telemetry.ts`), but
+ * the READ path — the hot one, the one every latency claim in the docs is
+ * about — had only a single total. Every attribution of that total was
+ * therefore a reading of the code rather than a measurement, and two comments
+ * in this repository assert "the reranker is ~90% of warm recall latency"
+ * citing nothing but each other. This module exists so that number can be
+ * checked, and so a reviewer can check it too.
+ *
+ * USE
+ * ---
+ *   AWM_PROFILE_RECALL=1                  one stderr line per recall
+ *   AWM_PROFILE_RECALL_OUT=path.jsonl     append one JSON object per recall
+ *
+ * Both unset ⇒ `startRecallProfile()` returns a shared no-op and the only
+ * cost on the hot path is a handful of empty method calls.
+ *
+ * DESIGN
+ * ------
+ * Labels are FLAT and must not overlap: each `begin`/`end` pair measures a
+ * span that no other pair contains. That is what makes `unaccounted`
+ * (total minus the sum of all spans) meaningful — it is the synchronous
+ * JavaScript that no stage claims, and if it is large that is itself the
+ * finding. Repeated labels accumulate, so a per-agent loop can reuse one.
+ *
+ * Additive module: nothing here changes an existing export or code path.
+ *
+ * `node:fs` is imported statically. A lazy `require()` here was silently dead:
+ * this package is ESM, `require` is not defined, and the throw landed in the
+ * catch that exists so profiling can never break a recall — so the first run
+ * produced an empty capture and an honest-looking zero.
+ */
+import { appendFileSync } from 'node:fs';
+
+const STDERR = process.env.AWM_PROFILE_RECALL === '1';
+const OUT = process.env.AWM_PROFILE_RECALL_OUT || '';
+const ON = STDERR || !!OUT;
+
+export interface RecallProfiler {
+  /** Open a span. Nesting a span inside another breaks `unaccounted`. */
+  begin(label: string): void;
+  /** Close the most recent span with this label, accumulating its duration. */
+  end(label: string): void;
+  /** Record a scalar fact about this recall (pool size, counts, flags). */
+  note(key: string, value: number | string | boolean): void;
+  /** Emit the record. Safe to call once; later calls are ignored. */
+  finish(meta?: Record<string, number | string | boolean>): void;
+}
+
+const NOOP: RecallProfiler = {
+  begin() {}, end() {}, note() {}, finish() {},
+};
+
+class Profiler implements RecallProfiler {
+  private readonly t0 = performance.now();
+  private readonly open = new Map<string, number>();
+  private readonly sums = new Map<string, number>();
+  private readonly calls = new Map<string, number>();
+  private readonly notes: Record<string, number | string | boolean> = {};
+  private done = false;
+
+  begin(label: string): void {
+    this.open.set(label, performance.now());
+  }
+
+  end(label: string): void {
+    const started = this.open.get(label);
+    if (started === undefined) return;      // unbalanced end — ignore, never throw
+    this.open.delete(label);
+    const ms = performance.now() - started;
+    this.sums.set(label, (this.sums.get(label) ?? 0) + ms);
+    this.calls.set(label, (this.calls.get(label) ?? 0) + 1);
+  }
+
+  note(key: string, value: number | string | boolean): void {
+    this.notes[key] = value;
+  }
+
+  finish(meta: Record<string, number | string | boolean> = {}): void {
+    if (this.done) return;
+    this.done = true;
+    const totalMs = performance.now() - this.t0;
+
+    const stages: Record<string, number> = {};
+    let accounted = 0;
+    for (const [label, ms] of this.sums) {
+      stages[label] = Math.round(ms * 100) / 100;
+      accounted += ms;
+    }
+
+    const record = {
+      totalMs: Math.round(totalMs * 100) / 100,
+      unaccountedMs: Math.round((totalMs - accounted) * 100) / 100,
+      stages,
+      calls: Object.fromEntries(this.calls),
+      ...this.notes,
+      ...meta,
+    };
+
+    if (OUT) {
+      try {
+        appendFileSync(OUT, JSON.stringify(record) + '\n');
+      } catch { /* profiling must never break a recall */ }
+    }
+
+    if (STDERR) {
+      const top = Object.entries(stages).sort((a, b) => b[1] - a[1]).slice(0, 6)
+        .map(([k, v]) => `${k}=${Math.round(v)}ms`).join(' ');
+      process.stderr.write(
+        `[awm] recall ${Math.round(totalMs)}ms ${top} unaccounted=${Math.round(record.unaccountedMs)}ms\n`,
+      );
+    }
+  }
+}
+
+/** One profiler per `activate()` call, or a shared no-op when disabled. */
+export function startRecallProfile(): RecallProfiler {
+  return ON ? new Profiler() : NOOP;
+}
+
+/** Whether recall profiling is active — for callers that want to skip setup work. */
+export function recallProfileEnabled(): boolean {
+  return ON;
+}