agent-working-memory 0.7.17 → 0.8.5

package/README.md

@@ -86,18 +86,25 @@ The design is based on cognitive science — ACT-R activation decay, Hebbian lea
 
 ---
 
-## Benchmarks (v0.6.0)
-
-### Eval Harness (new in v0.6.0)
-
-| Suite | Score | Threshold | What it tests |
-|-------|-------|-----------|---------------|
-| Retrieval | **Recall@5 = 0.800** | >= 0.80 | 200 facts, 50 queries — BM25 + vector + reranker pipeline precision |
-| Associative | **success@10 = 1.000** | >= 0.70 | 20 multi-hop causal chains — graph walk finds non-obvious connections |
-| Redundancy | **dedup F1 = 0.966** | >= 0.80 | 50 clusters × 4 paraphrases — consolidation removes duplicates correctly |
-| Temporal | **Spearman = 0.932** | >= 0.75 | 25 facts with controlled age/access — ACT-R decay ranking accuracy |
-
-Key finding: **consolidation improves retrieval by 30%** — post-consolidation recall (0.950) exceeds pre-consolidation (0.650). Removing redundant noise helps ranking.
+## Benchmarks
+
+### Eval Harness
+
+| 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 |
+
+> **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.
 
 ### Full Test Suite
 
@@ -113,6 +120,7 @@ Key finding: **consolidation improves retrieval by 30%** — post-consolidation
 | `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) |
 
@@ -277,6 +285,46 @@ curl -X POST http://localhost:8400/memory/activate \
   }'
 ```
 
+### Substrate primitives (new in 0.8)
+
+For long-running structured projects — novels, codebases, investigations,
+design docs — where the agent needs to track typed state across hundreds
+of writes without polluting cognitive retrieval. Full reference at
+[`docs/reference.md`](docs/reference.md).
+
+```bash
+# "Latest emotional state per character" — one round trip
+curl -X POST http://localhost:8400/memory/latest-by-tag -d '{
+  "agentId": "novel-x", "tagKey": "character=",
+  "scopeTagsAll": ["topic=emotional-state"], "sortBy": "sequence"
+}'
+
+# "Top 40 active promises by weight, excluding resolved" — filter + sort native
+curl -X POST http://localhost:8400/memory/top-by -d '{
+  "agentId": "novel-x", "sortField": "weight=", "order": "desc",
+  "filterTagsAll": ["topic=promise", "state=active"],
+  "filterTagsNone": ["kind=advancement"], "limit": 40
+}'
+
+# Atomic write-and-supersede by concept match (Form B)
+curl -X POST http://localhost:8400/memory/supersede -d '{
+  "agentId": "novel-x",
+  "matchConcept": "Mara's deferred disclosure",
+  "newEngram": {
+    "concept": "Mara's disclosure — RESOLVED in Ch 3",
+    "content": "...", "memory_class": "structural"
+  }
+}'
+
+# Race-free chronology
+curl http://localhost:8400/memory/sequence/novel-x/next
+```
+
+New `memory_class: "structural"` keeps high-volume system-written records
+(chapter analyses, promise advancements, commit logs) out of cognitive
+`/activate` while preserving them with canonical-level salience. See the
+[CHANGELOG entry for 0.8.0](CHANGELOG.md) for the full design.
+
 ---
 
 ## How It Works
@@ -395,6 +443,18 @@ npm run test:locomo   # LoCoMo industry benchmark (28.2%)
 | `AWM_DISABLE_RERANK_SKIP` | *(unset)* | Set to `1` to disable the reranker skip on clear-winner queries (0.7.10+). Forces every recall through the cross-encoder |
 | `AWM_DISABLE_EXPANSION_CACHE` | *(unset)* | Set to `1` to disable the query expansion skip heuristic + LRU cache (0.7.11+). Forces every recall through the flan-t5-small expander |
 | `AWM_WORKSPACE` | *(unset)* | Default workspace for cross-agent recall in hive setups |
