agent-working-memory 0.15.9 → 0.16.0

package/dist/engine/activation.js

@@ -6,25 +6,42 @@
  * Cognitive retrieval pipeline — phases as shipped (D4 honesty pass 2026-07-30;
  * default-OFF phases are marked, since operators tune from this header):
  *   -1. Coreference expansion (conditional: query contains pronouns)
- *   0. Query expansion (flan-t5-small; caller-gated, MCP default ON)
+ *   0. Query expansion (flan-t5-small; caller-gated. The ENGINE default is OFF and
+ *      AWM_DEFAULT_EXPANSION=1 flips it — but MCP memory_recall defaults
+ *      use_expansion to TRUE, so it DOES run on the path most callers use.
+ *      HTTP /memory/activate and the prime hook pass nothing, so they get OFF.)
  *   1. Vector embedding (bge-small 384d)
  *   2. Parallel retrieval (dual FTS5/BM25 + native vector top-K)
- *   3. Per-candidate scoring (BM25, Jaccard, cosine floor, ACT-R decay,
- *      Hebbian boost, confidence gate — computed together in phase 3b)
- *   3.5 Rocchio pseudo-relevance feedback (conditional on BM25 signal)
- *   3.7 Entity-bridge boost (default ON; AWM_DISABLE_ENTITY_BRIDGE=1)
- *   3.5  Entity-index candidate injection (DEFAULT OFF; AWM_ENTITY_INDEX_FETCH=1 —
- *        D11 2026-07-30: D9 inverted-index lookup of query-named entities; injected
- *        candidates get no boost but a guaranteed rerank audition)
+ *   3a. Candidate fetch — and entity-index candidate injection splices in HERE,
+ *       before any scoring (DEFAULT OFF; AWM_ENTITY_INDEX_FETCH=1 — D11
+ *       2026-07-30: D9 inverted-index lookup of query-named entities; injected
+ *       candidates get no boost but a guaranteed rerank audition)
+ *   3b. Per-candidate scoring (BM25, Jaccard, cosine floor, ACT-R decay,
+ *       Hebbian boost, confidence gate — all computed TOGETHER here, not as
+ *       separate later passes)
+ *   3.5 Rocchio pseudo-relevance feedback (DEFAULT OFF since 2026-10-09;
+ *       AWM_FEEDBACK_BM25=1 — measured at 7% of a recall for nothing, see phase 3.5)
+ *   3.7 Entity-bridge boost (default ON. AWM_DISABLE_ENTITY_BRIDGE disables it —
+ *       the check is for PRESENCE, not value, so =0 disables it too; unset to
+ *       re-enable.)
  *   3.75 Query-conditioned entity bridge (DEFAULT OFF; AWM_QUERY_BRIDGE=1)
- *   4/5 Spreading-activation graph walk (DEFAULT OFF; AWM_SPREAD=1 — parked
- *       after displacing-gold regressions; see design-proposals D11)
+ *   4/5 Graph walk. A plain beam walk over Hebbian + temporal edges is the
+ *       DEFAULT; the iterative SPREADING-activation variant is the opt-in
+ *       (AWM_SPREAD=1 — parked after displacing-gold regressions, see D11)
  *   6. Filter + sort into rerank pool (wide pool since 0.9.0)
- *   7. Cross-encoder rerank (ms-marco; clear-winner skip unless
- *      AWM_DISABLE_RERANK_SKIP=1)
- *   8. Multi-channel OOD detection + agreement gate; supersession penalty;
+ *   7. Cross-encoder rerank (ms-marco; every pooled candidate — the
+ *      0.7.10 clear-winner skip was removed 2026-10-09, see phase 7a)
+ *   8. Multi-channel OOD detection + agreement gate; supersession penalty (8c);
  *      abstention enforced only when caller passes require_confidence
  *   9. Final sort, granularity, confidence attach
