agent-working-memory 0.14.1 → 0.14.6

package/src/adapters/types.ts

@@ -28,8 +28,12 @@ export interface SetupContext {
   hasDist: boolean;
   /** Hook sidecar secret token */
   hookSecret: string;
-  /** Hook sidecar port */
+  /** Hook sidecar port (preferred; the sidecar walks upward from here when busy) */
   hookPort: string;
+  /** How many ports upward from hookPort the sidecar may try (0.14.2) */
+  hookPortRange: string;
+  /** Install the UserPromptSubmit prime hook (0.14.6; `--no-prime` turns it off) */
+  installPrime: boolean;
   /** Whether to use global scope */
   isGlobal: boolean;
   /** Windows platform */
@@ -70,6 +74,13 @@ export interface CLIAdapter {
   /** Configure hooks (if supported). Returns action summary. */
   writeHooks(ctx: SetupContext, skip: boolean): string;
 
-  /** Validate that the setup is healthy. */
-  diagnose(ctx: SetupContext): DiagnosticResult[];
+  /** Validate that the setup is healthy. May probe the network, hence possibly async. */
+  diagnose(ctx: SetupContext): DiagnosticResult[] | Promise<DiagnosticResult[]>;
+
+  /**
+   * The env block of an AWM server entry this adapter previously wrote, if any.
+   * `awm setup` re-runs preserve these values unless a flag overrides them, so an
+   * upgrade never repoints the database or renames the agent (0.14.6).
+   */
+  readExistingEnv?(isGlobal: boolean, cwd: string): Record<string, string> | null;
 }

package/src/cli.ts

@@ -74,7 +74,10 @@ Setup options:
   --no-instructions   Skip instruction file (CLAUDE.md, AGENTS.md, etc.)
   --no-claude-md      Alias for --no-instructions
   --no-hooks          Skip hook installation
-  --hook-port PORT    Sidecar port for hooks (default: 8401)
+  --no-prime          Skip the UserPromptSubmit prime hook (auto-inject memories per prompt)
+  --hook-port PORT    Preferred sidecar port (default: 8401; each session walks upward when busy)
+  --hook-port-range N Ports to try upward from --hook-port (default: 10)
+  Re-running setup keeps your existing agent id, db path, port and any env you added.
 
 Examples:
   awm setup --global              Claude Code, global (recommended)
@@ -95,7 +98,9 @@ async function setup() {
   let skipInstructions = false;
   let isGlobal = false;
   let skipHooks = false;
-  let hookPort = '8401';
+  let installPrime = true;
+  let hookPort: string | undefined;
+  let hookPortRange: string | undefined;
 
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--agent-id' && args[i + 1]) {
@@ -106,8 +111,12 @@ async function setup() {
       skipInstructions = true;
     } else if (args[i] === '--no-hooks') {
       skipHooks = true;
+    } else if (args[i] === '--no-prime') {
+      installPrime = false;
     } else if (args[i] === '--hook-port' && args[i + 1]) {
       hookPort = args[++i];
+    } else if (args[i] === '--hook-port-range' && args[i + 1]) {
+      hookPortRange = args[++i];
     } else if (args[i] === '--global') {
       isGlobal = true;
     } else if (!args[i].startsWith('--')) {
@@ -133,8 +142,10 @@ async function setup() {
     isGlobal = true;
   }
 
-  // Build context
-  const ctx = buildSetupContext({ agentId, dbPath, isGlobal, hookPort });
+  // Build context. A previous install's values survive unless a flag overrides them
+  // (0.14.6) — an upgrade must never repoint the database or rename the agent.
+  const existingEnv = adapter.readExistingEnv?.(isGlobal, process.cwd()) ?? null;
+  const ctx = buildSetupContext({ agentId, dbPath, isGlobal, hookPort, hookPortRange, installPrime, existingEnv });
 
   // Run adapter
   const configAction = adapter.writeMcpConfig(ctx);
@@ -157,6 +168,7 @@ AWM configured for ${adapter.name}${isGlobal ? ' (global)' : ''}
 Next steps:
   1. Restart ${adapter.name} to pick up the MCP server
   2. Memory tools will appear automatically${adapter.id === 'codex' ? ' (verify with /mcp)' : ''}
+  3. \`awm doctor\` checks the install and lists the live sidecars
 `.trim());
 }
 
@@ -197,7 +209,9 @@ async function doctor() {
     }
 
     console.log(`  ${adapter.name}:`);
-    const results = adapter.diagnose(ctx);
+    const existingEnv = adapter.readExistingEnv?.(true, process.cwd()) ?? null;
+    const ctx = buildSetupContext({ isGlobal: true, existingEnv });
+    const results = await adapter.diagnose(ctx);
     for (const r of results) {
       const icon = r.status === 'ok' ? '+' : r.status === 'warn' ? '~' : 'x';
       console.log(`    [${icon}] ${r.check}: ${r.message}`);

package/src/core/agent-id.ts

@@ -0,0 +1,28 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Fallback agent identity when AWM_AGENT_ID / WORKER_NAME are unset.
+ *
+ * Derived from the project directory so a plain `claude` launch still binds to
+ * the right store: `Personal-Projects` → 'personal'; everything else → 'work'.
+ * The AWM package itself lives under Personal-Projects, so an AgentSynapse
+ * checkout is guarded first — a stray server cwd must not mis-bind.
+ *
+ * ONE definition, three consumers that must agree:
+ *   - src/mcp.ts — what the server actually binds to
+ *   - src/adapters/common.ts — what `awm setup` reports and seeds
+ *   - the shipped hook scripts (src/adapters/hook-scripts.ts) carry a
+ *     line-for-line JavaScript mirror, because a hook cannot import from dist.
+ *     tests/adapters/hook-scripts.test.ts asserts the mirror agrees with this.
+ */
+export function deriveAgentFromDir(dir: string): string {
+  const d = String(dir ?? '').replace(/\\/g, '/');
+  if (/\/AgentSynapse\//i.test(d)) return 'work';
+  return /\/Personal-Projects(\/|$)/i.test(d) ? 'personal' : 'work';
+}
+
+/** The agent id a server process would resolve to for `dir`, honouring the env first. */
+export function resolveAgentId(dir: string, env: NodeJS.ProcessEnv = process.env): string {
+  return env.AWM_AGENT_ID ?? env.WORKER_NAME ?? deriveAgentFromDir(dir);
+}

package/src/core/whoami.ts

@@ -59,6 +59,14 @@ export async function buildWhoami(
   store: WhoamiStore,
   agentId: string,
   surface: 'mcp' | 'http',
+  /**
+   * 0.14.2: the port the hook sidecar actually BOUND, from the running handle.
+   * Before this, whoami echoed AWM_HOOK_PORT from the environment — so a session
+   * whose sidecar had lost the port fight and disabled hooks still reported
+   * "hookSidecar=8401". Pass `null` for "tried and failed"; omit (undefined)
+   * for surfaces that have no sidecar, which falls back to the env value.
+   */
+  boundHookPort?: number | null,
 ): Promise<WhoamiInfo> {
   const coordination = process.env.AWM_COORDINATION === 'true' || process.env.AWM_COORDINATION === '1';
   let siblings: string[] = [];
@@ -80,7 +88,9 @@ export async function buildWhoami(
     pid: process.pid,
     ports: {
       http: Number.isFinite(httpPort) && httpPort > 0 ? httpPort : null,
-      hookSidecar: Number.isFinite(hookPort) && hookPort > 0 ? hookPort : null,
+      hookSidecar: boundHookPort !== undefined
+        ? boundHookPort
+        : (Number.isFinite(hookPort) && hookPort > 0 ? hookPort : null),
     },
     recall: { fingerprint: recallConfigFingerprint(), flags: activeRecallConfig() },
     siblingAgents: siblings,

package/src/engine/activation.ts

@@ -502,8 +502,11 @@ export class ActivationEngine {
     // top-N (~30 candidates) — its on-demand `getAssociationsFor` lookups are
     // cheap (<5ms total).
     const assocStats = await this.store.getAssociationStatsForBatch(candidates.map(e => e.id));
+    // 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();
     const scored = candidates.map(engram => {
-      const ageDays = (Date.now() - engram.createdAt.getTime()) / (1000 * 60 * 60 * 24);
+      const ageDays = (nowMs - engram.createdAt.getTime()) / (1000 * 60 * 60 * 24);
       const stats = assocStats.get(engram.id) ?? { count: 0, sumWeight: 0 };
 
       // --- Text relevance (keyword signals) ---
@@ -638,7 +641,7 @@ export class ActivationEngine {
             candidateMap.set(r.engram.id, r.engram);
             // Score the new candidate
             const engram = r.engram;
-            const ageDays = (Date.now() - engram.createdAt.getTime()) / (1000 * 60 * 60 * 24);
+            const ageDays = (nowMs - engram.createdAt.getTime()) / (1000 * 60 * 60 * 24);
             const associations = await this.store.getAssociationsFor(engram.id);
             const cTokens = tokenize(engram.concept);
             const ctTokens = tokenize(engram.content);
@@ -1222,8 +1225,9 @@ export class ActivationEngine {
 
       // Log activation event for eval
       const latencyMs = performance.now() - startTime;
+      const eventId = randomUUID();
       await this.store.logActivationEvent({
-        id: randomUUID(),
+        id: eventId,
         agentId: query.agentId,
         timestamp: new Date(),
         context: query.context,
@@ -1232,11 +1236,22 @@ export class ActivationEngine {
         latencyMs,
         engramIds: activatedIds,
       });
+      // 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
+      // activation_event_id = NULL, so feedback could never be joined to the
+      // recall it judged. Stamped on each result (same value across the set,
+      // like `confidence`) so the MCP layer can render it once in the footer.
+      for (const r of results) r.activationEventId = eventId;
+      this.lastActivationEventId = eventId;
     }
 
     return results;
   }
 
+  /** Id of the most recent non-internal activation this engine logged (0.14.3). */
+  lastActivationEventId: string | null = null;
+
   /**
    * Multi-graph traversal (MAGMA-inspired).
    *

package/src/engine/eval.ts

@@ -75,6 +75,8 @@ export class EvalEngine {
       activationCount: activationStats.count,
       avgPrecisionAtK: precision,
       avgLatencyMs: activationStats.avgLatencyMs,
+      p50LatencyMs: activationStats.p50LatencyMs,
+      p90LatencyMs: activationStats.p90LatencyMs,
       p95LatencyMs: activationStats.p95LatencyMs,
 
       totalEdges: allAssociations.length,
@@ -104,4 +106,36 @@ export class EvalEngine {
         Math.max(activeEngrams.length + retractedEngrams.length, 1),
     };
   }
+
+  /**
+   * 0.14.3: outcome-shaped usage numbers for memory_stats. Each of these can
+   * move in BOTH directions, unlike edge utility. Cheap: one pass over the
+   * agent's engrams plus two count queries.
+   */
+  async computeUsage(agentId: string): Promise<UsageMetrics> {
+    const active = await this.store.getEngramsByAgent(agentId, 'active');
+    const since30 = new Date(Date.now() - 30 * 24 * 3600_000);
+    const writes30d = active.filter(e => e.createdAt >= since30).length;
+    const neverRecalled = active.filter(e => e.accessCount === 0).length;
+    const act30 = await this.store.getActivationStats(agentId, 30 * 24);
+    const fb = await this.store.getLinkedFeedbackStats(agentId, 7 * 24);
+    return {
+      writes30d,
+      recalls30d: act30.count,
+      recallsPerWrite30d: writes30d > 0 ? act30.count / writes30d : 0,
+      neverRecalledShare: active.length > 0 ? neverRecalled / active.length : 0,
+      feedbackLinked7d: fb.total,
+      usefulShare7d: fb.total > 0 ? fb.useful / fb.total : 0,
+    };
+  }
+}
+
+export interface UsageMetrics {
+  writes30d: number;
+  recalls30d: number;
+  recallsPerWrite30d: number;
+  neverRecalledShare: number;
+  /** feedback rows in the window that carry an activation_event_id (0.14.3+) */
+  feedbackLinked7d: number;
+  usefulShare7d: number;
 }

package/src/hooks/prime.ts

@@ -36,7 +36,12 @@ import { packRecallByBudget, estimateTokens, type PackedRecall } from '../core/t
 
 /** Shape returned by the sidecar's `activate` dependency. */
 export interface PrimeCandidate {
-  engram: { id: string; concept: string; content: string; memoryClass?: string; validTo?: string | null };
+  engram: {
+    id: string; concept: string; content: string; memoryClass?: string;
+    validTo?: string | null;
+    /** Used for the age label; Date from the store, string over HTTP. */
+    createdAt?: Date | string | null;
+  };
   score: number;
   summary?: string;
   confidence?: number;
@@ -64,21 +69,31 @@ export interface PrimeResult {
 export const PRIME_DEFAULTS = {
   maxTokens: 600,
   /**
-   * 0.25 = the "balanced" threshold AWM's own recall docs recommend for
-   * acting on a memory. Priming is acting on it without being asked, so it
-   * should not be looser than the value the docs suggest for deliberate use.
+   * 0.10 (was 0.25 until 0.14.6). The confidence this gates on describes the
+   * SHAPE of the score distribution — how far the top results stand out from
+   * the rest — not relevance. Measured 2026-09-11 on a 30k-memory store: at
+   * 0.25 two specific prompts with one clear winner (top score 0.26 and 0.38)
+   * were silenced while a vague prompt passed at 0.92. Those specific prompts
+   * are exactly what priming exists for. 0.10 passed all three and still
+   * abstains on the garbage case (confidence ≈ 0.05).
    */
-  minConfidence: 0.25,
+  minConfidence: 0.10,
   minScore: 0.10,
 } as const;
 
 /** One injected line. Deliberately terser than the MCP recall format — this is
  *  context the agent didn't ask for, so it should read as a brief note, not a
  *  report. The id is retained so the agent can act on it (feedback, supersede). */
-function formatPrimeLine(c: PrimeCandidate): string {
+function formatPrimeLine(c: PrimeCandidate, now: number = Date.now()): string {
   const body = c.summary ?? c.engram.content;
   const validity = c.engram.validTo ? ` [valid until ${c.engram.validTo}]` : '';
-  return `- ${c.engram.concept}${validity} [${c.engram.id}]: ${body}`;
+  // Class + age make the volatility rubric mechanical: a 90-day-old working
+  // memory reads differently from a 2-day-old canonical one, and the agent
+  // should not have to look either up before deciding how much to trust it.
+  const cls = c.engram.memoryClass ?? 'working';
+  const created = c.engram.createdAt ? new Date(c.engram.createdAt as any).getTime() : NaN;
+  const age = Number.isFinite(created) ? ` · ${Math.max(0, Math.round((now - created) / 86_400_000))}d` : '';
+  return `- [${cls}${age}] ${c.engram.concept}${validity} [${c.engram.id}]: ${body}`;
 }
 
 /**

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

@@ -30,6 +30,7 @@
  */
 
 import { readFileSync } from 'node:fs';
+import { deriveAgentFromDir as deriveAgentFromDirShared } from './core/agent-id.js';
 import { resolve, basename } from 'node:path';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 
@@ -111,19 +112,21 @@ const BACKEND: StoreBackend = getConfiguredBackend();
 const DB_PATH = process.env.AWM_DB_PATH ?? (BACKEND === 'pglite' ? 'memory-pglite' : 'memory.db');
 
 // Fallback agent selection when AWM_AGENT_ID/WORKER_NAME are unset: derive from
-// the project directory so plain `claude` launches still bind to the right
-// store. Personal-Projects -> 'personal'; everything else -> 'work' (the
-// primary store). MUST stay in sync with the SessionStart hook
-// (~/.claude/hooks/awm-session-start.ps1) so the hook's restore and the
-// server's reads/writes never diverge. Guard the AWM package's own path
-// (it lives under Personal-Projects) so a stray server cwd can't mis-bind.
-function deriveAgentFromDir(): string {
-  const dir = (process.env.CLAUDE_PROJECT_DIR ?? process.cwd()).replace(/\\/g, '/');
-  if (/\/AgentSynapse\//i.test(dir)) return 'work';
-  return /\/Personal-Projects(\/|$)/i.test(dir) ? 'personal' : 'work';
-}
+// the project directory (core/agent-id.ts — one definition shared with `awm setup`
+// and mirrored in the shipped hook scripts, so the server, the installer and the
+// hooks always name the same pool for a given directory).
+const deriveAgentFromDir = () => deriveAgentFromDirShared(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
 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);
@@ -521,10 +524,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,
       }],
     };
   }
@@ -539,9 +547,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) {
@@ -645,7 +663,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) }] };
   },
 );
@@ -658,6 +676,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}`,
@@ -665,9 +688,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}`,
@@ -675,7 +701,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 {
@@ -1336,6 +1365,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
@@ -1419,7 +1450,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>(