agent-working-memory 0.14.0 → 0.14.5

package/src/hooks/sidecar.ts

@@ -27,7 +27,20 @@ export interface SidecarDeps {
   store: EngramStore;
   agentId: string;
   secret: string | null;
+  /** Preferred port. If busy, the sidecar walks upward (see `portRange`). */
   port: number;
+  /**
+   * 0.14.2: how many consecutive ports to try starting at `port` (default 10).
+   * Every Claude Code session spawns its own MCP process, and each one used to
+   * ask for exactly 8401; on EADDRINUSE the sidecar logged "hooks disabled" and
+   * gave up, so with N concurrent sessions only the first had working hooks —
+   * and `memory_whoami` still reported the configured port as if it were bound.
+   * Observed 2026-09-11: 4 of 5 live sessions had no sidecar at all.
+   * Hook clients probe the same range and match on `/health.agentId`.
+   */
+  portRange?: number;
+  /** Reported by /health so hook clients can prefer the newest build. */
+  version?: string;
   onConsolidate?: (agentId: string, reason: string) => void;
   /**
    * 0.12.2: warm recall for hooks. The sidecar runs in the same process as
@@ -157,8 +170,16 @@ function json(res: ServerResponse, status: number, body: Record<string, unknown>
 
 const AUTO_CHECKPOINT_INTERVAL_MS = 15 * 60_000; // 15 minutes
 
-export function startSidecar(deps: SidecarDeps): { close: () => void } {
+export interface SidecarHandle {
+  close: () => void;
+  /** The port actually bound, or null while binding / if every port in range was busy. */
+  boundPort: () => number | null;
+}
+
+export function startSidecar(deps: SidecarDeps): SidecarHandle {
   const { store, agentId, secret, port, onConsolidate } = deps;
+  const portRange = Math.max(1, deps.portRange ?? 10);
+  let bound: number | null = null;
 
   const server = createServer(async (req, res) => {
     // CORS preflight
@@ -170,7 +191,12 @@ export function startSidecar(deps: SidecarDeps): { close: () => void } {
 
     // Health check — no auth required
     if (req.url === '/health' && req.method === 'GET') {
-      json(res, 200, { status: 'ok', sidecar: true, agentId });
+      // port/pid/version let a hook that probes 8401..841x pick the right
+      // process: same agentId as its session, newest version on a tie.
+      json(res, 200, {
+        status: 'ok', sidecar: true, agentId,
+        port: bound, pid: process.pid, version: deps.version ?? null,
+      });
       return;
     }
 
@@ -340,17 +366,34 @@ export function startSidecar(deps: SidecarDeps): { close: () => void } {
     json(res, 404, { error: 'Not found' });
   });
 
-  server.listen(port, '127.0.0.1', () => {
-    console.error(`AWM hook sidecar listening on 127.0.0.1:${port}`);
+  // Bind to the first free port in [port, port + portRange). A listen error
+  // fires 'error' before 'listening', so we re-listen on the next candidate
+  // from the error handler; any other error, or exhausting the range, leaves
+  // the sidecar unbound (hooks disabled) but never takes the MCP server down.
+  let attempt = 0;
+  const tryListen = () => {
+    const candidate = port + attempt;
+    server.listen(candidate, '127.0.0.1');
+  };
+  server.on('listening', () => {
+    const addr = server.address();
+    bound = addr && typeof addr === 'object' ? addr.port : port + attempt;
+    const note = bound === port ? '' : ` (preferred ${port} was busy)`;
+    console.error(`AWM hook sidecar listening on 127.0.0.1:${bound}${note}`);
   });
-
   server.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EADDRINUSE' && attempt + 1 < portRange) {
+      attempt++;
+      tryListen();
+      return;
+    }
     if (err.code === 'EADDRINUSE') {
-      console.error(`AWM hook sidecar: port ${port} in use, hooks disabled`);
+      console.error(`AWM hook sidecar: ports ${port}-${port + portRange - 1} all in use, hooks disabled`);
     } else {
       console.error('AWM hook sidecar error:', err.message);
     }
   });
+  tryListen();
 
   // --- Silent auto-checkpoint every 15 minutes ---
   const autoCheckpointTimer = setInterval(async () => {
@@ -383,5 +426,6 @@ export function startSidecar(deps: SidecarDeps): { close: () => void } {
       clearInterval(autoCheckpointTimer);
       server.close();
     },
+    boundPort: () => bound,
   };
 }

package/src/mcp.ts

@@ -71,7 +71,7 @@ import { evaluateSalience, computeNovelty, computeNoveltyWithMatch } from './cor
 import { performWrite } from './core/write-pipeline.js';
 import type { ConsciousState } from './types/checkpoint.js';
 import type { SalienceEventType } from './core/salience.js';
-import type { TaskStatus, TaskPriority } from './types/engram.js';
+import type { TaskStatus, TaskPriority, AbstentionInfo } from './types/engram.js';
 import { DEFAULT_AGENT_CONFIG } from './types/agent.js';
 import { embed, getEmbedder } from './core/embeddings.js';
 import { getReranker } from './core/reranker.js';
@@ -124,6 +124,15 @@ function deriveAgentFromDir(): string {
 }
 const AGENT_ID = process.env.AWM_AGENT_ID ?? process.env.WORKER_NAME ?? deriveAgentFromDir();
 const HOOK_PORT = parseInt(process.env.AWM_HOOK_PORT ?? '8401', 10);
+// 0.14.2: ports to try upward from HOOK_PORT when it is busy (see sidecar.ts).
+const HOOK_PORT_RANGE = Math.max(1, parseInt(process.env.AWM_HOOK_PORT_RANGE ?? '10', 10) || 10);
+// Set once the sidecar starts; whoami reads the bound port from it.
+let sidecarHandle: { boundPort: () => number | null } | null = null;
+function sidecarPortLabel(): string {
+  const p = sidecarHandle?.boundPort() ?? null;
+  if (p === null) return `not bound (preferred ${HOOK_PORT}; hooks disabled)`;
+  return p === HOOK_PORT ? `127.0.0.1:${p}` : `127.0.0.1:${p} (preferred ${HOOK_PORT} was busy)`;
+}
 const HOOK_SECRET = process.env.AWM_HOOK_SECRET ?? null;
 
 initLogger(DB_PATH);
@@ -414,7 +423,7 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
     use_expansion: z.boolean().optional().default(true).describe('Expand query with synonyms for better recall (default true)'),
     memory_type: z.enum(['episodic', 'semantic', 'procedural']).optional().describe('Filter by memory type (omit to search all types)'),
     workspace: z.string().optional().describe('Search across all agents in this workspace (hive mode). Omit for agent-scoped recall only.'),
-    require_confidence: z.number().optional().default(0.05).describe('Abstain (return nothing) when recall confidence is below this threshold. Defaults to 0.05 — a LIGHT filter, chosen from measurement: it halves the rate of answering off-topic queries at zero cost to hit rate. Raise it only for push-style use where nobody asked (0.25 is what the prime hook uses). Do NOT raise it for ordinary recall: a miss is expensive, because the agent then reads the codebase instead (~2,106 tokens), so aggressive thresholds measurably destroy value — 0.20+ cut net tokens saved by 25% in tests/abstention-eval. Pass 0 to disable.'),
+    require_confidence: z.number().optional().default(0.05).describe('Abstain (return nothing) when recall confidence is below this threshold. Defaults to 0.05 — a LIGHT filter, chosen from measurement: it halves the rate of answering off-topic queries at zero cost to hit rate. Raise it only for push-style use where nobody asked (0.25 is what the prime hook uses). Do NOT raise it for ordinary recall: a miss is expensive, because the agent then reads the codebase instead (~2,106 tokens), so aggressive thresholds measurably destroy value — 0.20+ cut net tokens saved by 25% in tests/abstention-eval. Pass 0 to disable. NOTE: this is NOT min_score — it gates on the SHAPE of the score distribution across the whole result set, not per-result relevance, so memories that pass min_score can still be withheld. When that happens the reply says RECALL ABSTAINED and reports how many were withheld; an empty result is only absence when it does not.'),
     granularity: z.enum(['full', 'compact', 'auto']).optional().describe('Output granularity (Paper 3: cognitive teaming). "full" (default): no change. "compact": every result carries a short summary field. "auto": confidence-adaptive — top result gets a longer summary when there is a clear winner, otherwise everything is compact for scanning.'),
     max_tokens: z.number().optional().describe('Token budget for the response. `limit` is a COUNT and is token-blind — 5 results may cost 400 tokens or 4,000. Use this when context is tight: results are packed by value-per-token until the budget is reached, the top-scored match always gets first refusal, and the reply reports what it cost and what was withheld. Omit for no budget (everything is returned, still with accounting).'),
   },
@@ -430,6 +439,9 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
     }
     // Use workspace from param, env var, or omit for agent-scoped
     const workspace = params.workspace ?? process.env.AWM_WORKSPACE ?? undefined;
