agent-working-memory 0.8.8 → 0.9.1

package/README.md

@@ -84,59 +84,134 @@ Most "memory for AI" projects are vector databases with a retrieval wrapper. AWM
 
 The design is based on cognitive science — ACT-R activation decay, Hebbian learning, complementary learning systems, synaptic homeostasis, and synaptic tagging — rather than ad-hoc heuristics. See [How It Works](#how-it-works) and [docs/cognitive-model.md](docs/cognitive-model.md) for details.
 
+> **New to AWM?** [`docs/pipeline-walkthrough.html`](docs/pipeline-walkthrough.html) is a visual, plain-language walkthrough (no background required) — what happens when AWM learns and recalls a fact, why it's built this way, and how it differs from a plain vector store. Open it in a browser.
+
+> **Build an agent on it:** the [AWM-Native Agent Harness pattern](docs/patterns/awm-native-harness.md) shows how to use AWM as an always-on cognitive *substrate* (not a tool the model calls) so the agent learns automatically by working — letting a cheap model perform at a high level and get cheaper + better over time. Measured: gpt-5.4-mini + AWM beat a frontier model on a domain workload at ~1/40th the cost.
+
+> **For builders & researchers:** [`docs/awm-for-agents.html`](docs/awm-for-agents.html) is the agent playbook — why AWM exists (the context-window wall), the PRIME→ACT→VERIFY→LEARN harness, the full agent feature surface (workspace, session IDs, bearer-token hooks, supersede/feedback), how multi-hop is solved in the harness, and the honest gauntlet findings (where AWM wins, ties, and what isn't measured yet). Open it in a browser.
+
 ---
 
-## Benchmarks
+## Why it matters at scale
 
-### Eval Harness
+The reason AWM exists: **past roughly half a million tokens, you can no longer keep a large project's context alive by carrying it.** The codebase, the docs, the decision history, and the meeting/work transcripts outgrow every model's window — and summarizing to fit silently drops the fact you needed next.
 
-| Suite | Score (v0.8.5) | Score (v0.6.0 baseline) | Threshold | What it tests |
-|-------|---|---|-----------|---------------|
-| Retrieval | **Recall@5 = 0.980** | 0.800 | >= 0.80 | 200 facts, 50 queries — BM25 + vector + reranker pipeline precision |
-| Associative | **success@10 = 1.000** | 1.000 | >= 0.70 | 20 multi-hop causal chains — graph walk finds non-obvious connections |
-| Redundancy | **dedup F1 = 0.966** | 0.966 | >= 0.80 | 50 clusters × 4 paraphrases — consolidation removes duplicates correctly |
-| Temporal | **Spearman = 0.932** | 0.932 | >= 0.75 | 25 facts with controlled age/access — ACT-R decay ranking accuracy |
+These figures come from real-world use on a large software platform project, where a single work agent has accumulated **20,000+ memories** over a multi-million-token codebase and documentation set:
 
-> **v0.8.5 recall fix:** A regression intermediate-step had Recall@5 drop to
-> 0.46. Root cause: the entity-bridge boost (Phase 3.7) inverted top-1 in
-> dense same-concept corpora — it rewarded clones that shared tags with
-> the anchor while excluding the anchor itself. Fix: proportional gating
-> so the boost scales with the textMatch gap between candidate and anchor.
-> Clones near the anchor get near-zero boost; genuine lateral candidates
-> (low textMatch, shared entities) still get the full boost.
-> Result: Recall@5 0.46 → 0.980 with all 4 eval suites green.
+| To answer one question, carry… | tokens | AWM scoped recall |
+|---|---|---|
+| the accumulated memory (~20K memories) | ~1.3M | **~630, flat** |
+| the project's notes & transcript docs | ~2M | **~630, flat** |
+| the whole system (code + docs) | ~29M — fits in no window, any tier | **~630, flat** |
 
-### Full Test Suite
+A scoped recall answers from the relevant *slice*, independent of how large the store grows. Measured consequences on real questions against the real project:
+
+- **~2,000× fewer tokens per query** than carrying the memory store — and **~5× fewer** than opening the single best-matching documentation file (a floor; agents usually open several and still miss cross-file facts).
+- **At scale, "carry everything" isn't an option.** At ~20K memories no context window holds it, so retrieval is not an optimization — it is the only door. A static notes file or long-context approach is forced to truncate, which silently drops facts.
+
+Two structural advantages a file or a flat vector store cannot match:
 
-| Command | Score | What it tests |
-|---------|-------|---------------|
-| `npm run eval` | **4/4 suites pass** | Retrieval, associative, redundancy, temporal benchmarks with ablation support |
-| `npm run test:run` | **77/77 tests** | Unit tests: salience, decay, hebbian, supersession, coordination |
-| `npm run test:mcp` | **5/5 pass** | MCP protocol: write, recall, feedback, retract, stats |
-| `npm run test:self` | **94.1% EXCELLENT** | Pipeline component checks across all cognitive subsystems |
-| `npm run test:edge` | **All pass** | 9 failure modes: narcissistic interference, identity collision, contradiction trapping, bridge overshoot, noise forgetting |
-| `npm run test:stress` | **96.2% (50/52)** | 500 memories, 100 sleep cycles, catastrophic forgetting, adversarial spam, recovery |
-| `npm run test:workday` | **93.3% EXCELLENT** | 43 memories across 4 projects, cross-cutting queries, noise filtering |
-| `npm run test:ab` | **AWM 20/22 vs Baseline 18/22** | AWM outperforms keyword baseline on architecture + testing topics |
-| `npm run test:sleep` | **71.4%** | 60 memories, 4 topic clusters, consolidation impact across 3 cycles |
-| `npm run test:tokens` | **56.3% savings, 2.3x efficiency** | Memory-guided context vs full history, keyword accuracy 72.5% |
-| `scripts/measure-claude-vs-awm.ts` | **9.8× lower aggregate cost vs file_retrieval** | Real Claude Code session audit: AWM recall vs Read/Grep/Glob workflows |
-| `npm run test:pilot` | **14/15 pass** | Production-like queries with noise rejection (5/5 noise rejected) |
-| `npm run test:locomo` | **28.2%** | Industry-standard LoCoMo conversational memory benchmark (1,986 QA pairs) |
-
-### Consolidation Health (v0.6.0)
-
-| Metric | Value |
-|--------|-------|
-| Topic clusters formed | **10** per consolidation cycle |
-| Cross-topic bridges | **20** in first cycle |
-| Edges strengthened | **135** per cycle (access-weighted) |
-| Graph size at scale | **3,000-4,500 edges** (500 memories) |
-| Recall after 100 cycles | **90%** stable |
-| Catastrophic forgetting survival | **5/5** (100%) |
-| Post-dedup retrieval | **0.950** (consolidation improves recall) |
-
-All evals are reproducible. See [Testing & Evaluation](#testing--evaluation).
+- **Staleness is tracked.** When a fact changes, `memory_supersede` retires the old value and recall stops returning it — the system *knows* what changed. A notes file or repo goes stale silently; you would re-scan everything to find out. (This work agent has superseded and retracted dozens of facts as the project moved.)
+- **Dead weight costs nothing.** ~90% of accumulated memories are never recalled for a given task — a notes file pays for all of them in every prompt; recall pays for ≈zero.
+
+### Honest about the trade-offs
+
+- AWM does **not** win on small, one-shot tasks — write/recall overhead exceeds the savings until knowledge is reused or the corpus grows past what fits in context.
+- Recall is not free: a few seconds of latency per query buys the token reduction.
+- Recall accuracy is bounded by what was written — write quality matters (lead with the fact; tag with identifiers like file, table, ticket).
+- It does not replace your source of truth. The intended pattern is: **recall first, read/grep the code for ground truth on a miss, and supersede when reality differs.**
+
+---
+
+## Benchmarks
+
+Two kinds of tests, both reproducible (see [Testing & Evaluation](#testing--evaluation)).
+First, **recall quality** — does the pipeline return the right memory? Second,
+**behavior under stress** — does it stay honest, filter noise, and hold up as the
+store grows and ages? Numbers below were re-run on the 0.9-staged line (2026-06-17).
+
+### 1 · Recall quality (eval harness)
+
+Each suite has a pass threshold; all four pass.
+
+| Suite | Score | Threshold | What it measures |
+|-------|-------|-----------|------------------|
+| Retrieval | **Recall@5 = 0.980** | ≥ 0.80 | 200 facts, 50 queries — does the BM25 + vector + reranker pipeline surface the right fact in the top 5? |
+| Associative | **success@10 = 1.000** | ≥ 0.70 | 20 multi-hop causal chains — does the graph walk find non-obvious connections? |
+| Redundancy | **dedup F1 = 0.966** | ≥ 0.80 | 50 clusters × 4 paraphrases — does consolidation merge duplicates without losing the original? |
+| Temporal | **Spearman = 0.932** | ≥ 0.75 | 25 facts with controlled age/access — does ACT-R decay rank recent/used memories ahead of stale ones? |
+
+### 2 · Behavior under stress & adversarial conditions
+
+These are graded suites (not pass/fail). The headline risk they guard against is a
+memory system that confidently returns the *wrong* thing — so the weakest area is
+called out, not hidden.
+
+| Suite | Score | What it measures |
+|-------|-------|------------------|
+| `test:run` (unit) | **569 / 569** | Salience, decay, Hebbian, supersession, coordination, scheduler |
+| `test:self` | **93.9% (EXCELLENT)** | Every cognitive subsystem end-to-end; weakest = exact-topic retrieval |
+| `test:workday` | **85.4% (GOOD)** | A realistic mixed day — 43 memories across 4 projects, cross-cutting queries; weakest = noise filtering |
+| `test:edge` | **~32 / 34** | Named failure modes: identity collision, contradiction trapping, bridge overshoot, false generalization |
+| `test:ab` | **AWM 10 / 11 vs keyword baseline 8 / 11** | Where the cognitive pipeline beats plain keyword search |
+| `test:pilot` | **14 / 15** (5/5 noise rejected) | Production-like queries that must reject planted distractors |
+| `test:locomo` | **25.7%** | LoCoMo conversational-memory benchmark (a *chatbot* benchmark — see note) |
+| `test:mcp` | **5 / 5** | MCP protocol smoke: write, recall, feedback, retract, stats |
+
+> **On LoCoMo (25.7%):** LoCoMo measures *chatbot* recall ("what did we say about X"
+> across long conversations). It is not the workload AWM is tuned for (productivity /
+> engineering, staying on topic, rejecting noise), and ~66% of AWM's misses there are
+> retriever-coverage (the gold turn isn't in the top-10), not extraction. The 0.9 recall
+> work lifted it from 22.7% with every category up. We report it for comparability, not
+> as the headline.
+
+### 3 · The sleep cycle (consolidation)
+
+The **sleep cycle** is AWM's offline maintenance pass (the term is borrowed from how
+human memory consolidates during sleep). On each cycle it **clusters** related
+memories, builds **cross-topic bridges**, **strengthens** co-used edges, **decays**
+unused ones, and **prunes** duplicates. You run it so the association graph stays
+*healthy and navigable* as the store grows — without it, edges accumulate into noise.
+
+> **Reading the score:** `test:sleep` = **78.6%** is a *consolidation-quality* score —
+> it asks "after the maintenance pass, is recall at least as good and is the structure
+> better?" **It is not recall falling to 78.6%.** In this fixture recall is held flat
+> across three cycles (78.6% before = 78.6% after) while the graph reorganizes. The
+> scaling picture is the real proof:
+
+| Under a 100-cycle stress run | Observed |
+|---|---|
+| Recall across cycles | **holds 90–100%** (no catastrophic forgetting) |
+| Cross-topic recall | **~80%**, stable |
+| Graph self-pruning | edges grow to ~2,300 then prune back to ~1,500 as unused links decay |
+| Clusters / bridges per cycle | ~10 clusters, bridges formed early then settle |
+
+So consolidation *protects* recall over the long run — the per-cycle score measures the
+health of the maintenance, and the stress run shows recall doesn't degrade.
+
+### 4 · Token economics — honest
+
+The win that matters is **structural**: at the scale AWM targets you can't carry the
+project at all (see [Why it matters at scale](#why-it-matters-at-scale)). On real coding
+sessions, scoped recall costs **9.8× less in aggregate** than the Read/Grep/Glob
+rediscovery it replaces (`scripts/measure-claude-vs-awm.ts`).
+
+The per-turn micro-benchmark (`test:tokens`) reports against **two** baselines, because the
+baseline you pick *is* the result:
+
+- **vs carrying the full history** (what a memoryless agent must actually do — it can't know
+  which past turn matters): **+67% savings at 97.5% recall accuracy.** This is the honest,
+  apples-to-apples number.
+- **vs an oracle that pre-scoped context to the exactly-relevant task**: **≈ −13%.** A
+  deliberately brutal bar — it gives the baseline the very scoping that retrieval exists to do —
+  and on a tiny 6–8-turn task a fixed top-5 recall is break-even-to-negative *by construction*.
+
+An earlier build reported ~56% on the oracle bar, but that was an **artifact**: pre-v0.8.5,
+reinforce-on-duplicate silently *discarded* memory content, so recalls were artificially tiny.
+v0.8.5 fixed the data loss (accuracy ~72% → 97.5%); better recall now fills all five slots,
+which *lowers* the oracle-bar number while *raising* correctness. Net: the at-scale structural
+win above is the real story; the oracle bar shows AWM roughly matches perfect manual scoping
+even on a corpus far too small to play to its strengths.
 
 ---
 
@@ -475,6 +550,49 @@ npm run test:locomo   # LoCoMo industry benchmark (28.2%)
 
 All three ML models run locally via ONNX. No external API calls for retrieval. The entire system is a single SQLite file + a Node.js process.
 
+## What's New in v0.9.0
+
+A recall-quality default + new tuning knobs + a builder/researcher doc set.
+Every change is an **env-revertible default** with no API changes — existing
+callers keep working unmodified. Validated: official LoCoMo **22.7% → 25.7%**
+(every category up) **and** adversarial precision **73.4 → 74.9** (strictly
+better on each axis); recall latency ~35 → ~77ms (sub-100ms, tunable); zero
+regression across the standard suite (eval 4-suite identical, 569/569 unit,
+edge 32/34, workday = old config).
+
+- **Wide rerank pool + top-K abstention (the win).** A pipeline-attribution
+  study (new tracer, `tests/locomo-eval/trace.ts`) found the dominant recall
+  loss wasn't candidate generation *or* the reranker — it was the stage between:
+  ~50% of answerable queries had gold that *cleared the candidate floor* but was
+  squeezed out of the rerank pool by the decay-compressed composite **before the
+  high-lift (+3.29) reranker saw it**. Fix: the composite becomes a cheap **wide
+  pre-filter** (`AWM_TOPN_MULT=8`, was 3×), the reranker discriminates on a wider
+  pool (`AWM_RERANK_POOL=max(limit*4,40)`, was `max(limit*2,15)`), and the
+  out-of-domain abstention gate judges only the **post-rerank top-K**
+  (`AWM_ABSTAIN_GATE_K=5`) so widening for recall doesn't inflate the in-domain
+  signal. Reverses the v0.7.13 "pool reduction" change. See
+  [reference.md → Recall tuning](docs/reference.md#recall-tuning-env-overrides).
+
+- **Tunable similarity floors.** `AWM_SIM_FLOOR_TARGETED` / `_EXPLORATORY`
+  (defaults 0.50 / 0.35, unchanged) and the candidate-entry floors are now env
+  overrides for retuning against a different embedder.
+
+- **Opt-in / experimental flags (default-off).** `AWM_QUERY_BRIDGE`
+  (query-named-entity boost — lifts attribution "what does X think" 36% → 92% on
+  a controlled eval; small adversarial cost, so opt-in), `AWM_AUTOTAG`
+  (write-time `entity:`/`cat:` meta-tags), `AWM_BROAD_EDGES`. `AWM_SPREAD`
+  (in-engine spreading activation) is **parked** — it regressed recall by
+  displacing gold; multi-hop is solved harness-side instead (see the playbook).
+
+- **New docs for builders & researchers.** [`docs/awm-for-agents.html`](docs/awm-for-agents.html)
+  — the agent playbook (why AWM exists, the PRIME→ACT→VERIFY→LEARN harness, the
+  full agent feature surface, how multi-hop is solved, and the honest gauntlet
+  findings). [`docs/pipeline-walkthrough.html`](docs/pipeline-walkthrough.html)
+  redesigned for devs/researchers. Both are published on GitHub Pages. A new
+  **Storage Backends + Postgres roadmap** section in
+  [architecture.md](docs/architecture.md) documents SQLite (default) vs PGlite
+  and the path to a networked-Postgres backend (v1 target).
+
 ## What's New in v0.8.5
 
 A research-grounded hardening pass on recall quality, retraction propagation,
@@ -582,6 +700,7 @@ callers keep working without modification. Full validation at the milestone:
 ## What's New in v0.7.13
 
 - **Reranker pool size reduction** — cross-encoder pool dropped from `max(limit*3, 30)` to `max(limit*2, 15)`. For typical agent queries (limit=5 or 10), that's 15-20 candidates reranked instead of 30, halving the cross-encoder cost. Top-K quality preserved (8/8 top-1, identical top-5/top-10 overlap) — reranking the 21st-30th candidates was wasted when the user only wants top-5 anyway.
+  > **⚠️ Superseded in 0.9.0 — this reduction was reversed.** A pipeline-attribution study found that "wasted" tail was actually where ~50% of retrievable answers were being squeezed out *before* the reranker saw them (the small 8-query A/B above missed it). 0.9.0 widens the pool back to `max(limit*4, 40)` and adds a top-K abstention gate — lifting LoCoMo recall 22.7%→25.7% **and** adversarial precision 73.4→74.9, with no regression. See the CHANGELOG and `docs/reference.md` → "Recall tuning."
 
 ## What's New in v0.7.12
 

package/dist/api/routes.js

@@ -655,9 +655,9 @@ export function registerRoutes(app, deps) {
             return reply.code(501).send({ error: 'export endpoint requires the SQLite backend' });
         }
         const db = store.getDb();
-        let engramSql = `SELECT id, agent_id, concept, content, confidence, salience, access_count,
-      last_accessed, created_at, salience_features, reason_codes, stage, ttl,
-      retracted, retracted_by, retracted_at, tags
+        let engramSql = `SELECT id, agent_id, concept, content, confidence, salience, access_count,
+      last_accessed, created_at, salience_features, reason_codes, stage, ttl,
+      retracted, retracted_by, retracted_at, tags
       FROM engrams`;
         const conditions = [];
         const params = [];
@@ -675,7 +675,7 @@ export function registerRoutes(app, deps) {
         engramSql += ' ORDER BY created_at ASC';
         const engrams = db.prepare(engramSql).all(...params);
         const engramIds = new Set(engrams.map(e => e.id));
-        const allAssocs = db.prepare(`SELECT id, from_engram_id, to_engram_id, weight, confidence, type, activation_count, created_at, last_activated
+        const allAssocs = db.prepare(`SELECT id, from_engram_id, to_engram_id, weight, confidence, type, activation_count, created_at, last_activated
        FROM associations`).all();
         const associations = allAssocs.filter(a => engramIds.has(a.from_engram_id) && engramIds.has(a.to_engram_id));
         return reply.send({
@@ -700,9 +700,9 @@ export function registerRoutes(app, deps) {
         if (coordEnabled && typeof deps.store.getDb === 'function') {
             try {
                 const db = deps.store.getDb();
-                const stats = db.prepare(`SELECT
-          (SELECT COUNT(*) FROM coord_agents WHERE status != 'dead') AS agents_alive,
-          (SELECT COUNT(*) FROM coord_assignments WHERE status = 'pending') AS pending_tasks,
+                const stats = db.prepare(`SELECT
+          (SELECT COUNT(*) FROM coord_agents WHERE status != 'dead') AS agents_alive,
+          (SELECT COUNT(*) FROM coord_assignments WHERE status = 'pending') AS pending_tasks,
           (SELECT COUNT(*) FROM coord_locks) AS active_locks`).get();
                 Object.assign(base, stats);
             }

package/dist/cli.js

@@ -38,46 +38,46 @@ catch { /* No .env file */ }
 const args = process.argv.slice(2);
 const command = args[0];
 function printUsage() {
-    console.log(`
-AgentWorkingMemory — Cognitive memory for AI agents
-
-Usage:
-  awm setup [target] [options]                      Configure AWM for an AI CLI
-  awm doctor [target|--all]                         Validate AWM integrations
-  awm mcp                                           Start MCP server (stdio)
-  awm serve [--port <port>]                         Start HTTP API server
-  awm health [--port <port>]                        Check server health
-  awm export --db <path> [--agent <id>] [--output <file>] [--active-only]
-                                                    Export memories to JSON
-  awm import <file> --db <path> [--remap-agent <id>] [--dedupe] [--dry-run]
-                                                    Import memories from JSON
-  awm merge --target <db> --source <db> [--source ...]
-            [--remap uuid=name] [--remap-all-uuids <name>]
-            [--dedupe] [--dry-run]                  Merge multiple memory DBs
-  awm migrate --from <sqlite.db> --to <pglite-dir> [--dry-run] [--verbose]
-                                                    Migrate SQLite DB to PGlite
-
-Setup targets:
-  claude-code (default)   .mcp.json + CLAUDE.md + hooks
-  codex                   ~/.codex/config.toml + AGENTS.md
-  cursor                  .cursor/mcp.json + .cursorrules
-  http                    Connection info for HTTP API
-
-Setup options:
-  --global            Use global scope (recommended for claude-code)
-  --agent-id <id>     Agent identifier (default: project name)
-  --db-path <path>    Database path (default: <awm>/data/memory.db)
-  --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)
-
-Examples:
-  awm setup --global              Claude Code, global (recommended)
-  awm setup codex                 Codex CLI
-  awm setup cursor                Cursor IDE
-  awm setup http                  Generic HTTP integration
-  awm doctor --all                Check all configured targets
+    console.log(`
+AgentWorkingMemory — Cognitive memory for AI agents
+
+Usage:
+  awm setup [target] [options]                      Configure AWM for an AI CLI
+  awm doctor [target|--all]                         Validate AWM integrations
+  awm mcp                                           Start MCP server (stdio)
+  awm serve [--port <port>]                         Start HTTP API server
+  awm health [--port <port>]                        Check server health
+  awm export --db <path> [--agent <id>] [--output <file>] [--active-only]
+                                                    Export memories to JSON
+  awm import <file> --db <path> [--remap-agent <id>] [--dedupe] [--dry-run]
+                                                    Import memories from JSON
+  awm merge --target <db> --source <db> [--source ...]
+            [--remap uuid=name] [--remap-all-uuids <name>]
+            [--dedupe] [--dry-run]                  Merge multiple memory DBs
+  awm migrate --from <sqlite.db> --to <pglite-dir> [--dry-run] [--verbose]
+                                                    Migrate SQLite DB to PGlite
+
+Setup targets:
+  claude-code (default)   .mcp.json + CLAUDE.md + hooks
+  codex                   ~/.codex/config.toml + AGENTS.md
+  cursor                  .cursor/mcp.json + .cursorrules
+  http                    Connection info for HTTP API
+
+Setup options:
+  --global            Use global scope (recommended for claude-code)
+  --agent-id <id>     Agent identifier (default: project name)
+  --db-path <path>    Database path (default: <awm>/data/memory.db)
+  --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)
+
+Examples:
+  awm setup --global              Claude Code, global (recommended)
+  awm setup codex                 Codex CLI
+  awm setup cursor                Cursor IDE
+  awm setup http                  Generic HTTP integration
+  awm doctor --all                Check all configured targets
 `.trim());
 }
 // ─── SETUP ──────────────────────────────────────
@@ -135,18 +135,18 @@ async function setup() {
     const configAction = adapter.writeMcpConfig(ctx);
     const instructionsAction = adapter.writeInstructions(ctx, skipInstructions);
     const hooksAction = adapter.writeHooks(ctx, skipHooks);
-    console.log(`
-AWM configured for ${adapter.name}${isGlobal ? ' (global)' : ''}
-
-  Agent ID:    ${ctx.agentId}
-  DB path:     ${ctx.dbPath}
-  ${configAction}
-  ${instructionsAction}
-  ${hooksAction}
-
-Next steps:
-  1. Restart ${adapter.name} to pick up the MCP server
-  2. Memory tools will appear automatically${adapter.id === 'codex' ? ' (verify with /mcp)' : ''}
+    console.log(`
+AWM configured for ${adapter.name}${isGlobal ? ' (global)' : ''}
+
+  Agent ID:    ${ctx.agentId}
+  DB path:     ${ctx.dbPath}
+  ${configAction}
+  ${instructionsAction}
+  ${hooksAction}
+
+Next steps:
+  1. Restart ${adapter.name} to pick up the MCP server
+  2. Memory tools will appear automatically${adapter.id === 'codex' ? ' (verify with /mcp)' : ''}
 `.trim());
 }
 // ─── DOCTOR ──────────────────────────────────────
@@ -374,23 +374,23 @@ async function importMemories() {
     const Database = (await import('better-sqlite3')).default;
     const db = new Database(dbPath);
     // Ensure tables exist in target
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS engrams (
-      id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, concept TEXT NOT NULL, content TEXT NOT NULL,
-      embedding BLOB, confidence REAL NOT NULL DEFAULT 0.5, salience REAL NOT NULL DEFAULT 0.5,
-      access_count INTEGER NOT NULL DEFAULT 0, last_accessed TEXT NOT NULL, created_at TEXT NOT NULL,
-      salience_features TEXT NOT NULL DEFAULT '{}', reason_codes TEXT NOT NULL DEFAULT '[]',
-      stage TEXT NOT NULL DEFAULT 'active', ttl INTEGER, retracted INTEGER NOT NULL DEFAULT 0,
-      retracted_by TEXT, retracted_at TEXT, tags TEXT NOT NULL DEFAULT '[]',
-      episode_id TEXT, task_status TEXT, task_priority TEXT, blocked_by TEXT,
-      memory_class TEXT NOT NULL DEFAULT 'working', superseded_by TEXT, supersedes TEXT
-    );
-    CREATE TABLE IF NOT EXISTS associations (
-      id TEXT PRIMARY KEY, from_engram_id TEXT NOT NULL, to_engram_id TEXT NOT NULL,
-      weight REAL NOT NULL DEFAULT 0.1, confidence REAL NOT NULL DEFAULT 0.5,
-      type TEXT NOT NULL DEFAULT 'hebbian', activation_count INTEGER NOT NULL DEFAULT 0,
-      created_at TEXT NOT NULL, last_activated TEXT
-    );
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS engrams (
+      id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, concept TEXT NOT NULL, content TEXT NOT NULL,
+      embedding BLOB, confidence REAL NOT NULL DEFAULT 0.5, salience REAL NOT NULL DEFAULT 0.5,
+      access_count INTEGER NOT NULL DEFAULT 0, last_accessed TEXT NOT NULL, created_at TEXT NOT NULL,
+      salience_features TEXT NOT NULL DEFAULT '{}', reason_codes TEXT NOT NULL DEFAULT '[]',
+      stage TEXT NOT NULL DEFAULT 'active', ttl INTEGER, retracted INTEGER NOT NULL DEFAULT 0,
+      retracted_by TEXT, retracted_at TEXT, tags TEXT NOT NULL DEFAULT '[]',
+      episode_id TEXT, task_status TEXT, task_priority TEXT, blocked_by TEXT,
+      memory_class TEXT NOT NULL DEFAULT 'working', superseded_by TEXT, supersedes TEXT
+    );
+    CREATE TABLE IF NOT EXISTS associations (
+      id TEXT PRIMARY KEY, from_engram_id TEXT NOT NULL, to_engram_id TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 0.1, confidence REAL NOT NULL DEFAULT 0.5,
+      type TEXT NOT NULL DEFAULT 'hebbian', activation_count INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL, last_activated TEXT
+    );
   `);
     // Build dedup set if needed
     const existingHashes = new Set();
@@ -405,15 +405,19 @@ async function importMemories() {
     let imported = 0;
     let skippedDupes = 0;
     let skippedRetracted = 0;
-    const insertMem = db.prepare(`
-    INSERT INTO engrams (id, agent_id, concept, content, confidence, salience,
-      access_count, last_accessed, created_at, stage, tags, memory_class,
-      episode_id, task_status, task_priority, supersedes, superseded_by, retracted)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    const insertMem = db.prepare(`
+    INSERT INTO engrams (id, agent_id, concept, content, confidence, salience,
+      access_count, last_accessed, created_at, stage, tags, memory_class,
+      episode_id, task_status, task_priority, supersedes, superseded_by, retracted)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
-    const insertAssoc = db.prepare(`
-    INSERT INTO associations (id, from_engram_id, to_engram_id, weight, type, activation_count, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+    // NOTE: associations.last_activated is NOT NULL on the engrams DB (storage/sqlite.ts),
+    // so importing into an existing store fails if it's omitted — and because import wraps
+    // memories+associations in ONE transaction, that rolls back the memories too (silent
+    // "empty store"). Set it alongside created_at. (migrate/merge paths already do this.)
+    const insertAssoc = db.prepare(`
+    INSERT INTO associations (id, from_engram_id, to_engram_id, weight, type, activation_count, created_at, last_activated)
+    VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
   `);
     const importTx = db.transaction(() => {
         // Import memories
@@ -516,21 +520,21 @@ async function mergeMemories() {
     targetDb.pragma('journal_mode = WAL');
     targetDb.pragma('foreign_keys = ON');
     // Ensure tables exist in target
-    targetDb.exec(`
-    CREATE TABLE IF NOT EXISTS engrams (
-      id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, concept TEXT NOT NULL, content TEXT NOT NULL,
-      embedding BLOB, confidence REAL NOT NULL DEFAULT 0.5, salience REAL NOT NULL DEFAULT 0.5,
-      access_count INTEGER NOT NULL DEFAULT 0, last_accessed TEXT NOT NULL, created_at TEXT NOT NULL,
-      salience_features TEXT NOT NULL DEFAULT '{}', reason_codes TEXT NOT NULL DEFAULT '[]',
-      stage TEXT NOT NULL DEFAULT 'active', ttl INTEGER, retracted INTEGER NOT NULL DEFAULT 0,
-      retracted_by TEXT, retracted_at TEXT, tags TEXT NOT NULL DEFAULT '[]'
-    );
-    CREATE TABLE IF NOT EXISTS associations (
-      id TEXT PRIMARY KEY, from_engram_id TEXT NOT NULL, to_engram_id TEXT NOT NULL,
-      weight REAL NOT NULL DEFAULT 0.1, confidence REAL NOT NULL DEFAULT 0.5,
-      type TEXT NOT NULL DEFAULT 'hebbian', activation_count INTEGER NOT NULL DEFAULT 0,
-      created_at TEXT NOT NULL, last_activated TEXT NOT NULL
-    );
+    targetDb.exec(`
+    CREATE TABLE IF NOT EXISTS engrams (
+      id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, concept TEXT NOT NULL, content TEXT NOT NULL,
+      embedding BLOB, confidence REAL NOT NULL DEFAULT 0.5, salience REAL NOT NULL DEFAULT 0.5,
+      access_count INTEGER NOT NULL DEFAULT 0, last_accessed TEXT NOT NULL, created_at TEXT NOT NULL,
+      salience_features TEXT NOT NULL DEFAULT '{}', reason_codes TEXT NOT NULL DEFAULT '[]',
+      stage TEXT NOT NULL DEFAULT 'active', ttl INTEGER, retracted INTEGER NOT NULL DEFAULT 0,
+      retracted_by TEXT, retracted_at TEXT, tags TEXT NOT NULL DEFAULT '[]'
+    );
+    CREATE TABLE IF NOT EXISTS associations (
+      id TEXT PRIMARY KEY, from_engram_id TEXT NOT NULL, to_engram_id TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 0.1, confidence REAL NOT NULL DEFAULT 0.5,
+      type TEXT NOT NULL DEFAULT 'hebbian', activation_count INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL, last_activated TEXT NOT NULL
+    );
   `);
     // Build dedupe hash set from existing target memories
     const existingHashes = new Set();
@@ -540,16 +544,16 @@ async function mergeMemories() {
             existingHashes.add(contentHash(row.concept, row.content));
         console.log(`Target has ${existingHashes.size} unique memories (for dedupe)\n`);
     }
-    const insertEngram = targetDb.prepare(`
-    INSERT OR IGNORE INTO engrams (id, agent_id, concept, content, confidence, salience, access_count,
-      last_accessed, created_at, salience_features, reason_codes, stage, ttl,
-      retracted, retracted_by, retracted_at, tags)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    const insertEngram = targetDb.prepare(`
+    INSERT OR IGNORE INTO engrams (id, agent_id, concept, content, confidence, salience, access_count,
+      last_accessed, created_at, salience_features, reason_codes, stage, ttl,
+      retracted, retracted_by, retracted_at, tags)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
-    const insertAssoc = targetDb.prepare(`
-    INSERT OR IGNORE INTO associations (id, from_engram_id, to_engram_id, weight, confidence, type,
-      activation_count, created_at, last_activated)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    const insertAssoc = targetDb.prepare(`
+    INSERT OR IGNORE INTO associations (id, from_engram_id, to_engram_id, weight, confidence, type,
+      activation_count, created_at, last_activated)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
     let totalMemories = 0, totalAssociations = 0, totalSkipped = 0;
     for (const sourcePath of sources) {
@@ -558,10 +562,10 @@ async function mergeMemories() {
             continue;
         }
         const sourceDb = new Database(sourcePath, { readonly: true });
-        const engrams = sourceDb.prepare(`SELECT id, agent_id, concept, content, confidence, salience, access_count,
-        last_accessed, created_at, salience_features, reason_codes, stage, ttl,
+        const engrams = sourceDb.prepare(`SELECT id, agent_id, concept, content, confidence, salience, access_count,
+        last_accessed, created_at, salience_features, reason_codes, stage, ttl,
         retracted, retracted_by, retracted_at, tags FROM engrams`).all();
-        const assocs = sourceDb.prepare(`SELECT id, from_engram_id, to_engram_id, weight, confidence, type,
+        const assocs = sourceDb.prepare(`SELECT id, from_engram_id, to_engram_id, weight, confidence, type,
         activation_count, created_at, last_activated FROM associations`).all();
         const idMap = new Map();
         const skippedIds = new Set();