+| `AWM_STORE_BACKEND` | `sqlite` | `sqlite` (better-sqlite3 + FTS5) or `pglite` (PGlite + pgvector + pgroonga). 0.8.x. |
+| `AWM_DB_PATH` | `memory.db` (SQLite) / `./memory-pglite` (PGlite) | Storage path. Directory for PGlite, file for SQLite. |
+| `AWM_CONF_SHARPNESS_W` | `0.4` | Weight of `top1 / mean(top5)` in recall confidence (PR-1, v0.8.5) |
+| `AWM_CONF_CLIFF_W` | `0.3` | Weight of `(top1 - top10) / top1` in recall confidence (PR-1, v0.8.5) |
+| `AWM_CONF_FLOOR_W` | `0.3` | Weight of `top1` absolute score in recall confidence (PR-1, v0.8.5) |
+| `AWM_FADE_DAYS_SINCE_ACCESS` | `45` | Days without access before a stale active engram fades (v0.8.5) |
+| `AWM_FADE_KEEP_CHARS` | `150` | Chars retained in faded engram content (v0.8.5) |
+| `AWM_FADE_MIN_CONTENT_LEN` | `250` | Don't fade engrams shorter than this — nothing to trim (v0.8.5) |
+| `AWM_FADE_MAX_PER_CYCLE` | `25` | Max engrams faded per consolidation cycle — gradual, not sudden (v0.8.5) |
+| `AWM_GRANULARITY_COMPACT_LEN` | `200` | Char cap for `granularity: 'compact'` summaries (v0.8.5) |
+| `AWM_GRANULARITY_FULL_LEN` | `1000` | Char cap for top result under `granularity: 'auto'` when confidence ≥ threshold (v0.8.5) |
+| `AWM_GRANULARITY_AUTO_THRESHOLD` | `0.4` | Recall-confidence threshold above which `'auto'` granularity gives the top result a long-form summary (v0.8.5) |
 
 ## Tech Stack
 