+ *   9b. rerank2 second-pass reorder (feedback / edge-strength / class bonuses).
+ *       Engine default OFF (AWM_RERANK2=1), but awm setup, the plugin and the
+ *       Desktop bundle all switch it on, so a normal install HAS it.
+ *
+ *   Phase numbers are the ones used in the code below, so they can be grepped.
+ *   Corrected 2026-10-09: the entity-index injection was listed as a second
+ *   "3.5" (colliding with Rocchio) and placed after 3.7 though it runs inside
+ *   3a; 9b was missing entirely.
  *
  * Logs activation events for eval metrics.
  */
@@ -34,6 +51,7 @@ import { strengthenAssociation, CoActivationBuffer, ValidationGatedBuffer } from
 import { embed, cosineSimilarity } from '../core/embeddings.js';
 import { rerank } from '../core/reranker.js';
 import { expandQuery } from '../core/query-expander.js';
+import { startRecallProfile } from '../core/recall-telemetry.js';
 import { computeRecallConfidence } from './confidence.js';
 import { reorderByReranker, rerank2Enabled, rerank2WindowSize } from '../core/rerank2.js';
 import { buildRerankPassage, rerankTruncation, rerankWindowMode } from '../core/rerank-window.js';
@@ -176,6 +194,7 @@ export class ActivationEngine {
      */
     async activate(query) {
         const startTime = performance.now();
+        const prof = startRecallProfile();
         const limit = query.limit ?? 10;
         const minScore = query.minScore ?? 0.01; // Default: filter out zero-relevance results
         const useReranker = query.useReranker ?? true;
@@ -189,9 +208,11 @@ export class ActivationEngine {
         const requireConfidence = query.requireConfidence ?? 0;
         const adaptive = resolveAdaptiveParams(query);
         // Resolve workspace scope: if workspace is set, search across all agents in that workspace
+        prof.begin('agents');
         const agentIds = query.workspace
             ? await this.store.getWorkspaceAgentIds(query.agentId, query.workspace)
             : [query.agentId];
+        prof.end('agents');
         const isWorkspaceScoped = agentIds.length > 1;
         // ── Phase -2: temporal expression ──
         // Nothing downstream parses dates, so "from last Thursday" was being spent
@@ -214,11 +235,14 @@ export class ActivationEngine {
         }
         const pronounPattern = /\b(she|he|they|her|his|him|their|it|that|this|there)\b/i;
         if (pronounPattern.test(queryContext)) {
+            prof.begin('pronounEntities');
             try {
-                const recentEntities = (await this.store.getEngramsByAgents(agentIds, 'active'))
-                    .sort((a, b) => b.accessCount - a.accessCount)
-                    .slice(0, 10)
-                    .flatMap(e => e.tags.filter(t => t.length >= 3 && !/^(session-|low-|D\d)/.test(t)))
+                // Bounded in SQL. This used to load EVERY active engram to pick five
+                // tag words — 280ms median on 2.1% of real prompts. See
+                // EngramStore.getTopAccessedTags and docs/recall-latency.md.
+                const recentEntities = (await this.store.getTopAccessedTags(agentIds, 10, 'active'))
+                    .flat()
+                    .filter(t => t.length >= 3 && !/^(session-|low-|D\d)/.test(t))
                     .filter((v, i, a) => a.indexOf(v) === i)
                     .slice(0, 5);
                 if (recentEntities.length > 0) {
@@ -227,6 +251,7 @@ export class ActivationEngine {
             }
             catch { /* non-fatal */ }
         }
+        prof.end('pronounEntities');
         // Phase 0: Query expansion — add related terms to improve BM25 recall
         let searchContext = queryContext;
         // Project-dialect aliases. Added to the BM25 SEARCH STRING ONLY — never to
@@ -239,6 +264,7 @@ export class ActivationEngine {
         const aliasAdded = aliasTermsFor(queryContext);
         if (aliasAdded.length > 0)
             searchContext = `${searchContext} ${aliasAdded.join(' ')}`;
+        prof.begin('expansion');
         if (useExpansion) {
             let timer;
             try {
@@ -255,22 +281,27 @@ export class ActivationEngine {
                     clearTimeout(timer);
             }
         }
+        prof.end('expansion');
         // Phase 1: Embed query for vector similarity (uses coref-expanded context)
         let queryEmbedding = null;
+        prof.begin('embed');
         try {
             queryEmbedding = await embed(queryContext);
         }
         catch {
             // Embedding unavailable — fall back to text-only matching
         }
+        prof.end('embed');
         // Phase 2: Parallel retrieval — dual BM25 + all active engrams
         // Two-pass BM25: (1) keyword-stripped query for precision, (2) expanded query for recall.
         // Uses queryContext, not query.context: temporal words must not reach BM25.
+        prof.begin('bm25');
         const keywordQuery = Array.from(tokenize(queryContext)).join(' ');
         const bm25Keyword = keywordQuery.length > 2
             ? await this.store.searchBM25WithRankMultiAgent(agentIds, keywordQuery, limit * 3)
             : [];
         const bm25Expanded = await this.store.searchBM25WithRankMultiAgent(agentIds, searchContext, limit * 3);
+        prof.end('bm25');
         // Merge: take the best BM25 score per engram from either pass
         const bm25ScoreMap = new Map();
         const bm25EngramMap = new Map();
@@ -326,7 +357,9 @@ export class ActivationEngine {
         if (queryEmbedding) {
             for (const aid of agentIds) {
                 try {
+                    prof.begin('vector');
                     const hits = await this.store.searchByVector(aid, queryEmbedding, VECTOR_TOP_K);
+                    prof.end('vector');
                     for (const h of hits) {
                         // pgvector cosine distance: 0 = identical, 2 = opposite.
                         // For unit-norm BGE vectors, distance ≈ 1 - cosineSimilarity.
@@ -401,7 +434,9 @@ export class ActivationEngine {
             }
             if (ents.size > 0) {
                 try {
+                    prof.begin('entityBridge');
                     const entHits = await this.store.searchBM25WithRankMultiAgent(agentIds, Array.from(ents).slice(0, 8).join(' '), ENT_CAP);
+                    prof.end('entityBridge');
                     let added = 0;
                     for (const h of entHits) {
                         if (added >= ENT_CAP)
@@ -424,11 +459,13 @@ export class ActivationEngine {
             }
         }
         // ── D11 (2026-07-30): ENTITY-INDEX CANDIDATE INJECTION (default-OFF, AWM_ENTITY_INDEX_FETCH=1) ──
-        // The D9 inverted index resolves query-NAMED entities ("Seetha", "ticket 18999") to every
+        // The D9 inverted index resolves query-NAMED entities ("Avery", "ticket 10002") to every
         // engram indexed under them — deterministic exact lookup, immune to embedding/BM25 vocabulary
         // mismatch. Injected candidates get NO score boost; instead they are GUARANTEED a rerank
-        // audition (exempt from the topN cut, the minScore pool filter, the rerank-pool slice, and
-        // the rerank-skip heuristic) and the cross-encoder alone decides whether they surface.
+        // audition (exempt from the topN cut, the minScore pool filter and the rerank-pool slice)
+        // and the cross-encoder alone decides whether they surface. The fourth exemption, from the
+        // clear-winner rerank skip, went away with that branch on 2026-10-09 — the reranker is now
+        // unconditional, so an injected candidate is always auditioned.
         // This is the guarded successor to AWM_ENTITY_FETCH above, whose failure mode was measured:
         // injected gold entered the pool but was cut before the reranker ever scored it. Bounded
         // (AWM_ENTITY_INDEX_CAP, default 12) so the audition costs at most one extra rerank batch.
@@ -451,7 +488,9 @@ export class ActivationEngine {
                 for (const term of Array.from(terms).slice(0, 4)) {
                     if (added >= IDX_CAP)
                         break;
+                    prof.begin('entitySearch');
                     const entities = await this.store.searchEntities(term, 6);
+                    prof.end('entitySearch');
                     for (const entity of entities) {
                         if (added >= IDX_CAP)
                             break;
@@ -475,7 +514,9 @@ export class ActivationEngine {
                                     }
                                     continue;
                                 }
+                                prof.begin('entityFetch');
                                 const n = await this.store.getEngram(id);
+                                prof.end('entityFetch');
                                 if (!n || n.stage !== 'active' || n.retracted || n.supersededBy)
                                     continue;
                                 if (query.memoryType && n.memoryType !== query.memoryType)
@@ -505,10 +546,14 @@ export class ActivationEngine {
         // Graph walk still needs full Association objects, but it operates on the
         // top-N (~30 candidates) — its on-demand `getAssociationsFor` lookups are
         // cheap (<5ms total).
+        prof.note('candidates', candidates.length);
+        prof.begin('assocStats');
         const assocStats = await this.store.getAssociationStatsForBatch(candidates.map(e => e.id));
+        prof.end('assocStats');
         // 0.14.4: decay clock is overridable (query.now) so evals against a frozen
         // snapshot are reproducible across days. See ActivationQuery.now.
         const nowMs = query.now ?? Date.now();
+        prof.begin('scoring');
         const scored = candidates.map(engram => {
             const ageDays = (nowMs - engram.createdAt.getTime()) / (1000 * 60 * 60 * 24);
             const stats = assocStats.get(engram.id) ?? { count: 0, sumWeight: 0 };
@@ -607,10 +652,39 @@ export class ActivationEngine {
             // associations: empty in 0.7.12+ — graph walk lazy-fetches per engram on demand
             return { engram, score: composite, phaseScores, associations: [] };
         });
+        prof.end('scoring');
         // Phase 3.5: Rocchio pseudo-relevance feedback — expand query with top result terms
-        // then re-search BM25 to find candidates that keyword search missed
+        // then re-search BM25 to find candidates that keyword search missed.
+        //
+        // DEFAULT OFF since 2026-10-09. `AWM_FEEDBACK_BM25=1` restores it.
+        //
+        // It ran on 100% of queries and cost 6.7-7.0% of every warm recall (35-41ms
+        // mean, plus a getAssociationsFor per newly discovered candidate on 71-79%
+        // of them). What it bought had never been measured. Across three suites and
+        // 950 queries it is (arrow reads ON -> OFF):
+        //
+        //   identifier n=300   s@1 92.7 -> 93.0   s@5 96.7 -> 97.0   silence 90.0 -> 90.0
+        //   topic      n=450   s@1 92.0 -> 92.2   s@5 96.7 -> 96.9   silence 90.0 -> 90.0
+        //   public     n=200   s@1 56.0 -> 56.0   s@5 61.5 -> 61.5   silence  100 ->  100
+        //
+        // Three gold ranks move in 950 queries, and two of the three move in the
+        // wrong direction for the pass — which is the shape you would expect, since
+        // it can only ADD candidates and an added candidate can only displace. The
+        // public corpus is the decisive row: it is the only suite with real recall
+        // headroom (s@5 61.5%), and there the pass is INERT per query, not merely
+        // equal in aggregate — 0 of 200 queries differ in gold rank, top-1 identity
+        // or top-1 score, against an ON-vs-ON determinism check that is also 0.
+        //
+        // Scope that to THIS implementation before concluding anything about the
+        // technique: the expansion terms are the first five novel tokens in DOCUMENT
+        // ORDER (a Set populated by iterating the top-3 contents), not the top five
+        // by weight, and they come mostly from the top-1 result. A weighted term
+        // selection is a different experiment and might well pay.
         const preSorted = scored.sort((a, b) => b.score - a.score);
-        const topForFeedback = preSorted.slice(0, 3).filter(r => r.phaseScores.textMatch > 0.1);
+        const feedbackEnabled = process.env.AWM_FEEDBACK_BM25 === '1';
+        const topForFeedback = feedbackEnabled
+            ? preSorted.slice(0, 3).filter(r => r.phaseScores.textMatch > 0.1)
+            : [];
         if (topForFeedback.length > 0) {
             const feedbackTerms = new Set();
             for (const item of topForFeedback) {
@@ -623,14 +697,18 @@ export class ActivationEngine {
             // Take top 5 feedback terms and re-search
             const extraTerms = Array.from(feedbackTerms).slice(0, 5).join(' ');
             if (extraTerms) {
+                prof.begin('feedbackBM25');
                 const feedbackBM25 = await this.store.searchBM25WithRankMultiAgent(agentIds, `${searchContext} ${extraTerms}`, limit * 2);
+                prof.end('feedbackBM25');
                 for (const r of feedbackBM25) {
                     if (!candidateMap.has(r.engram.id)) {
                         candidateMap.set(r.engram.id, r.engram);
                         // Score the new candidate
                         const engram = r.engram;
                         const ageDays = (nowMs - engram.createdAt.getTime()) / (1000 * 60 * 60 * 24);
+                        prof.begin('feedbackAssoc');
                         const associations = await this.store.getAssociationsFor(engram.id);
+                        prof.end('feedbackAssoc');
                         const cTokens = tokenize(engram.concept);
                         const ctTokens = tokenize(engram.content);
                         const cJac = jaccard(queryTokens, cTokens);
@@ -840,12 +918,14 @@ export class ActivationEngine {
                     topN.push(item);
             }
         }
+        prof.begin('graph');
         if (process.env.AWM_SPREAD === '1' && query.spread !== false) {
             await this.spreadActivation(topN);
         }
         else {
             await this.graphWalk(topN, 2, adaptive.hopPenalty, adaptive.beamWidth);
         }
+        prof.end('graph');
         // Phase 6: Initial filter and sort for re-ranking pool
         // (D11 guard 2/4: injected entity-index candidates are exempt from the minScore floor.)
         const pool = topN
@@ -869,39 +949,51 @@ export class ActivationEngine {
                     rerankPool.push(item);
             }
         }
-        // Reranker skip heuristic (0.7.10+): if BM25 already has a clear winner with
-        // strong absolute score AND a meaningful gap to the runner-up, the cross-encoder
-        // is unlikely to change the top result. Skipping saves ~300ms of wall-clock per
-        // recall on simple queries (40% of post-0.7.9 floor was reranker).
+        // Phase 7a: every candidate in the pool is judged by the cross-encoder.
         //
-        // Conservative gate (only skip when very confident):
-        //   - top-1 textMatch >= 0.8 (high BM25 + jaccard agreement)
-        //   - top-1 score is at least 1.5× top-2 score (clear separation)
-        //   - rerankPool size <= limit*2 (small pool — reranker has less to do)
+        // There used to be a skip here (0.7.10): when the composite already had a
+        // "clean winner" — top-1 textMatch >= 0.8 AND top-1 >= 1.5x top-2 — and the
+        // pool was small, the cross-encoder was skipped to save its ~400ms.
         //
-        // Ambiguous queries (close BM25 scores, weak top-1, large pool) still go through
-        // the reranker. Disable this heuristic via AWM_DISABLE_RERANK_SKIP=1.
-        let rerankSkipped = false;
-        // (D11 guard 4/4: never skip the reranker when entity-index candidates were injected —
-        // the audition IS the rerank; skipping would return them unjudged or drop them.)
-        if (useReranker && rerankPool.length >= 2 && injectedIds.size === 0 && process.env.AWM_DISABLE_RERANK_SKIP !== '1') {
-            const top1 = rerankPool[0];
-            const top2 = rerankPool[1];
-            const t1Text = top1.phaseScores.textMatch;
-            const t1Score = top1.score;
-            const t2Score = top2.score;
-            const cleanWinner = t1Text >= 0.8 && t1Score >= 1.5 * Math.max(t2Score, 0.01);
-            const smallPool = rerankPool.length <= Math.max(limit * 2, 20);
-            if (cleanWinner && smallPool) {
-                rerankSkipped = true;
-            }
-        }
-        if (useReranker && !rerankSkipped && rerankPool.length > 0) {
+        // It is gone, measured 2026-10-09 (`npm run profile:recall` at d7417c4,
+        // which carries `--skip-pool off` for exactly this):
+        //
+        //   - It never fired at any store size this repository benchmarks: 0/300
+        //     identifier, 0/200 public, 0/870 in the earlier profile. Its bound was
+        //     max(limit*2, 20) = 20 against a pool of 24 at the shipped k=3. The
+        //     bound was in step when written — 0.7.13 had cut the pool to
+        //     max(limit*2, 15) — and 0.9.0 widened the pool to max(limit*4, 40) for
+        //     recall without revisiting it.
+        //
+        //   - Forced on, it cost success@1 92.7% -> 91.7%, success@5 96.7% -> 96.3%,
+        //     MRR 94.6% -> 93.9% on the identifier suite, to save at most 13.6ms of a
+        //     528ms recall — under this machine's run-to-run drift. A per-query diff
+        //     moved exactly the 10 queries it fired on: 3 of those 10 lost rank-1 and
+        //     one lost the gold out of the top 5 altogether. Its premise, that the
+        //     cross-encoder rarely changes the top result on a clean winner, does not
+        //     hold on the queries it selected for itself.
+        //
+        //   - Where it DID fire — a store with under ~20 candidates clearing
+        //     minScore, which is to say a new install — it left every pool item at
+        //     rerankerScore = 0, and phase 8 reads that in three places with no idea
+        //     the stage was skipped: the reranker agreement channel dies; `margin` is
+        //     0 so the thin-margin branch ALWAYS fires (x0.4 on every score, which
+        //     drops `floor` in computeRecallConfidence and so depresses confidence on
+        //     exactly the clearest queries); and a caller passing abstentionThreshold
+        //     needs 3 of 3 channels, so it abstains.
+        //
+        // That last hazard outlives the skip on the two paths where the reranker
+        // still does not run: `useReranker: false` (exposed as the MCP
+        // `use_reranker` parameter) and the catch below. Separate defect, needs its
+        // own measurement — AWM task 2026-10-09.
+        prof.note('rerankPool', rerankPool.length);
+        if (useReranker && rerankPool.length > 0) {
             try {
                 // Passage selection for the cross-encoder. Truncation exists for a real
                 // reason: cross-encoders pad to the longest passage in the batch, so one
                 // 5,000-char memory in a 40-item pool drags everything to ~512 tokens and
-                // costs 3-4x — and the reranker is already ~90% of warm recall latency.
+                // costs 3-4x — and the reranker is 83% of warm recall latency (measured,
+                // `npm run profile:recall`; this comment claimed ~90% until it was).
                 //
                 // But a PREFIX is the wrong budget to spend. On the live store, canonical
                 // memories are median 1,965 chars and 98.7% exceed 400, so the reranker
@@ -914,15 +1006,21 @@ export class ActivationEngine {
                 // AWM_RERANK_WINDOW=query spends the SAME budget on the window that
                 // actually contains the query terms. Cost is unchanged. See
                 // src/core/rerank-window.ts.
+                prof.begin('passages');
                 const rrBudget = rerankTruncation();
                 const rrMode = rerankWindowMode();
                 const passages = rerankPool.map(r => buildRerankPassage(r.engram.concept, r.engram.content, queryContext, rrBudget, rrMode, r.engram.tags));
+                prof.end('passages');
+                prof.note('passageChars', passages.reduce((s, p) => s + p.length, 0));
+                prof.note('passageMaxChars', passages.reduce((m, p) => Math.max(m, p.length), 0));
                 let rerankTimer;
+                prof.begin('rerank');
                 const rerankResults = await Promise.race([
                     rerank(queryContext, passages),
                     new Promise((_, reject) => { rerankTimer = setTimeout(() => reject(new Error('reranker timeout')), 10000); }),
                 ]).finally(() => { if (rerankTimer)
                     clearTimeout(rerankTimer); });
+                prof.end('rerank');
                 // Adaptive reranker blend (Codex recommendation):
                 // When BM25/text signals are strong, trust them more; when weak, lean on reranker.
                 const bm25Max = Math.max(...rerankPool.map(r => r.phaseScores.textMatch));
@@ -987,11 +1085,13 @@ export class ActivationEngine {
             // on raw cosine against the mode floor (targeted=0.50, exploratory=0.35).
             const semanticFloor = adaptive.zScoreGate > 0.5 ? 0.50 : 0.35;
             if (channelsAgreeing < requiredChannels && maxRawCosine < semanticFloor) {
+                prof.finish({ results: 0, abstained: 'channels' });
                 return [];
             }
             // Soft penalty: only 1 channel agrees or margin is thin
             if (channelsAgreeing < 2 || margin < 0.05) {
                 if (abstentionThreshold > 0) {
+                    prof.finish({ results: 0, abstained: 'soft' });
                     return [];
                 }
                 for (const item of rerankPool) {
@@ -1009,6 +1109,7 @@ export class ActivationEngine {
             const meanScore = topRerankerScores.reduce((s, v) => s + v, 0) / topRerankerScores.length;
             const variance = topRerankerScores.reduce((s, v) => s + (v - meanScore) ** 2, 0) / topRerankerScores.length;
             if (maxScore < abstentionThreshold || (maxScore < 0.5 && variance < 0.01)) {
+                prof.finish({ results: 0, abstained: 'legacy' });
                 return [];
             }
         }
@@ -1040,6 +1141,7 @@ export class ActivationEngine {
                 confidence,
                 threshold: requireConfidence,
             });
+            prof.finish({ results: 0, abstained: 'confidence' });
             return [];
         }
         // Confidence-adaptive output granularity (Paper 3: cognitive teaming).
@@ -1076,7 +1178,7 @@ export class ActivationEngine {
             // AWM_SNIPPET_WEIGHT=rarity weights a hit by 1/(occurrences of that token
             // in THIS document), so one occurrence of a rare term outweighs many of a
             // common one. Doc-local: no corpus statistics, no extra queries, no
-            // latency. Default OFF preserves the shipped behaviour exactly.
+            // latency. Default OFF preserves the shipped behavior exactly.
             const rarityMode = process.env.AWM_SNIPPET_WEIGHT === 'rarity' || process.env.AWM_SNIPPET_WEIGHT === 'anchor';
             const hits = [];
             const hitW = [];
@@ -1186,8 +1288,11 @@ export class ActivationEngine {
         // Side effects: touch, co-activate, defer Hebbian to validation gate (skip for internal/system calls)
         if (!query.internal) {
             for (const id of activatedIds) {
+                prof.begin('touch');
                 await this.store.touchEngram(id);
+                prof.end('touch');
             }
+            prof.begin('hebbian');
             this.coActivationBuffer.pushBatch(activatedIds);
             // Validation-gated Hebbian: defer strengthening until feedback arrives
             const pairs = this.coActivationBuffer.getCoActivatedPairs(10_000);
@@ -1201,8 +1306,10 @@ export class ActivationEngine {
                 }
             }
             this.validationGate.addPending(activatedIds, uniquePairs);
+            prof.end('hebbian');
             // Log activation event for eval
             const latencyMs = performance.now() - startTime;
+            prof.begin('logEvent');
             const eventId = randomUUID();
             await this.store.logActivationEvent({
                 id: eventId,
@@ -1214,6 +1321,7 @@ export class ActivationEngine {
                 latencyMs,
                 engramIds: activatedIds,
             });
+            prof.end('logEvent');
             // 0.14.3: expose the event id so callers can hand it back on
             // memory_feedback. Before this, the id was generated here and dropped —
             // every one of the 872 retrieval_feedback rows in the live store has
@@ -1224,6 +1332,7 @@ export class ActivationEngine {
                 r.activationEventId = eventId;
             this.lastActivationEventId = eventId;
         }
+        prof.finish({ results: results.length });
         return results;
     }
     /** Id of the most recent non-internal activation this engine logged (0.14.3). */