+    // Set only when a gate WITHHELD results. Distinguishes abstention from absence,
+    // which an empty array cannot.
+    let abstained: AbstentionInfo | undefined;
     const results = await activationEngine.activate({
       agentId: AGENT_ID,
       context: queryText,
@@ -442,6 +454,7 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
       workspace,
       requireConfidence: params.require_confidence,
       granularity: params.granularity,
+      onAbstain: (info) => { abstained = info; },
     });
 
     // Auto-checkpoint: track recall
@@ -458,12 +471,29 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
       : '';
 
     if (results.length === 0) {
-      return {
-        content: [{
-          type: 'text' as const,
-          text: 'No relevant memories found.' + peerSuffix,
-        }],
-      };
+      // Two very different conditions used to render identically as
+      // "No relevant memories found." — a claim of absence the system cannot make
+      // when a gate withheld matches. Callers read it as absence and stopped
+      // looking, for memories scoring well above minScore.
+      const text = abstained
+        ? [
+            `RECALL ABSTAINED — this is NOT "no memories exist".`,
+            ``,
+            `${abstained.candidates} candidate${abstained.candidates === 1 ? '' : 's'} matched ` +
+              `(best score ${abstained.topScore.toFixed(3)}) and ${abstained.candidates === 1 ? 'was' : 'were'} ` +
+              `withheld because recall confidence ` +
+              `${abstained.confidence !== undefined ? abstained.confidence.toFixed(3) + ' ' : ''}` +
+              `fell below your require_confidence of ${abstained.threshold ?? '?'}.`,
+            ``,
+            `require_confidence is NOT min_score. It gates on the SHAPE of the score` +
+              ` distribution across the whole result set, not on how relevant any single` +
+              ` memory is — so results that comfortably pass min_score can still be withheld here.`,
+            ``,
+            `To see them: re-run this query with require_confidence: 0.`,
+            `Do not conclude the memories are absent without doing that.`,
+          ].join('\n') + peerSuffix
+        : 'No relevant memories found.' + peerSuffix;
+      return { content: [{ type: 'text' as const, text }] };
     }
 
     // Confidence-adaptive output (Paper 3: cognitive teaming) and D8