@@ -413,6 +473,81 @@ 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.8.5
+
+A research-grounded hardening pass on recall quality, retraction propagation,
+and lifecycle management. Every change is **fully additive** — existing
+callers keep working without modification. Full validation at the milestone:
+`vitest run` 549/549 pass; `test:self` 97.6% EXCELLENT (was 91.4% on 0.8.0);
+`test:ab` AWM 89.3% vs Baseline 83.0% (+6.4 points); `test:perf` 4/4 PASS.
+
+- **Recall confidence as data (PR-1).** Every `ActivationResult` now carries
+  a `confidence` field in [0, 1] — a score-distribution-aware signal
+  (sharpness + cliff + floor blended via weighted geometric mean) that tells
+  the caller how trustworthy the recall set is. Same value on every result
+  in a recall — it describes the *set*, not the individual. Research grounding:
+  Geifman & El-Yaniv (NeurIPS 2017), Roitero et al (SIGIR 2022). Default
+  behavior unchanged; this is data, not a gate.
+
+- **Opt-in confidence-based abstention (PR-2).** Callers can pass
+  `requireConfidence` (typical values: 0.10 strict, 0.25 balanced, 0.40
+  aggressive). When set, the engine returns `[]` on recalls whose
+  distribution shape falls below the threshold — defeats the
+  "best-of-bad-bunch" leak where a noisy recall returns a weak top result
+  that the agent then trusts.
+
+- **Coherence-weighted retraction (#18).** Retraction penalty propagation
+  is no longer uniform. Multiplier scales with local neighborhood cohesion:
+  dense topically-coherent clusters (a narrative) get heavier penalties when
+  the seed is wrong; hub structures (popular node with heterogeneous edges)
+  get lighter penalties. Implements Carrillo et al, "Continued Influence
+  Effect" (ICCM 2025).
+
+- **Counter-narrative replacement on supersede/correction (#19).** When
+  retraction creates a counter-content correction, the new engram inherits
+  the original's `'connection'` edges (scaled 0.7×, capped at 10
+  inheritances, with `invalidation` / `causal` / `temporal` skipped). The
+  corrected fact takes over the graph role of the wrong fact rather than
+  leaving the corrected fact disconnected.
+
+- **Content fade stage (#20) — Paper 1.** New intermediate `'fading'`
+  lifecycle stage between `'active'` and `'archived'`. Engrams accessed
+  before but stale (no access in 45+ days, content > 250 chars) get content
+  trimmed to 150 chars + `… [faded]` marker. Concept, tags, and embedding
+  preserved — the engram still participates in BM25 + vector recall, just
+  with less body to score against. Models human memory's loss of surface
+  detail while retaining cue-association pathways (PLOS Comp Biology on
+  storage degradation). Heavily-used (`accessCount >= 10`), `canonical`,
+  `structural`, and retracted engrams excluded.
+
+- **Adaptive output granularity (#21) — Paper 3.** New
+  `granularity: 'full' | 'compact' | 'auto'` on `ActivationQuery`.
+  `'compact'` attaches a 200-char `summary` to every result. `'auto'` is
+  confidence-adaptive: when recall confidence ≥ 0.4, the top result gets
+  a long-form summary and the rest are compact; when confidence is low,
+  everything is compact so the agent can scan a diverse set without
+  drowning in content. Engram body never modified — just the response shape.
+  Models cognitive teaming (Brill 2018 ACT-R collaboration).
+
+## What's New in v0.8.1
+
+- **Coordination control layer** — `FailureMode` classifier + mutation-hint
+  retry on `cleanupStale`, per-worker `CircuitBreaker`, and voluntary
+  `POST /assignment/:id/fail` endpoint. Designed to reduce the 11.5%
+  failure-with-no-retry rate observed in production hive runs (81/703).
+  Two new schema columns on `coord_assignments` plus a `coord_circuit_state`
+  table — both additive `CREATE IF NOT EXISTS` migrations.
+
+## What's New in v0.8.0
+
+- **Substrate primitives for long-running structured projects** — four new
+  HTTP endpoints (`/memory/latest-by-tag`, `/memory/top-by`,
+  `/memory/resolve`, `/memory/supersede` Form B), three query operators
+  (`tagsAll`, `tagsAny`, `tagsNone`), and a fourth `memory_class` value
+  (`structural`). Optional engram columns `sequence` + `references_json`
+  enable race-free chronology and typed cross-record links. Designed against
+  the NovelForge 36,000-word "Drawdown" test bed.
+
 ## What's New in v0.7.16
 
 - **`awm setup --global` template now teaches *write quality*.** Two new sections in `AWM_INSTRUCTION_CONTENT`:
@@ -524,15 +659,21 @@ See [CHANGELOG.md](CHANGELOG.md) for full details.
 
 ## Project Status
 
-AWM is in active development (v0.7.15). The core memory pipeline, consolidation system, multi-agent coordination, and MCP integration are stable and used daily in production coding workflows.
+AWM is in active development (v0.8.5). The core memory pipeline, consolidation
+system, multi-agent coordination, and MCP integration are stable and used
+daily in production coding workflows.
 
 - Core retrieval and consolidation: **stable**
 - MCP tools and Claude Code integration: **stable**
-- Multi-agent coordination: **stable** (v0.6.0)
+- Multi-agent coordination: **stable** (v0.8.1 hardening)
 - Task management: **stable**
 - Hook sidecar and auto-checkpoint: **stable**
 - HTTP API: **stable** (for custom agents)
-- Eval harness: **stable** (v0.6.0)
+- Eval harness: **stable** (v0.6.0, extended through 0.8.x)
+- Recall confidence + opt-in abstention (PR-1, PR-2): **stable** (v0.8.5)
+- Coherence-weighted retraction + counter-narrative inheritance: **stable** (v0.8.5)
+- Content fade stage + adaptive output granularity: **stable** (v0.8.5)
+- PGlite backend (alternative to SQLite, with pgvector + ivfflat): **stable** (v0.8.x)
 
 See [CHANGELOG.md](CHANGELOG.md) for version history.
 

package/dist/adapters/common.js

@@ -164,207 +164,207 @@ export function upsertAwmSection(filePath, newContent, options = {}) {
     writeFileSync(filePath, rebuilt);
     return `${fname}: AWM section updated (preserved surrounding content)`;
 }
-export const AWM_INSTRUCTION_CONTENT = `
-## Memory (AWM) — MANDATORY
-
-**AWM is THE memory system.** Use it via the \`agent-working-memory\` MCP server
-(preferred) or HTTP at \`http://127.0.0.1:8400\` (fallback). The file-based
-auto-memory at \`~/.claude/projects/.../memory/*.md\` is a LEGACY bootstrap path —
-**do not write new memories to it.** All persistent knowledge goes through AWM.
-
-If MCP tools aren't loaded at session start, use ToolSearch with
-\`select:mcp__agent-working-memory__memory_recall,mcp__agent-working-memory__memory_write\`
-to load them. If the MCP server isn't responsive, restart with \`/mcp\` or use
-the HTTP endpoints (\`POST /memory/write-batch\`, \`POST /memory/activate\`)
-directly — but **DO NOT fall back to markdown files**. Files drift the moment
-you write them; AWM stays current because every agent reads + writes the same store.
-
-### Lifecycle (always do these, in this order)
-1. **Session start**: call \`memory_restore\` to recover previous context.
-2. **Starting a task**: call \`memory_task_begin\` (checkpoints + recalls relevant memories).
-3. **During work**: call \`memory_recall\` BEFORE stating any fact, BEFORE searching
-   the filesystem, BEFORE making architectural decisions. Recall is ~300ms — cheaper
-   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.
-
-### Write memory when:
-- A project decision is made or changed
-- A root cause is discovered after debugging
-- A reusable implementation pattern is established
-- A user preference, constraint, or requirement is clarified
-- A prior assumption is found to be wrong
-- A significant piece of work is completed
-
-### Writing for recall (the highest-leverage section)
-A memory's recall quality is set the moment you write it. AWM is fast at
-finding what's findable — but if the write is shaped wrong, no retriever
-can rescue it. Be slightly more verbose at the front than feels natural:
-the first 1-2 sentences are what BM25, the embedding model, and concept
-extraction all see most strongly.
-
-- **Lead with the rule or fact.** Don't open with context or backstory.
-  "Don't mock the database in integration tests." comes first; the reason
-  comes second. Recall scans the head of the body, not the tail.
-- **Pick the most specific topic.** Not \`auth\` — \`auth-magic-link-rate-limit\`.
-  Topic is a hard filter at recall time. Generic topics hide the memory in
-  a noisy bucket where it competes with everything else in the area.
-- **Include 2+ retrievable identifiers.** File paths, function names, table
-  columns, ticket IDs, exact error strings, the literal terms a future query
-  will use. \`AccountingService.closePeriod()\` beats "the accounting code."
-  \`tblMemberDetails.activation_date\` beats "the activation column."
-  \`schema/072-period-close.sql\` beats "the migration."
-- **Write in the vocabulary of the future question.** When you imagine asking
-  this in three months, what nouns will you use? Use those nouns. Don't
-  paraphrase the user's domain language into your own neutral summary.
-- **Reserve canonical for stable invariants.** Decisions, requirements,
-  hard facts, cross-agent shared context. Working class (default) is correct
-  for findings, observations, and progress notes. The canonical floor is
-  0.7 salience — overusing it pollutes the canonical layer and the floor
-  loses meaning.
-- **Include the why for feedback memories.** A rule without a reason can't
-  be applied to edge cases. "Don't mock the database" is brittle. "Don't
-  mock the database — last quarter mocked tests masked a broken migration"
-  is portable to new situations.
-
-### Tagging rules (REQUIRED — AWM's prefix-tag retrieval boost depends on these)
-
-Every \`memory_write\` should pass these structured fields. AWM stores each as a
-prefix-tag like \`proj=\`, \`topic=\`, \`intent=\`, etc. and uses them for BM25
-and entity-bridge boosts at recall time.
-
-| Field | Required? | Format | Example |
-|---|---|---|---|
-| \`project\` | **YES** | one short word matching the current project | \`"EquiHub"\`, \`"AWM"\`, \`"USEA-Agent"\` |
-| \`topic\` | **YES** | one or more lowercase area words | \`"database-migration"\`, \`"benchmarks"\` |
-| \`intent\` | **YES** | one of: \`decision\` / \`finding\` / \`todo\` / \`question\` / \`context\` | \`"finding"\` |
-| \`confidence_level\` | **YES** | \`verified\` (tested) / \`observed\` (read in code) / \`assumed\` (reasoning) | \`"verified"\` |
-| \`source\` | recommended | \`code-reading\` / \`debugging\` / \`discussion\` / \`research\` / \`testing\` / \`observation\` | \`"testing"\` |
-| \`memory_class\` | when stable | \`canonical\` (source-of-truth, 0.7 floor, never staged) / \`working\` (default) / \`ephemeral\` | \`"canonical"\` |
-| \`session_id\` | recommended | current conversation ID for entity-bridge boost | autogenerated |
-| \`tags\` | when applicable | extra prefix-tags for IDs and dates | \`["ticket=18360", "date=2026-05-11"]\` |
-
-**Always add identifier tags when present in the content:**
-- \`ticket=<id>\` for Freshdesk tickets
-- \`member=<id>\` for member IDs
-- \`horse=<id>\` for horse_member_id
-- \`usef=<id>\` for USEF lookups
-- \`date=YYYY-MM-DD\` for temporal anchoring (ISO format)
-- \`person=<Name>\` for stakeholder quotes / decisions
-- \`version=<X.Y.Z>\` for release-specific findings
-
-### Memory classes (controls how strictly the salience filter gates the write)
-- \`memory_class: canonical\` — source-of-truth memories. Floor 0.7 salience, never staged.
-  Use for: user-stated decisions, project requirements, verified architectural facts,
-  cross-agent shared context. **In a hive (multi-agent) setup, always use \`canonical\`
-  for writes that other agents must be able to recall** — the default \`working\` class
-  may get filtered.
-- \`memory_class: working\` (default) — observations and findings. Salience-gated.
-- \`memory_class: ephemeral\` — short-lived context that should decay quickly.
-
-### Salience auto-promotion (defense in depth)
-The salience filter automatically promotes certain content patterns even if you forget
-to set \`memory_class\` explicitly:
-- **User feedback** — content starting with "Robert said…", "Katherine directed…",
-  "Nancy decided…" etc. auto-promotes to canonical. So quoting the user verbatim
-  always preserves the decision.
-- **Verified operational records** — content with an action verb (Submitted, Finalized,
-  Completed, Reconciled, Triaged, Posted, Resolved, Stamped, Pushed, Deployed, Migrated,
-  Imported, Exported, Backfilled) plus 2+ concrete identifiers (ISO date \`YYYY-MM-DD\`,
-  or contextual numeric IDs like "event 18969", "ticket #18330", "USEF 341980") gets
-  a 0.45 salience floor. So batch summaries with real IDs survive even when topic
-  terms repeat.
-
-If neither pattern applies and you want a memory to definitely survive, set
-\`memory_class: canonical\` explicitly. Don't rely on auto-promotion for important writes.
-
-### Recall memory when:
-- **BEFORE stating ANY fact about how a system works** — recall first; if AWM doesn't
-  have it, read the code. Never guess and present it as fact.
-- **BEFORE searching the filesystem** — recall first; AWM is faster and has cross-session
-  knowledge that file search doesn't.
-- Starting work on a new task or subsystem
-- Re-entering code you haven't touched recently
-- After a failed attempt — check if there's prior knowledge
-- Before refactoring or making architectural changes
-- When a topic comes up that you might have prior context on
-
-Recall is fast (~300ms typical). Use it freely.
-
-### Recall strategy (when one query isn't enough)
-AWM's adaptive retrieval handles most query variations natively — synonym
-expansion, multi-channel scoring, embedding + BM25 + reranker agreement.
-A single recall is usually enough.
-
-When it isn't:
-- **If the first recall returns nothing or returns the wrong things, reformulate.**
-  Try a second query with different phrasing — synonyms, more specific nouns,
-  the exact identifier from the code rather than the conceptual name. Two or
-  three recalls cost less than one filesystem search.
-- **Use the words a domain expert would use, not generic English.** "Period
-  close lock" not "accounting feature"; "magic link rate limit" not "auth issue."
-- **For broad exploration, pass \`mode: "exploratory"\`** — wider candidate
-  pool, lower precision floor. For specific lookups, leave mode unset (auto).
-- **Don't ensemble more than 3 reformulations.** If three different phrasings
-  return nothing, the memory probably isn't there — read the code instead of
-  burning more recalls.
-
-### 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.
-- 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.**
-
-### Example — good vs bad memory_write
-
-**BAD** (no prefix tags, vague concept, can't be recalled by future queries):
-\`\`\`
-memory_write(
-  concept="found a bug",
-  content="The thing I was looking at was broken so I fixed it."
-)
-\`\`\`
-
-**GOOD** (rich identifiers, structured metadata, prefix tags):
-\`\`\`
-memory_write(
-  concept="EquiHub period-close BLOCKED check missing server-side",
-  content="apps/web/app/(accounting)/accounting/period-close/page.tsx had client-only BLOCKED enforcement. Fixed by adding server-side check in AccountingService.closePeriod() per schema/072-period-close.sql. Without server-side check a malicious request could bypass via direct API call.",
-  project="EquiHub",
-  topic="accounting",
-  intent="finding",
-  confidence_level="verified",
-  source="debugging",
-  memory_class="canonical",
-  tags=["ticket=18360", "person=Robert", "date=2026-05-11", "topic=period-close", "topic=security"]
-)
-\`\`\`
-
-### Also:
-- To track work items: memory_task_add, memory_task_update, memory_task_list, memory_task_next
-- AWM is shared across all agents in real time. When any agent writes or supersedes a
-  memory, every other agent can recall it immediately.
-
-### 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. Each optimization
-is gated by an env-var so it can be disabled for A/B testing if a regression
-appears in your workload:
-
-- \`AWM_DISABLE_POOL_FILTER=1\` (0.7.7+) — disables the candidate pool reduction
-  pre-filter in recall. Reverts to scoring all active candidates.
-- \`AWM_DISABLE_SLIM_CACHE=1\` (0.7.10+) — disables the in-memory slim cache.
-  Reverts to per-recall SQL fetch + Buffer→Float32Array conversion.
-- \`AWM_DISABLE_RERANK_SKIP=1\` (0.7.10+) — disables the cross-encoder skip on
-  clear-winner queries. Forces every recall through the reranker.
-- \`AWM_DISABLE_EXPANSION_CACHE=1\` (0.7.11+) — disables the query expansion
-  skip heuristic + LRU cache. Forces every recall through flan-t5-small.
-
-In production, leave these all unset. Use only when diagnosing a suspected
-recall-quality regression.
+export const AWM_INSTRUCTION_CONTENT = `
+## Memory (AWM) — MANDATORY
+
+**AWM is THE memory system.** Use it via the \`agent-working-memory\` MCP server
+(preferred) or HTTP at \`http://127.0.0.1:8400\` (fallback). The file-based
+auto-memory at \`~/.claude/projects/.../memory/*.md\` is a LEGACY bootstrap path —
+**do not write new memories to it.** All persistent knowledge goes through AWM.
+
+If MCP tools aren't loaded at session start, use ToolSearch with
+\`select:mcp__agent-working-memory__memory_recall,mcp__agent-working-memory__memory_write\`
+to load them. If the MCP server isn't responsive, restart with \`/mcp\` or use
+the HTTP endpoints (\`POST /memory/write-batch\`, \`POST /memory/activate\`)
+directly — but **DO NOT fall back to markdown files**. Files drift the moment
+you write them; AWM stays current because every agent reads + writes the same store.
+
+### Lifecycle (always do these, in this order)
+1. **Session start**: call \`memory_restore\` to recover previous context.
+2. **Starting a task**: call \`memory_task_begin\` (checkpoints + recalls relevant memories).
+3. **During work**: call \`memory_recall\` BEFORE stating any fact, BEFORE searching
+   the filesystem, BEFORE making architectural decisions. Recall is ~300ms — cheaper
+   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.
+
+### Write memory when:
+- A project decision is made or changed
+- A root cause is discovered after debugging
+- A reusable implementation pattern is established
+- A user preference, constraint, or requirement is clarified
+- A prior assumption is found to be wrong
+- A significant piece of work is completed
+
+### Writing for recall (the highest-leverage section)
+A memory's recall quality is set the moment you write it. AWM is fast at
+finding what's findable — but if the write is shaped wrong, no retriever
+can rescue it. Be slightly more verbose at the front than feels natural:
+the first 1-2 sentences are what BM25, the embedding model, and concept
+extraction all see most strongly.
+
+- **Lead with the rule or fact.** Don't open with context or backstory.
+  "Don't mock the database in integration tests." comes first; the reason
+  comes second. Recall scans the head of the body, not the tail.
+- **Pick the most specific topic.** Not \`auth\` — \`auth-magic-link-rate-limit\`.
+  Topic is a hard filter at recall time. Generic topics hide the memory in
+  a noisy bucket where it competes with everything else in the area.
+- **Include 2+ retrievable identifiers.** File paths, function names, table
+  columns, ticket IDs, exact error strings, the literal terms a future query
+  will use. \`AccountingService.closePeriod()\` beats "the accounting code."
+  \`tblMemberDetails.activation_date\` beats "the activation column."
+  \`schema/072-period-close.sql\` beats "the migration."
+- **Write in the vocabulary of the future question.** When you imagine asking
+  this in three months, what nouns will you use? Use those nouns. Don't
+  paraphrase the user's domain language into your own neutral summary.
+- **Reserve canonical for stable invariants.** Decisions, requirements,
+  hard facts, cross-agent shared context. Working class (default) is correct
+  for findings, observations, and progress notes. The canonical floor is
+  0.7 salience — overusing it pollutes the canonical layer and the floor
+  loses meaning.
+- **Include the why for feedback memories.** A rule without a reason can't
+  be applied to edge cases. "Don't mock the database" is brittle. "Don't
+  mock the database — last quarter mocked tests masked a broken migration"
+  is portable to new situations.
+
+### Tagging rules (REQUIRED — AWM's prefix-tag retrieval boost depends on these)
+
+Every \`memory_write\` should pass these structured fields. AWM stores each as a
+prefix-tag like \`proj=\`, \`topic=\`, \`intent=\`, etc. and uses them for BM25
+and entity-bridge boosts at recall time.
+
+| Field | Required? | Format | Example |
+|---|---|---|---|
+| \`project\` | **YES** | one short word matching the current project | \`"EquiHub"\`, \`"AWM"\`, \`"USEA-Agent"\` |
+| \`topic\` | **YES** | one or more lowercase area words | \`"database-migration"\`, \`"benchmarks"\` |
+| \`intent\` | **YES** | one of: \`decision\` / \`finding\` / \`todo\` / \`question\` / \`context\` | \`"finding"\` |
+| \`confidence_level\` | **YES** | \`verified\` (tested) / \`observed\` (read in code) / \`assumed\` (reasoning) | \`"verified"\` |
+| \`source\` | recommended | \`code-reading\` / \`debugging\` / \`discussion\` / \`research\` / \`testing\` / \`observation\` | \`"testing"\` |
+| \`memory_class\` | when stable | \`canonical\` (source-of-truth, 0.7 floor, never staged) / \`working\` (default) / \`ephemeral\` | \`"canonical"\` |
+| \`session_id\` | recommended | current conversation ID for entity-bridge boost | autogenerated |
+| \`tags\` | when applicable | extra prefix-tags for IDs and dates | \`["ticket=18360", "date=2026-05-11"]\` |
+
+**Always add identifier tags when present in the content:**
+- \`ticket=<id>\` for Freshdesk tickets
+- \`member=<id>\` for member IDs
+- \`horse=<id>\` for horse_member_id
+- \`usef=<id>\` for USEF lookups
+- \`date=YYYY-MM-DD\` for temporal anchoring (ISO format)
+- \`person=<Name>\` for stakeholder quotes / decisions
+- \`version=<X.Y.Z>\` for release-specific findings
+
+### Memory classes (controls how strictly the salience filter gates the write)
+- \`memory_class: canonical\` — source-of-truth memories. Floor 0.7 salience, never staged.
+  Use for: user-stated decisions, project requirements, verified architectural facts,
+  cross-agent shared context. **In a hive (multi-agent) setup, always use \`canonical\`
+  for writes that other agents must be able to recall** — the default \`working\` class
+  may get filtered.
+- \`memory_class: working\` (default) — observations and findings. Salience-gated.
+- \`memory_class: ephemeral\` — short-lived context that should decay quickly.
+
+### Salience auto-promotion (defense in depth)
+The salience filter automatically promotes certain content patterns even if you forget
+to set \`memory_class\` explicitly:
+- **User feedback** — content starting with "Robert said…", "Katherine directed…",
+  "Nancy decided…" etc. auto-promotes to canonical. So quoting the user verbatim
+  always preserves the decision.
+- **Verified operational records** — content with an action verb (Submitted, Finalized,
+  Completed, Reconciled, Triaged, Posted, Resolved, Stamped, Pushed, Deployed, Migrated,
+  Imported, Exported, Backfilled) plus 2+ concrete identifiers (ISO date \`YYYY-MM-DD\`,
+  or contextual numeric IDs like "event 18969", "ticket #18330", "USEF 341980") gets
+  a 0.45 salience floor. So batch summaries with real IDs survive even when topic
+  terms repeat.
+
+If neither pattern applies and you want a memory to definitely survive, set
+\`memory_class: canonical\` explicitly. Don't rely on auto-promotion for important writes.
+
+### Recall memory when:
+- **BEFORE stating ANY fact about how a system works** — recall first; if AWM doesn't
+  have it, read the code. Never guess and present it as fact.
+- **BEFORE searching the filesystem** — recall first; AWM is faster and has cross-session
+  knowledge that file search doesn't.
+- Starting work on a new task or subsystem
+- Re-entering code you haven't touched recently
+- After a failed attempt — check if there's prior knowledge
+- Before refactoring or making architectural changes
+- When a topic comes up that you might have prior context on
+
+Recall is fast (~300ms typical). Use it freely.
+
+### Recall strategy (when one query isn't enough)
+AWM's adaptive retrieval handles most query variations natively — synonym
+expansion, multi-channel scoring, embedding + BM25 + reranker agreement.
+A single recall is usually enough.
+
+When it isn't:
+- **If the first recall returns nothing or returns the wrong things, reformulate.**
+  Try a second query with different phrasing — synonyms, more specific nouns,
+  the exact identifier from the code rather than the conceptual name. Two or
+  three recalls cost less than one filesystem search.
+- **Use the words a domain expert would use, not generic English.** "Period
+  close lock" not "accounting feature"; "magic link rate limit" not "auth issue."
+- **For broad exploration, pass \`mode: "exploratory"\`** — wider candidate
+  pool, lower precision floor. For specific lookups, leave mode unset (auto).
+- **Don't ensemble more than 3 reformulations.** If three different phrasings
+  return nothing, the memory probably isn't there — read the code instead of
+  burning more recalls.
+
+### 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.
+- 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.**
+
+### Example — good vs bad memory_write
+
+**BAD** (no prefix tags, vague concept, can't be recalled by future queries):
+\`\`\`
+memory_write(
+  concept="found a bug",
+  content="The thing I was looking at was broken so I fixed it."
+)
+\`\`\`
+
+**GOOD** (rich identifiers, structured metadata, prefix tags):
+\`\`\`
+memory_write(
+  concept="EquiHub period-close BLOCKED check missing server-side",
+  content="apps/web/app/(accounting)/accounting/period-close/page.tsx had client-only BLOCKED enforcement. Fixed by adding server-side check in AccountingService.closePeriod() per schema/072-period-close.sql. Without server-side check a malicious request could bypass via direct API call.",
+  project="EquiHub",
+  topic="accounting",
+  intent="finding",
+  confidence_level="verified",
+  source="debugging",
+  memory_class="canonical",
+  tags=["ticket=18360", "person=Robert", "date=2026-05-11", "topic=period-close", "topic=security"]
+)
+\`\`\`
+
+### Also:
+- To track work items: memory_task_add, memory_task_update, memory_task_list, memory_task_next
+- AWM is shared across all agents in real time. When any agent writes or supersedes a
+  memory, every other agent can recall it immediately.
+
+### 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. Each optimization
+is gated by an env-var so it can be disabled for A/B testing if a regression
+appears in your workload:
+
+- \`AWM_DISABLE_POOL_FILTER=1\` (0.7.7+) — disables the candidate pool reduction
+  pre-filter in recall. Reverts to scoring all active candidates.
+- \`AWM_DISABLE_SLIM_CACHE=1\` (0.7.10+) — disables the in-memory slim cache.
+  Reverts to per-recall SQL fetch + Buffer→Float32Array conversion.
+- \`AWM_DISABLE_RERANK_SKIP=1\` (0.7.10+) — disables the cross-encoder skip on
+  clear-winner queries. Forces every recall through the reranker.
+- \`AWM_DISABLE_EXPANSION_CACHE=1\` (0.7.11+) — disables the query expansion
+  skip heuristic + LRU cache. Forces every recall through flan-t5-small.
+
+In production, leave these all unset. Use only when diagnosing a suspected
+recall-quality regression.
 `.trimStart();
 //# sourceMappingURL=common.js.map