agent-working-memory 0.15.8 → 0.16.0

package/llms.txt

@@ -0,0 +1,437 @@
+# AWM — agent-working-memory
+
+> Persistent, local-first memory for AI coding agents. One Node process, one
+> SQLite file, no cloud and no API keys. It decides what is worth keeping,
+> returns the two or three memories that matter, and returns nothing when
+> nothing fits.
+
+**If you are a language model, read this file first.** It is written to be
+ingested whole. It gives you the mental model, the setup for each situation,
+the configuration that actually matters, and — most importantly — what breaks
+when AWM is installed but not configured well. That last part is where almost
+every disappointing result comes from.
+
+Repository: https://github.com/CompleteIdeas/agent-working-memory
+Package: `agent-working-memory` on npm · Apache-2.0 · Node >= 22
+Docs site: https://completeideas.github.io/agent-working-memory/
+
+Every number in this file is measured and reproducible from the repository.
+Where a claim has a source, the source is named. Where something is unknown or
+weak, it says so.
+
+---
+
+## 1. What it is, and what it is not
+
+**It is** a retrieval store with a salience filter in front of it and a decay
+model underneath. An agent writes short notes as it works; AWM decides whether
+each is worth keeping, embeds and indexes it, and hands back the few that match
+a later query.
+
+**It is not** a vector database, and it is not a transcript log. It does not
+store your conversation. It does not traverse a graph to answer multi-hop
+questions. It will not make an agent remember things it never wrote down.
+
+**The honest version of who it suits:** projects with accumulated decisions
+that outlive a single session, where an agent re-deriving the same context is a
+real cost. On a small or short-lived project the overhead does not pay back.
+`docs/known-limitations.md` and the "Is this for you?" section of `README.md`
+both say this plainly; believe them.
+
+---
+
+## 2. How retrieval actually works
+
+This is the single most useful thing for you to understand, because the common
+failure mode is writing memories that no channel can see.
+
+A recall runs **three scoring channels**, then a reranker decides the order:
+
+1. **Embedding** — `Xenova/bge-small-en-v1.5`, 384 dimensions, ONNX, downloaded
+   on first use and then run locally. The vector is built from
+   **`concept` + `content`**.
+2. **BM25** — SQLite FTS5 over `concept`, `content` and `tags`. This is the
+   only channel that sees tags.
+3. **Cross-encoder reranker** — `Xenova/ms-marco-MiniLM-L-6-v2`. It makes the
+   **final ordering**. Its passage is built from `concept` + `content`, plus
+   tags when `AWM_RERANK_TAGS=1`.
+
+Then two things that matter less than they sound:
+
+- **The association graph** contributes a score to about **85%** of top-3
+  results but changes the top-3 **set in 0%** of them. The reranker overrules
+  it; the graph's boost is capped and never wins. It is retained for the state
+  it accumulates — supersede chains, causal links, co-recall history — not for
+  today's ranking. (`tests/realstore-eval/graph-contribution-probe.ts`.)
+- **ACT-R decay** scores every memory by age, so recall results shift as a
+  store ages. Benchmarks must pin the clock or they drift day to day.
+
+### The three consequences you should act on
+
+- **A word that exists only as a tag is invisible to two of the three
+  channels.** Tag it *and* write it in the body. Measured on a real 30k store:
+  **66%** of the topical terms a memory is tagged with never appear in its
+  text.
+- **The reranker reads a 400-character window.** Anything past it is not seen
+  by the stage that decides final order. This is not a rounding error — on the
+  public benchmark corpus (`npm run bench:public`, 400 probes), `s@1` is
+  **97.3%** when the answer-bearing identifier sits inside the window and
+  **46.8%** when it sits beyond it. Put the decisive identifier **early**.
+- **Multi-hop is your job.** "Who owns the table that the failing report
+  reads?" is two recalls that you make, not one traversal AWM performs. One hop
+  per call.
+
+---
+
+## 3. Configuration that is not optional
+
+`awm setup` installs three retrieval flags. **If they are missing, retrieval is
+materially worse and nothing warns you.** This is the number one cause of "AWM
+didn't find it."
+
+```
+AWM_RERANK2=1              # second-stage rerank by the cross-encoder's own score
+AWM_RERANK_WINDOW=query    # 400-char window centered on the densest query terms,
+                           #   instead of truncating from the start of the body
+AWM_RERANK_TAGS=1          # tags joined into the rerank passage  (+7.4pp s@1)
+```
+
+`AWM_RERANK_WINDOW=query` is the difference between the reranker reading the
+first 400 characters and reading the 400 characters that actually contain the
+query terms. On long memories — and real memories are long, median ~1,965
+characters — that is the difference between finding the fact and missing it.
+
+**Check yours before diagnosing anything else:**
+
+```bash
+awm doctor          # reports config, live sidecars, store, and what is missing
+```
+
+If you installed via something other than `awm setup` — hand-written MCP
+config, a vendored copy, a container — assume these are unset until you have
+seen otherwise.
+
+---
+
+## 4. Setup, by scenario
+
+Pick the one that matches. All of them end up at the same store by default:
+**`~/.awm/memory.db`**.
+
+> **Upgrade note.** Before 0.15.6 the default store lived *inside* the
+> installed npm package, where `npm update` deleted it. If you are coming from
+> an older version, find the old file before upgrading and move it to
+> `~/.awm/memory.db`. 0.15.7 corrected the docs that still taught the old path.
+
+### A. Claude Code, global (the normal case)
+
+```bash
+npm install -g agent-working-memory
+awm setup --global
+```
+
+Restart Claude Code. **19 tools** appear. `awm setup` also writes agent
+instructions into your global `CLAUDE.md` and installs hooks that checkpoint on
+compaction and session end.
+
+Flags: `--no-instructions` (skip the CLAUDE.md edit), `--no-hooks`, `--force`,
+and `--no-prime`, which skips the **UserPromptSubmit prime hook** — the thing
+that injects relevant memories on *every prompt*. Without it, as `awm doctor`
+says, "memory reaches the agent only when it chooses to call memory_recall."
+If an agent seems not to be using its memory, check this first.
+
+### B. Separate pools per project
+
+Not a different install — a different **agent id**. One database file, isolation
+by agent. Give each project its own `.mcp.json` with a distinct `AWM_AGENT_ID`:
+
+```
+~/work/project-a/.mcp.json  →  AWM_AGENT_ID: "project-a"
+~/work/project-b/.mcp.json  →  AWM_AGENT_ID: "project-b"
+```
+
+Each then gets its own namespace in the same store. See
+`docs/claude-code-setup.md` ("Separate Memory Pools").
+
+### C. Claude Code plugin
+
+```bash
+awm plugin          # prints where it is and how to install it
+```
+
+See `docs/plugin.md`. **Upgrading a plugin is not automatic** — a directory
+marketplace does not pull new versions for you. This has bitten people; the doc
+says so explicitly.
+
+### D. Claude Desktop (MCPB bundle)
+
+`npm run pack:mcpb` produces the bundle, or take it from a release. Install it
+by double-clicking the `.mcpb`, dragging it onto the Claude Desktop window, or
+**Settings → Extensions → Advanced settings → Install Extension…**. Desktop then
+asks for two settings: **Memory database** (default `${HOME}/.awm/memory.db` —
+leave it to share one store with Claude Code) and **Memory pool** (default
+`work`). Restart Desktop and you should have nineteen tools.
+
+**Sharing the store with your CLI install is the point** — Desktop and Claude
+Code then see each other's memories. See `docs/desktop.md`.
+
+### E. Server / container
+
+```bash
+awm serve --port 8400
+```
+
+HTTP API, `GET /health`, Docker recipe and Railway / Fly / Render notes in
+`docs/deployment.md`. **Agent isolation on the HTTP API is by convention, not
+enforcement** — any caller can claim any `agentId`. Do not expose it to
+untrusted callers.
+
+### F. Multi-agent / shared pool
+
+Several processes against **one SQLite file** is supported and is the
+interesting case: agent A writes, agent B recalls it on its next call, with no
+network and no central service. SQLite WAL makes this multi-process safe.
+
+**The thing that silently breaks it: unpinned agent identity.** If a session
+does not set an explicit agent id, it lands in a per-directory fallback space
+that scoped recall never sees. The memory is written and is simply invisible to
+everyone else. Always set the identity explicitly, and call `memory_whoami` if
+you are unsure which space you are in.
+
+Cross-agent recall is opt-in per call via the `workspace` parameter; the
+default is agent-scoped.
+
+### G. Embedded in your own app
+
+Import the store and engine directly — see `examples/` and
+`docs/architecture.md`. `tests/longmem-eval/runner.ts` is a compact, working
+example of seeding a store through the real write pipeline and querying it.
+
+### Backend choice
+
+- **SQLite** (default) — multi-process safe via WAL. Use this.
+- **PGlite** — embedded Postgres with pgvector. **Single-process only**: a
+  second process against the same directory aborts. Only for single-process
+  embedding.
+- **Networked Postgres** — a genuinely shared backend across machines.
+
+Auto-detected: if `AWM_DB_PATH` points at an existing directory it is PGlite,
+a file is SQLite.
+
+---
+
+## 5. The 19 tools
+
+**Lifecycle** — `memory_restore` (session start), `memory_task_begin`,
+`memory_task_end`, `memory_checkpoint`.
+
+**Core** — `memory_write`, `memory_recall`.
+
+**Correction** — `memory_supersede` (replace a stale fact; the new version
+inherits the old one's associations), `memory_retract` (it was wrong),
+`memory_feedback` (useful / not-useful, after you used a result).
+
+**Tasks** — `memory_task_add`, `memory_task_update`, `memory_task_list`,
+`memory_task_next`.
+
+**Introspection** — `memory_whoami` (identity, store, backend, ports, sibling
+agent spaces — call this *first* whenever anything about AWM's own state is in
+question), `memory_stats`.
+
+**Onboarding** — `onboard_scan`, `onboard_questions`.
+
+**Output control** — `compress_output`, `retrieve_original`.
+
+### Recall parameters worth knowing
+
+- `granularity: 'compact'` — every result carries a ~200-char query-aware
+  snippet. Saves roughly 70% of recall output tokens when you expect to scan
+  several results. `'auto'` is confidence-adaptive.
+- `require_confidence` — abstain rather than return noise. Default is a light
+  `0.05`. **Do not raise it for ordinary recall**: a miss is expensive because
+  you then go and read the codebase instead (~2,106 tokens, measured), and
+  thresholds of 0.20+ cut net tokens saved by 25% in `tests/abstention-eval`.
+  Raise it only for push-style use where nobody asked.
+- `workspace` — cross-agent recall, opt-in.
+- `limit` — default **3**, and this is a measured choice, not a guess. On 400
+  real-store probes k=3 is the only **token-positive** setting: **+115 tokens
+  per recall, against -680 at k=5**. It is also 41% faster at p50, because
+  `limit` sizes the cross-encoder rerank pool and reranking is ~90% of warm
+  recall time. The cost is ~0.5pp `success@1` versus k=5 — about 3 queries in
+  400, inside noise. Raise it deliberately when you want breadth for
+  orientation; leave it alone when you want a specific fact.
+
+---
+
+## 6. Writing so that recall can find it
+
+Recall quality is decided when you write. Be slightly more verbose at the front
+than feels natural: the head of the body is what all three channels weight most.
+
+- **Lead with the fact or rule.** Not the backstory. "Don't mock the database
+  in integration tests" first; the reason second.
+- **Put the decisive identifier early** — before character 400 if you can. See
+  §2.
+- **Include two or more retrievable identifiers**: file paths, function names,
+  column names, error strings, ticket ids. `SettlementService.closeRun()`
+  beats "the accounting code".
+- **Name the category as well as the specifics.** A memory about scaling an
+  Azure App Service Plan that never contains the words "Azure" or "App Service
+  Plan" cannot be found by them — a real miss, and the reason this rule exists.
+- **Write in the vocabulary of the future question**, not your own summary of
+  it.
+- **Say why**, for any rule. A rule without a reason cannot be applied to a
+  case you did not anticipate.
+
+### Memory classes
+
+- `canonical` — source-of-truth. 0.7 salience floor, never staged. Use for
+  decisions, requirements, and anything other agents must be able to recall.
+- `working` — the default. Findings and observations. Salience-gated, so a
+  weak write may land in staging rather than active.
+- `ephemeral` — decays fast.
+
+### Content fade
+
+Un-recalled memories gradually fade their **content** while keeping their cue
+pathways — concept, tags and embedding stay intact, so they remain findable.
+Recall resets the clock. Practical upshot: **do not purge memories to save
+space, and do not mark everything canonical to fight fade** (canonical changes
+salience gating at write time, not fade). Use `memory_supersede` for stale
+facts.
+
+---
+
+## 7. Gotchas, in the order they bite
+
+1. **Retrieval flags unset.** §3. Silent, and the largest single effect.
+2. **The decisive identifier sits past character 400.** 97.3% -> 46.8% on the
+   public corpus.
+3. **Terms that exist only in tags.** Invisible to the embedding and (without
+   `AWM_RERANK_TAGS=1`) to the reranker.
+4. **Unpinned agent identity.** Writes vanish into a per-directory UUID space.
+   `memory_whoami`.
+5. **A running MCP connection never reloads code.** Rebuilding AWM on disk has
+   zero effect on a session whose connection already started — a child process
+   keeps the code it loaded at spawn. Restart the session, or reconnect, then
+   confirm with `memory_whoami`. Do not infer the running version from
+   `package.json`.
+6. **Cold start is ~1.5s; warm recall is ~480ms** (measured, k=3, 11k-engram
+   store, `npm run profile:recall`) — and on a genuinely fresh install, after a
+   one-time **~600 MB** model download, because **nothing is bundled**: no ONNX
+   ships in the npm tarball or the MCPB bundle, and all three models fetch lazily
+   into `AWM_CACHE_DIR` > `HF_HOME` > `<packageRoot>/data/models`. The
+   cross-encoder is **83%** of the warm figure, and its first inference is
+   450-670ms of the cold one — so cold start is model load, not a slow store, and
+   it is paid once per process. Never put a cold recall on a latency-critical
+   path. `AWM_RERANKER_DTYPE=q8` cuts total latency **26-33%** on three suites
+   for **one query in 450** of accuracy (re-measured 2026-10-09 on the shipped
+   pipeline: identifier success@1 unchanged at 93.0%, topic 92.2% -> 92.0%;
+   correct silence unmoved on all three suites, success@5 unmoved on both
+   private suites and +0.5pp on the public corpus, inside its 4pp noise floor) and it shrinks the reranker
+   ONNX file it loads from 91 MB to 23 MB. fp32 is still the shipped default:
+   q8 is a documented **latency-first operating mode**, not a hidden tuning
+   flag, and it CHANGES RANKING OUTCOMES rather than being a free speedup. It is
+   read once at module import and the model is then cached, so it needs a
+   PROCESS RESTART — setting it against a running AWM does nothing, and an MCP
+   session must be restarted or reconnected. To check latency on your own store
+   from any install, set `AWM_PROFILE_RECALL=1`; checking ACCURACY needs derived
+   ground truth and therefore a repo checkout, because scripts/ and tests/ are
+   not in the npm tarball. See docs/deployment.md "Operating modes". `q4` is
+   dominated — same accuracy, only -3% latency, 6.1s cold start. See
+   docs/recall-latency.md.
+7. **The embedding model is fixed per store.** Changing `AWM_EMBED_MODEL` or
+   `AWM_EMBED_DIMS` against an existing corpus leaves half the store scoring 0
+   on the vector channel. AWM warns once per process; re-embed the whole store
+   or revert.
+8. **Invocation depends on the harness, not on AWM.** AWM cannot make an agent
+   call it. If the agent is not writing memories, the instructions are the
+   problem, not the store.
+9. **PGlite is single-process.** §4.
+10. **HTTP agent isolation is advisory.** §4E.
+11. **The feedback loop has almost no signal yet** — overwhelmingly
+    `useful=1`, so do not expect `memory_feedback` to be visibly improving
+    ranking today.
+12. **Consolidation summaries are concatenations**, not synthesis. Do not read
+    them as insight.
+13. **The salience filter is tuned for engineering work.** Other domains will
+    need different tuning.
+14. **Schema migrations are additive, not versioned.** Downgrading is not
+    supported.
+
+`docs/known-limitations.md` is the maintained version of this list, with
+evidence for each item and a section of things that are **no longer true**, so
+they are not re-reported. Read it before filing anything.
+
+---
+
+## 8. Troubleshooting
+
+**Nothing is recalled, or the wrong things are.**
+`awm doctor` → are the three flags from §3 set? Then: does the memory's body
+contain the words you are querying with (§2)? Then: are you in the agent space
+that holds it (`memory_whoami`)? Then: reformulate once or twice with the
+domain's nouns rather than generic English. Three empty reformulations means
+the memory probably is not there — go read the code.
+
+**Memories are written but nobody else sees them.** Unpinned agent identity.
+Gotcha 4.
+
+**A code change had no effect.** Gotcha 5. Restart the session.
+
+**"EMBEDDING DIMENSION MISMATCH" in the logs.** Gotcha 7.
+
+**It was working and now the store is empty after an upgrade.** You were on
+<0.15.6 with the store inside the package directory. §4.
+
+Deeper: `docs/troubleshooting.md`, `docs/faq.md`, `docs/unknowns.md`.
+
+---
+
+## 9. Reproducing the measurements
+
+Two benchmark paths, and the difference matters:
+
+- **`npm run bench`** — the published numbers in `docs/benchmarks-current.md`.
+  Runs against a frozen snapshot of a real ~30,000-memory store. **That corpus
+  is private and is not in the repository**, so this command only works for the
+  maintainer. The generators are published; the data is not.
+
+- **`npm run bench:public:build` then `npm run bench:public`** — fully
+  reproducible by anyone. Builds a synthetic corpus from a seeded generator
+  (`tests/realstore-eval/public-corpus.mjs`), derives ground truth with **the
+  same hold-out code** as the private path, and scores with the same runner.
+
+**Mind the noise floor.** Two full builds differing only in corpus seed gave
+`s@1` 56.3% and 52.0% — the corpus *shape* reproduces to 0.2pp and every
+qualitative result holds, but the absolute moves about 4 points between draws.
+A 2pp move is not a result; confirm on a second seed.
+
+**Do not quote public-benchmark numbers as the published ones.** The synthetic
+corpus scores *lower*, because generated prose is more self-similar than real
+prose and same-domain neighbors are harder to separate. Use it for the method
+and for deltas, not for absolutes.
+
+Ground truth is derived by **unique-identifier hold-out**: an identifier that
+appears in exactly one active memory — verified through FTS, the real retrieval
+path — gives a mechanically checkable right answer. Adversarial probes are
+included so that **correct silence scores positively**, which is the opposite
+of what LoCoMo does. `docs/benchmarks.md` explains why LoCoMo was retired.
+
+---
+
+## 10. Further reading
+
+| For | Read |
+|---|---|
+| Deciding whether to adopt | `docs/for-decision-makers.md` |
+| The mechanism, walked through | `docs/walkthrough.md` |
+| Architecture | `docs/architecture.md` |
+| Cognitive model (ACT-R, Hebbian, fade) | `docs/cognitive-model.md` |
+| Recall quality at scale | `docs/using-awm-at-scale.md` |
+| Weaknesses, with evidence | `docs/known-limitations.md` |
+| What we do not know yet | `docs/unknowns.md` |
+| Benchmark method and history | `docs/benchmarks.md` |
+| Current scores, machine-generated | `docs/benchmarks-current.md` |
+| Agent-facing instructions | `AGENTS.md`, `plugin/skills/awm-memory/SKILL.md` |
+| Setup guides | `docs/quickstart.md`, `docs/claude-code-setup.md`, `docs/team-setup-guide.md`, `docs/plugin.md`, `docs/desktop.md`, `docs/deployment.md` |

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "agent-working-memory",
-  "version": "0.15.8",
+  "version": "0.16.0",
+  "mcpName": "io.github.CompleteIdeas/agent-working-memory",
   "description": "Persistent, local-first memory for AI agents. Selective by design: filters what's worth keeping, links what's related, and says nothing when it doesn't know. SQLite + ONNX, no cloud, no API keys.",
   "keywords": [
     "ai-agents",
@@ -53,6 +54,9 @@
     "test:all": "vitest run && tsx tests/mcp-smoke.ts",
     "check:release": "node scripts/check-release.mjs",
     "bench": "node scripts/bench-current.mjs",
+    "bench:public:build": "tsx tests/realstore-eval/build-public-snapshot.ts",
+    "bench:public": "node scripts/bench-public.mjs",
+    "profile:recall": "node scripts/profile-recall.mjs",
     "test:docker": "bash scripts/docker-release-test.sh",
     "test:linux": "bash scripts/docker-release-test.sh linux",
     "test:desktop": "bash scripts/docker-release-test.sh desktop"
@@ -68,6 +72,8 @@
     ".claude-plugin/",
     "package.json",
     "README.md",
+    "AGENTS.md",
+    "llms.txt",
     "LICENSE"
   ],
   "dependencies": {

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "awm",
   "displayName": "Agent Working Memory",
-  "version": "0.15.8",
+  "version": "0.16.0",
   "description": "Persistent, local-first memory for AI agents. Selective by design: filters what's worth keeping, links what's related, and says nothing when it doesn't know. SQLite + ONNX, no cloud, no API keys.",
   "author": {
     "name": "Robert Winter"

package/plugin/README.md

@@ -22,7 +22,7 @@ The launcher defaults `AWM_DB_PATH` to `~/.awm/memory.db` — **the same file
 than quietly starting an empty one. Set `AWM_DB_PATH` yourself to override.
 
 It prefers an installed copy of the package (global, or a local `node_modules`) and falls
-back to `npx -p agent-working-memory@0.15.8`. The npx path rebuilds
+back to `npx -p agent-working-memory@0.16.0`. The npx path rebuilds
 `better-sqlite3` on a cold cache, which is slow enough to look like a hang, so a real
 install is worth having:
 

package/plugin/bin/awm-mcp-launcher.cjs

@@ -6,7 +6,7 @@
 //
 // This is a REAL source file, not a string inside the generator, because it is real code:
 // it gets syntax-checked, linted and tested like everything else. `npm run build:plugin`
-// copies it to plugin/bin/ and substitutes 0.15.8.
+// copies it to plugin/bin/ and substitutes 0.16.0.
 //
 // Two jobs a bare `mcpServers` entry in plugin.json cannot do:
 //
@@ -95,7 +95,7 @@ if (found) {
   const isWin = process.platform === 'win32';
   const child = spawn(
     isWin ? 'npx.cmd' : 'npx',
-    ['-y', '-p', 'agent-working-memory@0.15.8', 'awm', 'mcp'],
+    ['-y', '-p', 'agent-working-memory@0.16.0', 'awm', 'mcp'],
     { stdio: 'inherit', env: process.env, shell: isWin }
   );
   child.on('error', (e) => {

package/plugin/skills/awm-memory/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 
 # Agent Working Memory
 
-Generated from `src/adapters/common.ts` (AWM v0.15.8) — the same guidance
+Generated from `src/adapters/common.ts` (AWM v0.16.0) — the same guidance
 `awm setup` writes into CLAUDE.md. Do not edit here; edit the source and re-run
 `npm run build:plugin`.
 
@@ -40,9 +40,11 @@ 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. **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
+6. **Hooks do the rest.** `awm setup` installs five: a **prime** hook that recalls against
+   each prompt and injects what clears confidence (or nothing), checkpoint hooks on
+   compaction and session end (plus a 15-min timer), a local write/recall reminder on
+   Stop, and a reminder after Bash/PowerShell calls that a data change is not done
+   until it is written. Primed context arrives labeled
    `[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.
@@ -70,9 +72,9 @@ extraction all see most strongly.
   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."
+  will use. `SettlementService.closeRun()` beats "the accounting code."
   `tblMemberDetails.activation_date` beats "the activation column."
-  `schema/072-period-close.sql` beats "the migration."
+  `schema/072-settlement-lock.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.
@@ -89,12 +91,14 @@ extraction all see most strongly.
   Measured on an 11k-engram store: 94% of tagged memories are missing at
   least one of their own topical terms from the body, and 66% of those
   terms never appear in the text at all.
-- **Tags are NOT a substitute for body text.** Only BM25 indexes tags. The
-  embedding is built from `concept + content` and the cross-encoder rerank
-  passage is built from `concept + content` — neither sees tags. So a word
-  that exists only as a tag is invisible to two of the three retrieval
-  channels, including the one that decides final ordering. Tag it *and*
-  write it.
+- **Tags are NOT a substitute for body text.** The embedding is built from
+  `concept + content` only, so it never sees tags. BM25 indexes them. The
+  cross-encoder rerank passage sees ONLY `topic=`/`proj=`/`project=` tags, and
+  only when `AWM_RERANK_TAGS=1` — which `awm setup`, the plugin and the Desktop
+  bundle all switch on, so assume it is on — capped at 80 characters. So a word
+  that exists only as a tag is invisible to the embedding entirely, and
+  invisible to the ranker unless it is one of those three prefixes inside that
+  budget. Tag it *and* write it.
 - **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
@@ -111,6 +115,10 @@ 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.
 
+(“Required” below means *required for good recall* — the MCP schema accepts every
+one of these as optional, so a write without them succeeds and simply retrieves
+worse.)
+
 | Field | Required? | Format | Example |
 |---|---|---|---|
 | `project` | **YES** | one short word matching the current project | `"EquiHub"`, `"AWM"`, `"USEA-Agent"` |
@@ -120,12 +128,12 @@ and entity-bridge boosts at recall time.
 | `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"]` |
+| `tags` | when applicable | extra prefix-tags for IDs and dates | `["ticket=10001", "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
+- `asset=<id>` for a domain record id
 - `usef=<id>` for USEF lookups
 - `date=YYYY-MM-DD` for temporal anchoring (ISO format)
 - `person=<Name>` for stakeholder quotes / decisions
@@ -134,7 +142,7 @@ and entity-bridge boosts at recall time.
 ### Entity index — exact-match recall for named things (default off)
 Structured identifier tags (`ticket=`, `person=`, `horse=`, `member=`, bare 4+ digit
 ids, etc.) feed a dedicated entity inverted index, separate from BM25/embedding scoring.
-A query naming an entity ("ticket 19252", "Kaleigh Collett") can reach the memory through
+A query naming an entity ("ticket 10003", "Dana Whitfield") can reach the memory through
 this index even when the wording doesn't lexically match — it's a deterministic exact
 lookup, immune to vocabulary mismatch. Keep identifier tags exact and consistent for
 this reason, not just for the BM25 boost described above.
@@ -334,14 +342,14 @@ memory_write(
 ```
 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.",
+  content="apps/web/app/(billing)/billing/settlement-lock/page.tsx had client-only BLOCKED enforcement. Fixed by adding server-side check in SettlementService.closeRun() per schema/072-settlement-lock.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"]
+  tags=["ticket=10001", "person=Robert", "date=2026-05-11", "topic=period-close", "topic=security"]
 )
 ```
 
@@ -389,7 +397,7 @@ 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)
-Each optimisation is gated by an env var so it can be disabled for A/B testing if a
+Each optimization 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):
@@ -411,8 +419,13 @@ Recall pipeline:
   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
-  clear-winner queries. Forces every recall through the reranker.
+- `AWM_FEEDBACK_BM25=1` — re-enables Rocchio pseudo-relevance feedback
+  (phase 3.5), a third BM25 pass over the query plus five terms harvested from
+  the top 3 results. Default OFF since 2026-10-09: measured at 6.7–7.0% of every
+  warm recall for no measurable accuracy — 3 gold ranks moved in 950 queries
+  across three suites, two of them the wrong way. On the public corpus — the only
+  suite with recall headroom left — it is inert per query, not just in aggregate:
+  0 of 200 queries differ in rank, top-1 or score.
 - `AWM_DISABLE_EXPANSION_CACHE=1` — disables the query expansion skip
   heuristic + LRU cache. Forces every recall through flan-t5-small.