@@ -500,10 +530,15 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
       };
     }
 
+    // 0.14.3: surface the activation event id once, so memory_feedback can join
+    // to this recall. Rendered after the token footer; cheap (one short line).
+    const evId = results[0]?.activationEventId;
+    const evFooter = evId ? `\n[recall_id: ${evId}]` : '';
+
     return {
       content: [{
         type: 'text' as const,
-        text: packed.lines.join('\n') + peerSuffix + formatTokenFooter(packed, params.max_tokens),
+        text: packed.lines.join('\n') + peerSuffix + formatTokenFooter(packed, params.max_tokens) + evFooter,
       }],
     };
   }
@@ -518,9 +553,19 @@ Always call this after using a recalled memory so the system learns what's valua
     engram_id: z.string().describe('ID of the memory (from memory_recall results)'),
     useful: z.boolean().describe('Was this memory actually helpful?'),
     context: z.string().optional().describe('Brief note on why it was/wasn\'t useful'),
+    recall_id: z.string().optional().describe(
+      'The [recall_id: …] printed at the end of the memory_recall output that returned this memory. '
+      + 'Pass it so the feedback is joined to that recall; omitted, it defaults to the most recent recall in this session.',
+    ),
   },
   async (params) => {
-    await store.logRetrievalFeedback(null, params.engram_id, params.useful, params.context ?? '');
+    // 0.14.3: join feedback to the recall that produced it. Explicit recall_id
+    // wins; otherwise fall back to the engine's most recent logged activation —
+    // the common case is "recall, use, feedback" in one turn. Before this the
+    // MCP path hardcoded null (the HTTP route already accepted the id), which
+    // is why every retrieval_feedback row in the live store was orphaned.
+    const eventId = params.recall_id ?? activationEngine.lastActivationEventId ?? null;
+    await store.logRetrievalFeedback(eventId, params.engram_id, params.useful, params.context ?? '');
 
     const engram = await store.getEngram(params.engram_id);
     if (engram) {
@@ -624,7 +669,7 @@ server.tool(
   `Identify THIS AWM instance — agent id, mode (standalone/hive), backend, store path, code provenance, ports, and the sibling agent spaces present in the same store. Call when unsure which AWM instance or memory space you are talking to.`,
   {},
   async () => {
-    const info = await buildWhoami(store, AGENT_ID, 'mcp');
+    const info = await buildWhoami(store, AGENT_ID, 'mcp', sidecarHandle ? sidecarHandle.boundPort() : undefined);
     return { content: [{ type: 'text', text: formatWhoami(info) }] };
   },
 );
@@ -637,6 +682,11 @@ Also shows the activity log path so the user can tail it to see what's happening
   async () => {
     const metrics = await evalEngine.computeMetrics(AGENT_ID);
     const checkpoint = await store.getCheckpoint(AGENT_ID);
+    // 0.14.3: outcome numbers, not activity counters. "Edge utility" (share of
+    // edges ever activated) was monotone — it could only rise — and read as
+    // health when it was not. Latency was a mean over a column that mixes cold
+    // loads and stalls (live store: mean 20 s, median 1.6 s); medians only now.
+    const usage = await evalEngine.computeUsage(AGENT_ID);
     const lines = [
       `Agent: ${AGENT_ID}`,
       `Active memories: ${metrics.activeEngramCount}`,
@@ -644,9 +694,12 @@ Also shows the activity log path so the user can tail it to see what's happening
       `Retracted: ${metrics.retractedCount}`,
       `Avg confidence: ${metrics.avgConfidence.toFixed(3)}`,
       `Total edges: ${metrics.totalEdges}`,
-      `Edge utility: ${(metrics.edgeUtilityRate * 100).toFixed(1)}%`,
+      ``,
+      `Write:recall (30d): 1 : ${usage.recallsPerWrite30d.toFixed(2)}  (${usage.writes30d} writes, ${usage.recalls30d} recalls)`,
+      `Never recalled: ${(usage.neverRecalledShare * 100).toFixed(0)}% of active memories`,
+      `Recall→use (7d): ${usage.feedbackLinked7d > 0 ? (usage.usefulShare7d * 100).toFixed(0) + '% useful of ' + usage.feedbackLinked7d + ' judged' : 'no linked feedback yet'}`,
       `Activations (24h): ${metrics.activationCount}`,
-      `Avg latency: ${metrics.avgLatencyMs.toFixed(1)}ms`,
+      `Recall latency (24h): p50 ${metrics.p50LatencyMs.toFixed(0)}ms  p90 ${metrics.p90LatencyMs.toFixed(0)}ms`,
       ``,
       `Session writes: ${checkpoint?.auto.writeCountSinceConsolidation ?? 0}`,
       `Session recalls: ${checkpoint?.auto.recallCountSinceConsolidation ?? 0}`,
@@ -654,7 +707,10 @@ Also shows the activity log path so the user can tail it to see what's happening
       `Checkpoint: ${checkpoint?.executionState ? checkpoint.executionState.currentTask : 'none'}`,
       ``,
       `Activity log: ${getLogPath() ?? 'not configured'}`,
-      `Hook sidecar: 127.0.0.1:${HOOK_PORT}`,
+      // Report the port actually BOUND, not the one configured. Before 0.14.2
+      // this line said 8401 in every session, including the ones whose sidecar
+      // had lost the port and silently disabled hooks.
+      `Hook sidecar: ${sidecarPortLabel()}`,
     ];
 
     return {
@@ -1315,6 +1371,8 @@ async function main() {
     agentId: AGENT_ID,
     secret: HOOK_SECRET,
     port: HOOK_PORT,
+    portRange: HOOK_PORT_RANGE,
+    version: VERSION,
     // 0.12.2: warm recall for hooks — the sidecar shares this process's
     // activation engine and loaded models, so a UserPromptSubmit hook can get
     // warm-latency recall without any standing server. Trimmed result shape
@@ -1398,7 +1456,8 @@ async function main() {
 
   // Log to stderr (stdout is reserved for MCP protocol)
   console.error(`AgentWorkingMemory MCP server started (agent: ${AGENT_ID}, db: ${DB_PATH})`);
-  console.error(`Hook sidecar on 127.0.0.1:${HOOK_PORT}${HOOK_SECRET ? ' (auth enabled)' : ' (no auth — set AWM_HOOK_SECRET)'}`);
+  sidecarHandle = sidecar;
+  console.error(`Hook sidecar preferred 127.0.0.1:${HOOK_PORT} (range ${HOOK_PORT_RANGE})${HOOK_SECRET ? ' (auth enabled)' : ' (no auth — set AWM_HOOK_SECRET)'}`);
 
   // Clean shutdown
   const cleanup = async () => {

package/src/storage/pglite.ts

@@ -1020,7 +1020,7 @@ export class PGliteEngramStore {
     };
   }
 
-  async getActivationStats(agentId: string, windowHours: number = 24): Promise<{ count: number; avgLatencyMs: number; p95LatencyMs: number }> {
+  async getActivationStats(agentId: string, windowHours: number = 24): Promise<{ count: number; avgLatencyMs: number; p50LatencyMs: number; p90LatencyMs: number; p95LatencyMs: number }> {
     await this.readyPromise;
     // Flush any buffered activation events so stats reflect the latest writes.
     await this.flushActivationEvents();
@@ -1031,17 +1031,35 @@ export class PGliteEngramStore {
        ORDER BY latency_ms ASC`,
       [agentId, since],
     );
-    if (result.rows.length === 0) return { count: 0, avgLatencyMs: 0, p95LatencyMs: 0 };
+    if (result.rows.length === 0) return { count: 0, avgLatencyMs: 0, p50LatencyMs: 0, p90LatencyMs: 0, p95LatencyMs: 0 };
     const latencies = result.rows.map((r) => Number(r.latency_ms));
     const total = latencies.reduce((s, l) => s + l, 0);
-    const p95Idx = Math.min(Math.floor(latencies.length * 0.95), latencies.length - 1);
+    // 0.14.3: p50/p90 — see sqlite.ts for why the mean is not usable here.
+    const pct = (q: number) => latencies[Math.min(Math.floor(latencies.length * q), latencies.length - 1)];
     return {
       count: latencies.length,
       avgLatencyMs: total / latencies.length,
-      p95LatencyMs: latencies[p95Idx],
+      p50LatencyMs: pct(0.5),
+      p90LatencyMs: pct(0.9),
+      p95LatencyMs: pct(0.95),
     };
   }
 
+  /** 0.14.3: feedback rows joined to an activation event — see sqlite.ts. */
+  async getLinkedFeedbackStats(agentId: string, windowHours: number = 24 * 7): Promise<{ total: number; useful: number }> {
+    await this.readyPromise;
+    const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
+    const result = await this.db.query<any>(
+      `SELECT COUNT(*) AS total, COUNT(CASE WHEN rf.useful = TRUE THEN 1 END) AS useful
+       FROM retrieval_feedback rf
+       JOIN activation_events ae ON ae.id = rf.activation_event_id
+       WHERE ae.agent_id = $1 AND rf.timestamp > $2`,
+      [agentId, since],
+    );
+    const row = result.rows[0] ?? { total: 0, useful: 0 };
+    return { total: Number(row.total), useful: Number(row.useful) };
+  }
+
   async getConsolidatedCount(agentId: string): Promise<number> {
     await this.readyPromise;
     const result = await this.db.query<any>(

package/src/storage/postgres.ts

@@ -1119,7 +1119,7 @@ export class PostgresEngramStore {
     };
   }
 
-  async getActivationStats(agentId: string, windowHours: number = 24): Promise<{ count: number; avgLatencyMs: number; p95LatencyMs: number }> {
+  async getActivationStats(agentId: string, windowHours: number = 24): Promise<{ count: number; avgLatencyMs: number; p50LatencyMs: number; p90LatencyMs: number; p95LatencyMs: number }> {
     await this.readyPromise;
     // Flush any buffered activation events so stats reflect the latest writes.
     await this.flushActivationEvents();
@@ -1130,17 +1130,35 @@ export class PostgresEngramStore {
        ORDER BY latency_ms ASC`,
       [agentId, since],
     );
-    if (result.rows.length === 0) return { count: 0, avgLatencyMs: 0, p95LatencyMs: 0 };
+    if (result.rows.length === 0) return { count: 0, avgLatencyMs: 0, p50LatencyMs: 0, p90LatencyMs: 0, p95LatencyMs: 0 };
     const latencies = result.rows.map((r) => Number(r.latency_ms));
     const total = latencies.reduce((s, l) => s + l, 0);
-    const p95Idx = Math.min(Math.floor(latencies.length * 0.95), latencies.length - 1);
+    // 0.14.3: p50/p90 — see sqlite.ts for why the mean is not usable here.
+    const pct = (q: number) => latencies[Math.min(Math.floor(latencies.length * q), latencies.length - 1)];
     return {
       count: latencies.length,
       avgLatencyMs: total / latencies.length,
-      p95LatencyMs: latencies[p95Idx],
+      p50LatencyMs: pct(0.5),
+      p90LatencyMs: pct(0.9),
+      p95LatencyMs: pct(0.95),
     };
   }
 
+  /** 0.14.3: feedback rows joined to an activation event — see sqlite.ts. */
+  async getLinkedFeedbackStats(agentId: string, windowHours: number = 24 * 7): Promise<{ total: number; useful: number }> {
+    await this.readyPromise;
+    const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
+    const result = await this.q<any>(
+      `SELECT COUNT(*) AS total, COUNT(CASE WHEN rf.useful = TRUE THEN 1 END) AS useful
+       FROM retrieval_feedback rf
+       JOIN activation_events ae ON ae.id = rf.activation_event_id
+       WHERE ae.agent_id = $1 AND rf.timestamp > $2`,
+      [agentId, since],
+    );
+    const row = result.rows[0] ?? { total: 0, useful: 0 };
+    return { total: Number(row.total), useful: Number(row.useful) };
+  }
+
   async getConsolidatedCount(agentId: string): Promise<number> {
     await this.readyPromise;
     const result = await this.q<any>(

package/src/storage/sqlite.ts

@@ -1348,7 +1348,7 @@ export class EngramStore {
   }
 
   getActivationStats(agentId: string, windowHours: number = 24): {
-    count: number; avgLatencyMs: number; p95LatencyMs: number;
+    count: number; avgLatencyMs: number; p50LatencyMs: number; p90LatencyMs: number; p95LatencyMs: number;
   } {
     const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
     const rows = this.db.prepare(`
@@ -1357,17 +1357,39 @@ export class EngramStore {
       ORDER BY latency_ms ASC
     `).all(agentId, since) as { latency_ms: number }[];
 
-    if (rows.length === 0) return { count: 0, avgLatencyMs: 0, p95LatencyMs: 0 };
+    if (rows.length === 0) return { count: 0, avgLatencyMs: 0, p50LatencyMs: 0, p90LatencyMs: 0, p95LatencyMs: 0 };
 
+    // 0.14.3: p50/p90 added. The column mixes warm recalls with cold model loads
+    // and stalls (live store: mean 20 s, median 1.6 s, max 38 min), so the mean
+    // is not a usable number; percentiles are. Rows are already sorted ASC.
+    const pct = (q: number) => rows[Math.min(Math.floor(rows.length * q), rows.length - 1)].latency_ms;
     const total = rows.reduce((s, r) => s + r.latency_ms, 0);
-    const p95Index = Math.min(Math.floor(rows.length * 0.95), rows.length - 1);
     return {
       count: rows.length,
       avgLatencyMs: total / rows.length,
-      p95LatencyMs: rows[p95Index].latency_ms,
+      p50LatencyMs: pct(0.5),
+      p90LatencyMs: pct(0.9),
+      p95LatencyMs: pct(0.95),
     };
   }
 
+  /**
+   * 0.14.3: feedback rows in the window that are JOINED to an activation event.
+   * Unlinked rows (activation_event_id IS NULL — all 872 rows written before
+   * 0.14.3) are excluded on purpose: this is the recall→use signal, and a row
+   * that cannot be traced to a recall does not measure it.
+   */
+  getLinkedFeedbackStats(agentId: string, windowHours: number = 24 * 7): { total: number; useful: number } {
+    const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
+    const row = this.db.prepare(`
+      SELECT COUNT(*) AS total, COUNT(CASE WHEN rf.useful = 1 THEN 1 END) AS useful
+      FROM retrieval_feedback rf
+      JOIN activation_events ae ON ae.id = rf.activation_event_id
+      WHERE ae.agent_id = ? AND rf.timestamp > ?
+    `).get(agentId, since) as { total: number; useful: number };
+    return { total: row.total, useful: row.useful };
+  }
+
   getConsolidatedCount(agentId: string): number {
     const row = this.db.prepare(
       `SELECT COUNT(*) as cnt FROM engrams WHERE agent_id = ? AND stage = 'consolidated'`

package/src/types/engram.ts

@@ -219,6 +219,13 @@ export interface ActivationResult {
    * See `src/engine/confidence.ts` for the formula.
    */
   confidence?: number;
+  /**
+   * Id of the activation_events row this recall logged (0.14.3). Same value on
+   * every result in the same recall. Hand it back on memory_feedback so the
+   * feedback joins to the recall that produced it — before this, the id was
+   * generated and dropped, and every retrieval_feedback row was orphaned.
+   */
+  activationEventId?: string;
   /**
    * Confidence-adaptive content preview (Paper 3: cognitive teaming).
    * Set when the query opts in via `granularity: 'compact' | 'auto'`.
@@ -254,6 +261,22 @@ export interface PhaseScores {
  */
 export type QueryMode = 'targeted' | 'exploratory' | 'balanced' | 'auto';
 
+/** Why a recall returned nothing, when the cause was a gate rather than an empty store. */
+export interface AbstentionInfo {
+  /** `confidence` = score-distribution gate (`requireConfidence`).
+   *  `agreement`  = cross-channel agreement gate (`abstentionThreshold`). */
+  reason: 'confidence' | 'agreement';
+  /** Candidates that survived scoring and were then withheld. Never 0 — a genuinely
+   *  empty result does not produce an AbstentionInfo at all. */
+  candidates: number;
+  /** Score of the best withheld candidate. Compare against `minScore`, not against
+   *  the confidence threshold — they measure different things. */
+  topScore: number;
+  /** Computed recall confidence, and the threshold it failed. */
+  confidence?: number;
+  threshold?: number;
+}
+
 export interface ActivationQuery {
   agentId: string;
   context: string;
@@ -273,6 +296,15 @@ export interface ActivationQuery {
    * 0.25 (balanced), 0.40 (aggressive — only return high-confidence recall).
    */
   requireConfidence?: number;
+  /**
+   * Called when a gate withholds results, INSTEAD of silently returning [].
+   *
+   * An empty array cannot distinguish "nothing matched" from "matches were found
+   * and withheld", and callers reliably read the second as the first — including
+   * when the withheld results scored well above `minScore`. If you act on an empty
+   * recall, wire this up.
+   */
+  onAbstain?: (info: AbstentionInfo) => void;
   internal?: boolean;          // Skip access count increment, Hebbian update, and event logging (for system calls)
   spread?: boolean;            // R2: when AWM_SPREAD=1, set false to skip iterative spreading activation (connection-discovery uses this so edge-building doesn't recurse)
   memoryType?: MemoryType;     // Filter by memory type (episodic, semantic, procedural)
@@ -285,6 +317,15 @@ export interface ActivationQuery {
    * something different on every run.
    */
   asOf?: number;
+  /**
+   * 0.14.4: clock for ACT-R decay. Defaults to Date.now(). `asOf` pinned the
+   * temporal PARSER but decay still read the wall clock, so a "frozen" eval
+   * snapshot scored differently every day — a 300-query benchmark read 70.0%
+   * s@1 one evening and 67.0% the next afternoon on byte-identical data and
+   * code. Evals must pass the snapshot's own timestamp here. Production leaves
+   * it unset.
+   */
+  now?: number;
   bm25Only?: boolean;          // Skip embedding — fast text-only retrieval for bulk/benchmark scenarios
   /**
    * Output granularity (Paper 3: cognitive teaming, Brill 2018 ACT-R collaboration).

package/src/types/eval.ts

@@ -54,7 +54,9 @@ export interface EvalMetrics {
   // Retrieval quality
   activationCount: number;
   avgPrecisionAtK: number;    // Of returned results, % judged useful
-  avgLatencyMs: number;
+  avgLatencyMs: number;       // kept for callers; misleading on the live store (mixes cold loads) — prefer p50/p90
+  p50LatencyMs: number;       // 0.14.3
+  p90LatencyMs: number;       // 0.14.3
   p95LatencyMs: number;
 
   // Connection quality