agent-working-memory 0.14.5 → 0.15.4

package/src/adapters/common.ts

@@ -14,6 +14,7 @@ import { randomBytes } from 'node:crypto';
 import { homedir as osHomedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import type { SetupContext } from './types.js';
+import { deriveAgentFromDir } from '../core/agent-id.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -47,20 +48,48 @@ export function resolveHookSecret(dbPath: string): string {
   return secret;
 }
 
-/** Build environment variables for the MCP server process. */
+/**
+ * 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:
+ * 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.
+ */
+export const RECOMMENDED_ENV: Readonly<Record<string, string>> = {
+  AWM_RERANK2: '1',
+  AWM_RERANK_WINDOW: 'query',
+  AWM_RERANK_TAGS: '1',
+};
+
+/** Keys `awm setup` owns outright; everything else in an existing env block is the user's. */
+export const OWNED_ENV_KEYS = ['AWM_DB_PATH', 'AWM_AGENT_ID', 'AWM_HOOK_PORT', 'AWM_HOOK_PORT_RANGE', 'AWM_HOOK_SECRET', 'AWM_CLIENT'] as const;
+
+/**
+ * Build environment variables for the MCP server process.
+ *
+ * Layering, lowest to highest: recommended defaults → whatever the user's current
+ * entry already carries (rerank flags they tuned, AWM_WORKSPACE, backend choice…)
+ * → the keys setup owns. Before 0.14.6 the entry was replaced wholesale, which
+ * dropped hand-set flags on every re-run.
+ */
 export function buildEnvVars(
   dbPath: string,
   agentId: string,
   hookPort: string,
   hookSecret: string,
   isWindows: boolean,
+  opts: { hookPortRange?: string; existing?: Record<string, string> | null; client?: string } = {},
 ): Record<string, string> {
-  return {
-    AWM_DB_PATH: isWindows ? dbPath.replace(/\\/g, '/') : dbPath,
+  const owned: Record<string, string> = {
+    AWM_DB_PATH: isWindows ? dbPath.split('\\').join('/') : dbPath,
     AWM_AGENT_ID: agentId,
     AWM_HOOK_PORT: hookPort,
     AWM_HOOK_SECRET: hookSecret,
   };
+  if (opts.hookPortRange && opts.hookPortRange !== '10') owned.AWM_HOOK_PORT_RANGE = opts.hookPortRange;
+  return { ...RECOMMENDED_ENV, ...(opts.existing ?? {}), ...owned };
 }
 
 /**
@@ -92,12 +121,28 @@ export function resolveMcpCommand(ctx: SetupContext): {
   };
 }
 
-/** Build a full SetupContext from parsed CLI flags. */
+/**
+ * Build a full SetupContext from parsed CLI flags.
+ *
+ * Precedence for every owned value: an explicit flag → the value in the entry a
+ * previous `awm setup` wrote (`existingEnv`) → the default. So re-running setup to
+ * pick up new hooks or guidance never repoints the database, renames the agent or
+ * moves the sidecar port underneath a working install.
+ *
+ * Global default agent id is `work` (was `claude` before 0.14.6): it matches what
+ * the server itself resolves to when AWM_AGENT_ID is unset (see core/agent-id.ts),
+ * so a config with and without the key name the same pool.
+ */
 export function buildSetupContext(opts: {
   agentId?: string;
   dbPath?: string | null;
   isGlobal: boolean;
-  hookPort: string;
+  hookPort?: string;
+  hookPortRange?: string;
+  installPrime?: boolean;
+  existingEnv?: Record<string, string> | null;
+  /** Which surface this install is for — stamped onto every write as a `client=` tag. */
+  client?: string;
 }): SetupContext {
   const cwd = process.cwd();
   const projectName = basename(cwd).toLowerCase().replace(/[^a-z0-9-]/g, '-');
@@ -106,11 +151,16 @@ export function buildSetupContext(opts: {
   const mcpDist = join(packageRoot, 'dist', 'mcp.js');
   const hasDist = existsSync(mcpDist);
   const isWindows = process.platform === 'win32';
-
-  const agentId = opts.agentId ?? (opts.isGlobal ? 'claude' : projectName);
-  const dbPath = resolveDbPath(packageRoot, opts.dbPath);
+  const existing = opts.existingEnv ?? null;
+
+  const agentId = opts.agentId
+    ?? existing?.AWM_AGENT_ID
+    ?? (opts.isGlobal ? deriveAgentFromDir('') : projectName);
+  const dbPath = resolveDbPath(packageRoot, opts.dbPath ?? existing?.AWM_DB_PATH ?? null);
+  const hookPort = opts.hookPort ?? existing?.AWM_HOOK_PORT ?? '8401';
+  const hookPortRange = opts.hookPortRange ?? existing?.AWM_HOOK_PORT_RANGE ?? '10';
   const hookSecret = resolveHookSecret(dbPath);
-  const envVars = buildEnvVars(dbPath, agentId, opts.hookPort, hookSecret, isWindows);
+  const envVars = buildEnvVars(dbPath, agentId, hookPort, hookSecret, isWindows, { hookPortRange, existing, client: opts.client });
 
   return {
     cwd,
@@ -122,16 +172,21 @@ export function buildSetupContext(opts: {
     mcpScript,
     hasDist,
     hookSecret,
-    hookPort: opts.hookPort,
+    hookPort,
+    hookPortRange,
+    installPrime: opts.installPrime ?? true,
     isGlobal: opts.isGlobal,
     isWindows,
     envVars,
   };
 }
 
-/** Home directory. */
+/**
+ * Home directory. `AWM_SETUP_HOME` overrides it so `awm setup` / `awm doctor` can be
+ * exercised against a scratch tree (tests do this; so does a cautious upgrade).
+ */
 export function homedir(): string {
-  return osHomedir();
+  return process.env.AWM_SETUP_HOME || osHomedir();
 }
 
 // ─── Instruction content ────────────────────────────────
@@ -282,7 +337,12 @@ 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. **Auto-checkpoint** is handled by hooks (compaction, session-end, 15-min timer). No action needed.
+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
+   \`[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.
 
 ### Write memory when:
 - A project decision is made or changed
@@ -478,10 +538,9 @@ When it isn't:
   return nothing, the memory probably isn't there — read the code instead of
   burning more recalls.
 
-### Recall tuning (0.8.x — opt-in parameters for higher-quality recall)
-Default \`memory_recall\` is tuned for the common case. The 0.8.x recall pipeline
-exposes four opt-in parameters that change the cost/quality tradeoff. Use them
-when the default doesn't match what you actually need.
+### Recall tuning — opt-in parameters
+Default \`memory_recall\` is tuned for the common case. Four opt-in parameters change
+the cost/quality tradeoff. Use them when the default doesn't match what you need.
 
 - **\`granularity: 'compact'\`** — every result carries a 200-char \`summary\`
   field with a query-aware snippet (the densest window of query terms in the
@@ -492,30 +551,37 @@ when the default doesn't match what you actually need.
   winner, it gets a longer summary while the rest are compact. If confidence
   is uniform across results, everything is compact. Use when you don't know
   in advance whether one result will dominate.
-- **\`require_confidence: 0.10 | 0.25 | 0.40\`** — opt-in abstention. AWM
-  returns \`[]\` instead of low-confidence noise. Use when you're about to ACT
-  on the recalled fact (grounding a decision, citing the memory verbatim,
-  contradicting a prior assumption). Thresholds: \`0.10\` strict — only abstain
-  on garbage; \`0.25\` balanced; \`0.40\` aggressive — prefer "I don't know"
-  over "best of bad." When abstention fires (empty result), treat it as a
-  signal — either the memory genuinely isn't there (read the code) or your
-  query missed (reformulate). Don't retry without the threshold.
+- **\`require_confidence\`** — abstention. The default (0.05) is already a light
+  gate: when the top results don't stand out from the rest, recall returns
+  nothing and the reply says **\`RECALL ABSTAINED\`** with the count it withheld.
+  An empty result *without* that line is genuine absence. The gate is on the
+  SHAPE of the score distribution, not relevance — so raising it silences
+  specific questions with one clear winner first (measured: 0.25 abstained on
+  two identifier queries scoring 0.26–0.38 while passing a vague one at 0.92).
+  Leave it alone for ordinary recall; \`0.10\` is the ceiling that still helps for
+  push-style use where nobody asked. When abstention fires, reformulate once
+  with the exact identifier, then read the code — don't retry with a lower
+  threshold to force an answer.
 - **\`workspace: "<name>"\`** — hive-mode recall across all agents in the
   workspace. Use when other agents may have written canonical knowledge you
   need. Default is agent-scoped (your own memories only). Can also be set
-  globally via the \`AWM_WORKSPACE\` env var.
+  globally via the \`AWM_WORKSPACE\` env var. Memories live in the agent pool
+  they were written to; if a session lands in an unexpected pool, \`memory_whoami\`
+  says which one before you conclude the memory is missing.
 
 ### Keep memory fresh
 - After recalling a memory, if you observe the real state is different → call
   \`memory_supersede\` immediately with the corrected version.
-- After using a recalled memory: call \`memory_feedback\` (useful/not-useful) so the
-  activation engine learns what's valuable.
+- After using a recalled memory: call \`memory_feedback\` (useful/not-useful) **with the
+  \`recall_id\`** printed at the end of the recall output (\`[recall_id: …]\`). That id
+  joins the feedback to the recall that produced it, which is what lets AWM learn
+  which recalls were worth their tokens; feedback without it is a bare vote.
 - If you discover a memory is factually wrong: \`memory_retract\` to remove it.
 - **If you bypass AWM (file-memory, in-context notes, "I'll just remember"), the memory
   drifts out of date. The system relies on you to keep it current. This is the #1
   failure mode.**
 
-### Cognition recipes — YOU do the thinking, AWM keeps the result (0.11.x)
+### Cognition recipes — YOU do the thinking, AWM keeps the result
 AWM contains no LLM. When memory needs real thinking — distilling a repeatable
 procedure, reflecting on a failure — AWM hands YOU a versioned recipe (prompt +
 strict output shape) and you run it as a SEPARATE focused pass, then write the
@@ -533,7 +599,7 @@ result back as an ordinary memory with provenance.
 - Re-deriving the same skill name reinforces the existing memory instead of
   duplicating it, so don't fear writing a skill you may have written before.
 
-### Content fade — write-and-forget is safe (0.8.x)
+### Content fade — write-and-forget is safe
 Un-recalled engrams gradually fade their content while preserving cue pathways
 (concept + tags + embedding stay intact). This is Paper 1 — storage
 degradation. Practical implications:
@@ -548,7 +614,7 @@ degradation. Practical implications:
   its fade clock. Frequently-recalled memories stay full-fidelity automatically.
 - **Supersede is the right tool for stale facts.** When you observe a memory
   is outdated, call \`memory_supersede\` — the new version inherits the old
-  one's coherent associations (counter-narrative replacement, 0.8.x) so cue
+  one's coherent associations (counter-narrative replacement) so cue
   pathways carry forward to the replacement.
 
 ### Example — good vs bad memory_write
@@ -600,7 +666,7 @@ comprehension cost. This is output-only: it never changes the data or your memor
 - Don't bother for small outputs — it only compresses when the saving is worthwhile
   and falls back to plain JSON if TOON wouldn't reproduce the data exactly.
 
-### Backend (SQLite vs PGlite, 0.8.x)
+### Backend (SQLite vs PGlite)
 AWM ships two storage backends. The installer picks SQLite by default; both
 are functionally equivalent for cognitive workloads, but differ in operational
 guarantees:
@@ -620,15 +686,26 @@ 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)
-The 0.7.6→0.7.14 work cut recall latency from 11s to ~300ms. The 0.8.x work
-added the write-path rewrite (per-write 300+ ms → under 10ms) and PGlite
-parity tuning. Each optimization is gated by an env-var so it can be disabled
-for A/B testing if a regression appears in your workload:
-
-Recall pipeline (0.7.x):
+Each optimisation 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):
+- \`AWM_RERANK2=1\` — second-stage rerank by the cross-encoder's own score.
+- \`AWM_RERANK_WINDOW=query\` — 400-char rerank window on the densest query-term
+  region instead of the prefix (25% → 87.5% on long memories).
+- \`AWM_RERANK_TAGS=1\` — tags fed into the rerank passage (+7.4pp s@1).
+
+Hook sidecar (0.14.2):
+- \`AWM_HOOK_PORT=8401\` / \`AWM_HOOK_PORT_RANGE=10\` — each MCP process binds the
+  first free port in the range, so several sessions can run at once. The shipped
+  hooks find their own session's sidecar by probing the range and matching
+  \`agentId\` on \`/health\`; \`memory_whoami\` reports the port actually bound.
+
+Recall pipeline:
 - \`AWM_DISABLE_POOL_FILTER=1\` — disables the candidate pool reduction
   pre-filter in recall. Reverts to scoring all active candidates.
-- \`AWM_ENTITY_INDEX_FETCH=1\` — see "Entity index" above (0.12.x, default off).
+- \`AWM_ENTITY_INDEX_FETCH=1\` — see "Entity index" above (default off; measured
+  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
@@ -636,8 +713,8 @@ Recall pipeline (0.7.x):
 - \`AWM_DISABLE_EXPANSION_CACHE=1\` — disables the query expansion skip
   heuristic + LRU cache. Forces every recall through flan-t5-small.
 
-Write pipeline + lifecycle (0.8.x, plus 0.12.x telemetry):
-- \`AWM_SLOW_WRITE_MS=250\` (0.12.x) — any write slower than this logs one stderr
+Write pipeline + lifecycle:
+- \`AWM_SLOW_WRITE_MS=250\` — any write slower than this logs one stderr
   line with a phase-time breakdown (embed/novelty/persist, event-loop lag,
   embed-model cold-load ms). \`0\` disables. Useful for diagnosing why a session's
   first write/recall feels slow.
@@ -653,7 +730,7 @@ Write pipeline + lifecycle (0.8.x, plus 0.12.x telemetry):
 - \`AWM_GRANULARITY_FULL_LEN=1000\` — char budget for the top result in
   \`granularity: 'auto'\` mode when there's a clear winner.
 
-PGlite backend (0.8.x):
+PGlite backend:
 - \`AWM_PGLITE_BM25_M=1\` — multiplier on PGlite \`ts_rank_cd\` to calibrate
   against SQLite FTS5 BM25 distribution. M=1 (default) is passthrough;
   higher M boosts PGlite scores at the cost of recall-ranking precision

package/src/adapters/hook-scripts.ts

@@ -0,0 +1,370 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Claude Code hook scripts shipped by `awm setup` (0.14.6).
+ *
+ * WHY SCRIPTS AND NOT INLINE CURL
+ * -------------------------------
+ * Until 0.14.5 `awm setup` wrote PreCompact/SessionEnd hooks as one-line curl
+ * commands with the sidecar port and the bearer secret baked into
+ * settings.json. Three things broke, each silently:
+ *
+ *   1. The port was fixed (8401, falling back to 8402). Since 0.14.2 every MCP
+ *      process binds the first free port in 8401..8410, so a session that lands
+ *      on 8403 had no hooks at all — and with two pools open, the fallback
+ *      posted a work session's checkpoint into the personal pool's process.
+ *   2. The secret was a literal in settings.json. When the secret file was
+ *      regenerated the hooks got 401s, and `curl -sf` hid them. Observed twice.
+ *   3. There was no prime hook. The only mechanism that injects memory without
+ *      the model choosing to call recall was a documentation page.
+ *
+ * These scripts resolve everything at run time: which agent this session is
+ * (from the MCP config that governs its cwd), which sidecar belongs to that
+ * agent (by probing the port range and reading /health), and the secret (from
+ * the same config, or the secret file next to the database). Nothing here is
+ * baked in at setup time except a fallback record in ~/.claude/hooks/awm-hooks.json.
+ *
+ * Every script fails OPEN: any problem prints nothing and exits 0. A hook that
+ * blocks a prompt or a compaction is worse than no hook.
+ *
+ * The JavaScript bodies deliberately avoid template literals so they can live
+ * inside these TypeScript template strings without escaping.
+ */
+
+/** Bumped when any shipped script changes; written into awm-hooks.json and the
+ *  script headers so `awm doctor` can tell a stale install from a current one. */
+export const AWM_HOOKS_VERSION = '0.14.6';
+
+/** File whose presence turns the prime hook off without uninstalling it. */
+export const PRIME_DISABLE_FILE = 'awm-prime.disabled';
+
+const HEADER = (name: string, purpose: string) => `#!/usr/bin/env node
+// ${name} — installed by \`awm setup\` (hooks v${AWM_HOOKS_VERSION}). ${purpose}
+// Re-running \`awm setup\` rewrites this file; put local changes elsewhere.
+// Fails open: on any problem it prints nothing and exits 0.
+`;
+
+// ─── awm-find-sidecar.cjs ────────────────────────────────────────────────────
+
+export const FIND_SIDECAR_SCRIPT = HEADER(
+  'awm-find-sidecar.cjs',
+  'Shared resolver: which AWM sidecar belongs to THIS session.',
+) + `
+// Since AWM 0.14.2 each MCP process binds the first free port in
+// [AWM_HOOK_PORT, +AWM_HOOK_PORT_RANGE), so "the sidecar is on 8401" is not a
+// safe assumption: with N sessions open there are N sidecars and the one on
+// 8401 may serve a different agent pool. This module (1) works out which agent
+// a session started in \`cwd\` belongs to, from the MCP config that governs that
+// directory, (2) probes the whole range in parallel (local, ~10 ms), and
+// (3) returns the responder whose agentId matches — newest version first, then
+// lowest port. No match → null, and callers fail open.
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+
+const SERVER_NAME = 'agent-working-memory';
+const PROBE_TIMEOUT_MS = 400;
+
+function norm(p) { return String(p || '').replace(/\\\\/g, '/').replace(/\\/+$/, '').toLowerCase(); }
+function readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (e) { return null; } }
+function readText(p) { try { return fs.readFileSync(p, 'utf8').trim(); } catch (e) { return ''; } }
+
+// MIRROR of deriveAgentFromDir() in src/core/agent-id.ts — the server's own
+// fallback when AWM_AGENT_ID is unset. Kept in sync by tests/adapters/hook-scripts.test.ts.
+function deriveAgentFromDir(dir) {
+  const d = String(dir || '').replace(/\\\\/g, '/');
+  if (/\\/AgentSynapse\\//i.test(d)) return 'work';
+  return /\\/Personal-Projects(\\/|$)/i.test(d) ? 'personal' : 'work';
+}
+
+// The AWM entry inside one MCP config file, if any. ~/.claude.json keeps
+// project-scoped servers under projects[<path>].mcpServers.
+function awmEntry(json, cwd) {
+  if (!json) return null;
+  if (json.mcpServers && json.mcpServers[SERVER_NAME]) return json.mcpServers[SERVER_NAME];
+  if (json.projects && cwd) {
+    for (const k of Object.keys(json.projects)) {
+      if (norm(k) !== norm(cwd)) continue;
+      const s = json.projects[k] && json.projects[k].mcpServers;
+      if (s && s[SERVER_NAME]) return s[SERVER_NAME];
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the configuration that governs a session started in \`cwd\`:
+ * { agentId, secret, port, range, dbPath, source }.
+ *
+ * Order: the nearest .mcp.json / .claude/mcp.json walking up from cwd, then
+ * ~/.mcp.json, then ~/.claude.json, then the record \`awm setup\` left in
+ * ~/.claude/hooks/awm-hooks.json. Process env always wins for a given key.
+ */
+function resolveConfig(cwd) {
+  cwd = cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const home = os.homedir();
+  const candidates = [];
+  let dir = path.resolve(cwd);
+  for (let i = 0; i < 16; i++) {
+    candidates.push(path.join(dir, '.mcp.json'), path.join(dir, '.claude', 'mcp.json'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  candidates.push(path.join(home, '.mcp.json'), path.join(home, '.claude.json'));
+
+  let entry = null, source = null;
+  for (const c of candidates) {
+    const e = awmEntry(readJson(c), cwd);
+    if (e) { entry = e; source = c; break; }
+  }
+  const env = (entry && entry.env) || {};
+  const fallback = readJson(path.join(home, '.claude', 'hooks', 'awm-hooks.json')) || {};
+
+  const agentId = process.env.AWM_AGENT_ID || env.AWM_AGENT_ID
+    || (entry ? deriveAgentFromDir(cwd) : (fallback.agentId || deriveAgentFromDir(cwd)));
+  const dbPath = env.AWM_DB_PATH || fallback.dbPath || null;
+  let secret = process.env.AWM_HOOK_SECRET || env.AWM_HOOK_SECRET || '';
+  if (!secret && dbPath) secret = readText(path.join(path.dirname(dbPath), '.awm-hook-secret'));
+  if (!secret && fallback.secretPath) secret = readText(fallback.secretPath);
+  const port = parseInt(process.env.AWM_HOOK_PORT || env.AWM_HOOK_PORT || fallback.hookPort || '8401', 10) || 8401;
+  const range = Math.max(1, parseInt(process.env.AWM_HOOK_PORT_RANGE || env.AWM_HOOK_PORT_RANGE || fallback.hookPortRange || '10', 10) || 10);
+  return { agentId: agentId, secret: secret, port: port, range: range, dbPath: dbPath, source: source };
+}
+
+function probe(port) {
+  return new Promise(function (resolve) {
+    const req = http.get({ host: '127.0.0.1', port: port, path: '/health', timeout: PROBE_TIMEOUT_MS }, function (res) {
+      let data = '';
+      res.on('data', function (c) { data += c; });
+      res.on('end', function () {
+        try {
+          const j = JSON.parse(data);
+          resolve(j && j.sidecar ? { port: port, agentId: j.agentId || null, version: j.version || '0.0.0', pid: j.pid || null } : null);
+        } catch (e) { resolve(null); }
+      });
+    });
+    req.on('error', function () { resolve(null); });
+    req.on('timeout', function () { req.destroy(); resolve(null); });
+  });
+}
+
+function versionKey(v) { return String(v || '0').split('.').map(function (n) { return parseInt(n, 10) || 0; }); }
+function newer(a, b) {
+  const ka = versionKey(a), kb = versionKey(b);
+  for (let i = 0; i < Math.max(ka.length, kb.length); i++) {
+    const d = (ka[i] || 0) - (kb[i] || 0);
+    if (d) return d > 0;
+  }
+  return false;
+}
+
+/** Every live sidecar in the configured range, regardless of agent. */
+async function listSidecars(cfg) {
+  const ports = [];
+  for (let i = 0; i < cfg.range; i++) ports.push(cfg.port + i);
+  return (await Promise.all(ports.map(probe))).filter(Boolean);
+}
+
+/**
+ * The sidecar for this session, or null. Resolves to
+ * { sidecar: {port, agentId, version, pid} | null, config, all: [...] }.
+ */
+async function findSidecar(cwd) {
+  const cfg = resolveConfig(cwd);
+  const all = await listSidecars(cfg);
+  const mine = all.filter(function (s) { return s.agentId === cfg.agentId; });
+  mine.sort(function (a, b) { return newer(a.version, b.version) ? -1 : newer(b.version, a.version) ? 1 : a.port - b.port; });
+  return { sidecar: mine[0] || null, config: cfg, all: all };
+}
+
+/** Optional trace for troubleshooting: AWM_HOOK_DEBUG=1 appends to ~/.claude/hooks/awm-hooks.log. */
+function debugLog(hook, fields) {
+  if (!process.env.AWM_HOOK_DEBUG) return;
+  try {
+    const line = Object.assign({ ts: new Date().toISOString(), hook: hook }, fields);
+    fs.appendFileSync(path.join(os.homedir(), '.claude', 'hooks', 'awm-hooks.log'), JSON.stringify(line) + '\\n');
+  } catch (e) { /* never matters */ }
+}
+
+module.exports = { resolveConfig, findSidecar, listSidecars, deriveAgentFromDir, debugLog, PROBE_TIMEOUT_MS };
+`;
+
+// ─── awm-checkpoint.cjs ──────────────────────────────────────────────────────
+
+export const CHECKPOINT_HOOK_SCRIPT = HEADER(
+  'awm-checkpoint.cjs',
+  'PreCompact / SessionEnd: checkpoint this session into ITS agent\'s AWM.',
+) + `
+// Forwards the whole hook payload (hook_event_name, transcript_path, cwd,
+// session_id) to POST /hooks/checkpoint on the sidecar that belongs to this
+// session's agent. transcript_path matters: the sidecar parses it for the
+// current task and active files, so the checkpoint is a real one, not a stub.
+'use strict';
+const http = require('http');
+
+let finder = null;
+try { finder = require('./awm-find-sidecar.cjs'); } catch (e) { process.exit(0); }
+
+const TIMEOUT_MS = 5000;
+
+let raw = '';
+process.stdin.on('data', function (d) { raw += d; });
+process.stdin.on('end', function () {
+  let payload = {};
+  try { payload = JSON.parse(raw || '{}'); } catch (e) { payload = {}; }
+  if (!payload.hook_event_name) payload.hook_event_name = 'PreCompact';
+  main(payload).catch(function () { process.exit(0); });
+});
+// A hook with nothing on stdin must still exit.
+process.stdin.on('error', function () { process.exit(0); });
+
+async function main(payload) {
+  const found = await finder.findSidecar(payload.cwd);
+  const sc = found.sidecar;
+  if (!sc) {
+    finder.debugLog('checkpoint', { event: payload.hook_event_name, agent: found.config.agentId, sidecar: null, live: found.all.length });
+    process.exit(0);
+  }
+  const body = JSON.stringify(payload);
+  const req = http.request({
+    host: '127.0.0.1', port: sc.port, path: '/hooks/checkpoint', method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+      'Authorization': 'Bearer ' + found.config.secret,
+    },
+    timeout: TIMEOUT_MS,
+  }, function (res) {
+    res.resume();
+    res.on('end', function () {
+      finder.debugLog('checkpoint', { event: payload.hook_event_name, agent: found.config.agentId, port: sc.port, status: res.statusCode });
+      process.exit(0);
+    });
+  });
+  req.on('error', function () { process.exit(0); });
+  req.on('timeout', function () { req.destroy(); process.exit(0); });
+  req.end(body);
+}
+`;
+
+// ─── awm-prime.cjs ───────────────────────────────────────────────────────────
+
+export const PRIME_HOOK_SCRIPT = HEADER(
+  'awm-prime.cjs',
+  'UserPromptSubmit: prime the turn with relevant memories, or stay silent.',
+) + `
+// The PRIME phase of the AWM-native harness (docs/patterns/awm-native-harness.md).
+// Posts the prompt to POST /hooks/prime on this session's sidecar and injects the
+// returned text as additionalContext. The sidecar decides what to inject, formats
+// it, abstains when confidence is low and caps the token budget — see
+// src/hooks/prime.ts — so this file stays thin.
+//
+// Turn it off without uninstalling: create ~/.claude/hooks/${PRIME_DISABLE_FILE}
+// (an empty file). Remove the file to turn it back on. \`awm doctor\` reports which.
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+
+let finder = null;
+try { finder = require('./awm-find-sidecar.cjs'); } catch (e) { process.exit(0); }
+
+// A slow AWM must never delay a prompt. Warm recall with rerank measures 1.4–1.8 s
+// on a 30k-memory store; 4 s leaves margin. Connection refused returns in ~100 ms.
+const TIMEOUT_MS = 4000;
+const MIN_PROMPT_LEN = 15;   // skip "yes" / "ok" / "go on" turns
+// Set-level confidence below which the sidecar injects nothing. 0.10 rather than
+// the 0.25 once documented as "balanced": measured 2026-09-11, 0.25 silenced
+// specific prompts with one clear winner (top score 0.26–0.38) while passing a
+// vague one at 0.92. The gate is on the shape of the score distribution, not on
+// relevance, so specific questions are exactly the ones a high threshold loses.
+const MIN_CONFIDENCE = 0.10;
+const DISABLE_FILE = path.join(os.homedir(), '.claude', 'hooks', '${PRIME_DISABLE_FILE}');
+
+let raw = '';
+process.stdin.on('data', function (d) { raw += d; });
+process.stdin.on('end', function () {
+  let payload = {};
+  try { payload = JSON.parse(raw || '{}'); } catch (e) { process.exit(0); }
+  main(payload).catch(function () { process.exit(0); });
+});
+process.stdin.on('error', function () { process.exit(0); });
+
+function extractPrompt(j) {
+  for (const key of ['prompt', 'message', 'user_prompt', 'text', 'input']) {
+    if (typeof j[key] === 'string' && j[key].trim()) return j[key];
+  }
+  return null;
+}
+
+async function main(payload) {
+  if (fs.existsSync(DISABLE_FILE)) process.exit(0);
+  const prompt = extractPrompt(payload);
+  if (!prompt || prompt.trim().length < MIN_PROMPT_LEN) process.exit(0);
+
+  const found = await finder.findSidecar(payload.cwd);
+  const sc = found.sidecar;
+  if (!sc) {
+    finder.debugLog('prime', { agent: found.config.agentId, sidecar: null, live: found.all.length });
+    process.exit(0);
+  }
+
+  const body = JSON.stringify({
+    hook_event_name: 'UserPromptSubmit',
+    session_id: payload.session_id,
+    cwd: payload.cwd,
+    prompt: prompt,
+    minConfidence: MIN_CONFIDENCE,
+  });
+  const req = http.request({
+    host: '127.0.0.1', port: sc.port, path: '/hooks/prime', method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+      'Authorization': 'Bearer ' + found.config.secret,
+    },
+    timeout: TIMEOUT_MS,
+  }, function (res) {
+    let data = '';
+    res.on('data', function (c) { data += c; });
+    res.on('end', function () {
+      let out = null;
+      try { out = JSON.parse(data); } catch (e) { out = null; }
+      const inject = out && typeof out.inject === 'string' ? out.inject : '';
+      finder.debugLog('prime', { agent: found.config.agentId, port: sc.port, status: res.statusCode, kept: out && out.kept, total: out && out.total, reason: out && out.reason });
+      if (res.statusCode === 200 && inject) {
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: inject },
+        }));
+      }
+      process.exit(0);
+    });
+  });
+  req.on('error', function () { process.exit(0); });
+  req.on('timeout', function () { req.destroy(); process.exit(0); });
+  req.end(body);
+}
+`;
+
+/** Everything `awm setup` places in ~/.claude/hooks/. */
+export const HOOK_SCRIPTS: ReadonlyArray<{ file: string; source: string }> = [
+  { file: 'awm-find-sidecar.cjs', source: FIND_SIDECAR_SCRIPT },
+  { file: 'awm-checkpoint.cjs', source: CHECKPOINT_HOOK_SCRIPT },
+  { file: 'awm-prime.cjs', source: PRIME_HOOK_SCRIPT },
+];
+
+/** The fallback record the finder reads when no MCP config governs a cwd. */
+export interface HooksRecord {
+  version: string;
+  agentId: string;
+  dbPath: string;
+  secretPath: string;
+  hookPort: string;
+  hookPortRange: string;
+  installedAt: string;
+}