agent-working-memory 0.14.5 → 0.15.4

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "agent-working-memory",
+  "description": "Agent Working Memory — persistent, local-first memory for AI agents",
+  "owner": {
+    "name": "Robert Winter",
+    "url": "https://github.com/CompleteIdeas"
+  },
+  "plugins": [
+    {
+      "name": "awm",
+      "description": "Persistent local memory: 19 MCP tools, session hooks that checkpoint and prime, and the usage guidance as a skill. Shares ~/.awm/memory.db with an `awm setup` install.",
+      "source": "./plugin",
+      "category": "development",
+      "keywords": ["memory", "mcp", "recall", "agent", "local-first"]
+    }
+  ]
+}

package/README.md

@@ -27,89 +27,54 @@ Restart Claude Code. 19 tools appear. No cloud, no API keys, nothing leaves your
 
 ## What it does, measured
 
-Every number below is reproducible from this repository against a frozen copy of a **real
-30,000-memory store** — not synthetic test data. Method and corrections: [`docs/benchmarks.md`](docs/benchmarks.md).
+Reproducible from this repository against a frozen copy of a **real 30,000-memory store**, not
+synthetic data. Current numbers, stamped with the commit that produced them:
+[`docs/benchmarks-current.md`](docs/benchmarks-current.md).
 
 | | |
 |---|---|
-| **Returns the right memory first** | **92.7%** of identifier queries · **92.0%** of topic queries · ~97% in the top five |
-| **Stays silent when it should** | **90%** correct abstention on questions about facts never stored |
-| **Halves the digging** | Same agent, same tools, four real support tickets: with memory, **2× the specific facts** the real answer needed and **half the database queries** (49 vs 100). On one ticket the memoryless arm ran 25 queries, exhausted its budget and answered nothing; the memory arm answered in 4. |
-| **Holds decisions for months** | On a six-month application project, recorded decisions were recalled a median of **30 days** after being written — some after **167 days**. 41% of the technical identifiers the agent used had entered the conversation *only* through a recall. |
-| **Costs a fraction to answer** | Scoped recall answers in **~630 tokens flat** regardless of store size. Carrying the memory store instead: ~1.3M tokens. Reading the codebase: doesn't fit in any window. |
-| **Lets a cheap model punch up** | A small model plus AWM out-performed a frontier model on a 15-task domain workload at **~1/40th the cost** — **14/15 vs 7/15**, $0.007 vs $0.277 per task. |
+| **Returns the right memory first** | **92.7%** of identifier queries · **92.0%** of topic queries · **96.7%** in the top five |
+| **Stays silent when it should** | **90.0%** correct abstention on questions about facts never stored |
+| **Costs the same at any scale** | Scoped recall answers in **~630 tokens flat**. Carrying the store instead: ~1.3M tokens |
+| **Lets a cheap model punch up** | Small model + AWM beat a frontier model on a 15-task domain workload: **14/15 vs 7/15**, at ~1/40th the cost |
 
 Two independently built fixtures agree within a point. Warm recall takes about half a second.
 
 <details>
-<summary><b>How these numbers were corrected upward in September 2026</b> — read before comparing to older figures</summary>
-
-Earlier published figures (s@1 63.8% category, 70.0% identifier) were **understated by the
-measuring instrument, not the engine**. Two defects, both found and fixed in 0.14.4–0.14.5: the
-benchmark's decay clock ran on the wall clock, so the "frozen" snapshot aged a day per day; and the
-runner queried every gold as the `work` agent while a quarter to a third belonged to `personal`,
-so agent isolation cut them before scoring. Nothing in retrieval changed between 63.8 and 92.0.
-The within-day *deltas* published earlier (e.g. the +7.4pp tags win) stand. Full account in
-[`docs/benchmarks.md`](docs/benchmarks.md) → correction notes.
-</details>
-
----
-
-## Why it works when a vector store doesn't
+<summary>Two more, from real work rather than fixtures</summary>
 
-Most "memory for AI" stores everything and retrieves by similarity. AWM makes the opposite bet:
-**a memory is only useful if it is selective.**
-
-**It refuses most of what it sees.** Every write is scored for importance before storage —
-is it new, is it a decision or a root cause, does it name its subject? About a third of what
-the agent offers is kept at full confidence. The rest never competes, so recall stays sharp as
-the store grows.
+**Halves the digging.** Same agent, same tools, four real support tickets: with memory, 2× the
+specific facts the real answer needed and half the database queries (49 vs 100). On one ticket
+the memoryless arm ran 25 queries, exhausted its budget and answered nothing; the memory arm
+answered in 4.
 
-**It forgets gracefully.** Memories that keep getting used stay strong; ones nobody touches
-fade from ranking without being deleted. The model is borrowed from cognitive science (ACT-R),
-and it means no one curates the store.
-
-**It tells you when it doesn't know.** When the top candidates are only marginally better than
-the tenth, AWM returns nothing and says how many it withheld. A confident wrong memory is more
-expensive than an admitted gap — the benchmark scores the silence as a win.
+**Holds decisions for months.** On a six-month application project, recorded decisions were
+recalled a median of 30 days after being written — some after 167. 41% of the technical
+identifiers the agent used had entered the conversation *only* through a recall.
+</details>
 
-**It knows what changed.** When a fact is corrected, the old memory is marked superseded and
-carries a visible warning if it ever surfaces. A notes file has two paragraphs that read with
-equal confidence; AWM knows which one won. One project has 108 such supersessions — an agent
-resuming it gets one current state, not five.
+---
 
-**It stays local and per-person.** One SQLite file, three small ONNX models (~200 MB, once).
-Work and personal memories are separate pools; several sessions share a pool safely.
+## Is this for you?
 
-<details>
-<summary>Against a typical RAG / vector store, feature by feature</summary>
+The honest version, because the overhead is real and it does not pay back for everyone.
 
-| | Typical vector store | AWM |
+| If you are… | What you actually get | It pays back when |
 |---|---|---|
-| Storage | Everything | Salience-filtered: active / staging / low-confidence fallback |
-| Retrieval | Cosine similarity | Keyword + vector candidates → liveness scoring → cross-encoder rerank → abstention gate |
-| Forgetting | Manual cleanup | ACT-R decay; reinforced knowledge persists |
-| Correction | Delete and re-insert | Supersede with a visible pointer; retract with confidence propagation to neighbours |
-| Duplicates | Stored again | Reinforce the existing memory instead |
-| Wrong answers | Best of a bad set | Returns nothing, says why |
-| Named things | Vocabulary-dependent | Entity index on tickets, people, tables, files |
-| Feedback | None | Useful / not-useful adjusts confidence and rank |
-| Multi-agent | Per-instance | Shared store, per-agent scoping, opt-in shared workspace |
-</details>
-
----
-
-## Who uses it
+| **A solo developer on one long-lived project** | The agent stops re-asking what you already told it, and stops re-proposing approaches you rejected | The project outgrows the context window — roughly, when you start saying "I have explained this before" |
+| **A team sharing conventions** | One pool where a decision written by anyone is recalled by everyone, with corrections superseding rather than accumulating | More than one person is steering agents at the same codebase |
+| **Running support or operations agents** | Ticket-scoped recall by real identifiers, so the second agent to touch a ticket knows what the first one did | Work arrives as a queue that several sessions or people share |
+| **Building multi-agent pipelines** | A shared substrate with per-agent scoping, so specialists cooperate without sharing one context window | You have specialised agents that need the same facts |
+| **Cost-constrained** | A small local model with good recall beats a frontier model without it on domain work | Your workload is narrow and repetitive rather than novel each time |
+| **Somewhere cloud memory is not allowed** | One SQLite file on the machine. No account, no telemetry, no egress | Compliance makes hosted memory a non-starter |
 
-- **Long-running coding agents** that need cross-session project knowledge
-- **Support and operations agents** that must remember what was already decided on a ticket
-- **Multi-agent pipelines** where specialised agents share one memory
-- **Local-first teams** for whom cloud memory is not acceptable
-- **Any MCP host** — Claude Code, [Hermes Agent](docs/integrations/hermes.md), or your own agent over a local HTTP API
+**Skip it if:** your tasks are short and one-off with nothing worth reusing; you want a hosted
+service someone else operates; you need memory synced across machines out of the box; or you were
+hoping to replace your code, tickets and docs as the source of truth. AWM is a fast path back to
+what was already decided — recall first, verify against the source when it matters, supersede when
+reality differs.
 
-**Not** a chatbot, a hosted service, a generic vector database, or a replacement for your
-code and tickets as the source of truth. Recall first; verify against the source when it
-matters; supersede when reality differs.
+It is also **not** a chatbot, a generic vector database, or a RAG pipeline over your files.
 
 ---
 
@@ -120,94 +85,131 @@ npm install -g agent-working-memory
 awm setup --global          # MCP config, CLAUDE.md guidance, hooks
 ```
 
-Requires **Node.js 22+**. Restart Claude Code; the first conversation is ~30 s slower while the
-models download. Upgrading is the same two commands — the database is preserved and every
-release to date has been backward compatible.
+Or install it as a Claude Code plugin instead, which wires the same things without a setup
+step. The npm package carries the plugin, so this needs no GitHub access:
 
-Starting on an existing project? Warm-start the store from its own docs so recall is useful
-on day one:
+```bash
+awm plugin                  # prints the two lines to paste, with the path on your machine
+```
+
+Both share one store at `~/.awm/memory.db`, so it is a preference, not a fork — the
+trade-offs are in [`docs/plugin.md`](docs/plugin.md). Install the npm package either way.
+
+Requires **Node.js 22+**. Restart Claude Code.
+
+**What to expect.** The first conversation is ~30 s slower while three small ONNX models download
+(~200 MB, once). After that the agent has 19 memory tools, and the hooks save state on compaction
+and session end without you doing anything. For the first day or two recall will be thin — it only
+knows what has been written. That is the normal shape of it, not a fault.
+
+**Starting on an existing project?** Warm-start the store from its own docs so recall is useful on
+day one:
 
 ```bash
 awm onboard ./docs --repo . --project <name>    # review the pack, then
 awm import <pack> --db <path> --dedupe
 ```
 
+**Turn on the three retrieval improvements.** They ship default-off and belong together:
+
+```bash
+AWM_RERANK2=1 AWM_RERANK_WINDOW=query AWM_RERANK_TAGS=1
+```
+
+Second-stage rerank by the cross-encoder's own score; a 400-character rerank window placed on the
+densest query-term region rather than the prefix (**25% → 87.5%** on long memories); and tags fed
+into the rerank passage (**+7.4pp**). `awm setup` writes them on a fresh install. `memory_whoami`
+prints the active fingerprint so you can confirm a running process has them.
+
+**Check it worked:** `awm doctor claude-code` reports the live sidecars, which agent each serves,
+and whether anything needs a re-run of setup.
+
 | Next | |
 |---|---|
 | Install, first write, first recall | [`docs/quickstart.md`](docs/quickstart.md) |
 | Separate pools per project, incognito mode, hooks | [`docs/claude-code-setup.md`](docs/claude-code-setup.md) |
+| As a Claude Code plugin | [`docs/plugin.md`](docs/plugin.md) |
+| In Claude Desktop | [`docs/desktop.md`](docs/desktop.md) |
 | Teams and multi-agent | [`docs/team-setup-guide.md`](docs/team-setup-guide.md) |
 | Custom agents over HTTP | [`docs/reference.md`](docs/reference.md) |
 
 ---
 
-## Recommended configuration
+## Why it works when a vector store doesn't
 
-Three retrieval improvements ship default-off and should be enabled **together**:
+Most "memory for AI" stores everything and retrieves by similarity. AWM makes the opposite bet:
+**a memory is only useful if it is selective.**
 
-```bash
-AWM_RERANK2=1 AWM_RERANK_WINDOW=query AWM_RERANK_TAGS=1
-```
+**It refuses most of what it sees.** Every write is scored for importance before storage — is it
+new, is it a decision or a root cause, does it name its subject? About a third of what the agent
+offers is kept at full confidence. The rest never competes, so recall stays sharp as the store
+grows.
+
+**It forgets gracefully.** Memories that keep getting used stay strong; ones nobody touches fade
+from ranking without being deleted. The model is borrowed from cognitive science (ACT-R), and it
+means no one curates the store.
+
+**It tells you when it doesn't know.** When the top candidates are only marginally better than the
+tenth, AWM returns nothing and says how many it withheld. A confident wrong memory is more
+expensive than an admitted gap — the benchmark scores the silence as a win.
+
+**It knows what changed.** When a fact is corrected, the old memory is marked superseded and
+carries a visible warning if it ever surfaces. A notes file has two paragraphs that read with equal
+confidence; AWM knows which one won. One project has 108 such supersessions — an agent resuming it
+gets one current state, not five.
+
+**It stays local and per-person.** One SQLite file, three small ONNX models. Work and personal
+memories are separate pools; several sessions share a pool safely.
+
+<details>
+<summary>Against a typical RAG / vector store, feature by feature</summary>
 
-Second-stage rerank by the cross-encoder's own score; a 400-character rerank window placed on
-the densest query-term region rather than the prefix (**25% → 87.5%** on long memories); and
-tags fed into the rerank passage (**+7.4pp**). `memory_whoami` prints the active fingerprint so
-you can confirm a running process actually has them. Every other variable, with its measured
-effect and the experiments that were rejected: [`docs/reference.md`](docs/reference.md).
+| | Typical vector store | AWM |
+|---|---|---|
+| Storage | Everything | Salience-filtered: active / staging / low-confidence fallback |
+| Retrieval | Cosine similarity | Keyword + vector candidates → liveness scoring → cross-encoder rerank → abstention gate |
+| Forgetting | Manual cleanup | ACT-R decay; reinforced knowledge persists |
+| Correction | Delete and re-insert | Supersede with a visible pointer; retract with confidence propagation to neighbours |
+| Duplicates | Stored again | Reinforce the existing memory instead |
+| Wrong answers | Best of a bad set | Returns nothing, says why |
+| Named things | Vocabulary-dependent | Entity index on tickets, people, tables, files |
+| Feedback | None | Useful / not-useful adjusts confidence and rank |
+| Multi-agent | Per-instance | Shared store, per-agent scoping, opt-in shared workspace |
+</details>
 
 ---
 
 ## How it works, in one paragraph
 
-A write is scored for salience — novelty against the existing store, event type, whether it
-names identifiers — and lands active, staged, or low-confidence. A recall casts a wide net with
-keyword and vector search, scores each candidate for relevance and liveness, lets linked
-memories vote, hands the shortlist to a cross-encoder that actually reads the text, then checks
-whether the score distribution justifies answering at all. A maintenance pass on session end
-clusters, decays unused links, and archives what has gone cold. Corrections supersede rather
-than overwrite.
+A write is scored for salience — novelty against the existing store, event type, whether it names
+identifiers — and lands active, staged, or low-confidence. A recall casts a wide net with keyword
+and vector search, scores each candidate for relevance and liveness, lets linked memories vote,
+hands the shortlist to a cross-encoder that actually reads the text, then checks whether the score
+distribution justifies answering at all. A maintenance pass on session end clusters, decays unused
+links, and archives what has gone cold. Corrections supersede rather than overwrite.
 
 The whole thing, one memory followed end to end with every threshold sourced:
-[`docs/walkthrough.md`](docs/walkthrough.md). The pipeline internals for engineers, with the
-attribution study behind the defaults: [`pipeline-walkthrough.html`](https://completeideas.github.io/agent-working-memory/pipeline-walkthrough.html).
+[`docs/walkthrough.md`](docs/walkthrough.md). The mental model an engineer needs to predict its
+behaviour — proposers, deciders, and when it stays silent:
+[`How AWM decides what to say`](https://completeideas.github.io/agent-working-memory/pipeline-walkthrough.html).
 The theory and its citations: [`docs/cognitive-model.md`](docs/cognitive-model.md).
 
 ---
 
 ## Honest limits
 
-- No help on small one-off tasks — the overhead pays back when knowledge is reused or the
-  project outgrows the context window.
-- Recall is bounded by what was written. A memory that never names its subject can't be found
-  by it. The writing guidance exists for this reason.
+- No help on small one-off tasks — the overhead pays back when knowledge is reused or the project
+  outgrows the context window.
+- Recall is bounded by what was written. A memory that never names its subject cannot be found by
+  it. The writing guidance exists for this reason.
 - The association graph, as of this release, rarely changes a final answer; the reranker does.
-- It is 0.x, and it says so: the benchmark was corrected three times this month when the
-  instrument turned out to be wrong. The corrections are documented in place, not revised away.
+- It is 0.x. Benchmark figures have been corrected upward more than once after the *instrument*
+  turned out to be wrong; every correction is documented in place rather than revised away.
 
 Everything else, with evidence and workarounds: [`docs/known-limitations.md`](docs/known-limitations.md).
 
 ---
 
-## What's new — v0.14.5
-
-Nothing in the retrieval engine changed in the last four point releases; what changed is how it
-is measured, invoked, and reports on itself.
-
-- **Benchmark instrument corrected twice; real numbers are higher.** Identifier s@1 92.7%,
-  category 92.0%, abstention unchanged at 90%. The runner now pins its clock and queries as each
-  gold's own agent.
-- **Feedback joins to its recall.** `memory_recall` ends with `[recall_id: …]`;
-  `memory_feedback` accepts it. Before this every feedback row in the live store was orphaned.
-  `memory_stats` now reports outcome numbers instead of activity counters.
-- **One hook sidecar per session.** Each session's process binds the first free port from 8401
-  upward; `memory_whoami` reports the port it actually holds.
-- **An empty recall no longer claims absence.** `RECALL ABSTAINED` with the withheld count,
-  instead of "No relevant memories found."
-
-Full history back to v0.6.0: [CHANGELOG.md](CHANGELOG.md).
-
----
-
 ## Reference
 
 The README points outward; it does not duplicate. Everything below is the authoritative source.
@@ -216,7 +218,8 @@ The README points outward; it does not duplicate. Everything below is the author
 |---|---|
 | **All 19 MCP tools**, every HTTP endpoint with schemas, every environment variable with its measured effect | [`docs/reference.md`](docs/reference.md) |
 | Architecture, pipelines, schema, backends (SQLite · PGlite · Postgres) | [`docs/architecture.md`](docs/architecture.md) · [`docs/pglite-feature-parity.md`](docs/pglite-feature-parity.md) |
-| Every eval suite — what it measures, how to run it, and how each number was corrected | [`docs/benchmarks.md`](docs/benchmarks.md) |
+| Current benchmark numbers, generated and stamped | [`docs/benchmarks-current.md`](docs/benchmarks-current.md) |
+| What each eval suite measures, and the measurement caveats | [`docs/benchmarks.md`](docs/benchmarks.md) |
 | Building an agent on AWM as a substrate (PRIME → ACT → VERIFY → LEARN) | [`docs/patterns/awm-native-harness.md`](docs/patterns/awm-native-harness.md) · [agent playbook](https://completeideas.github.io/agent-working-memory/awm-for-agents.html) |
 | Running it as a service; backup, restore, migration | [`docs/deployment.md`](docs/deployment.md) |
 | Behaviour as the store grows | [`docs/using-awm-at-scale.md`](docs/using-awm-at-scale.md) |
@@ -229,16 +232,22 @@ local ONNX via `@huggingface/transformers` — bge-small-en-v1.5 embeddings, ms-
 flan-t5-small expansion. Node 22+.
 
 ```bash
-npx vitest run          # 737 tests
-npm run eval            # benchmark suites
+npx vitest run          # 781 tests
+npm run bench           # benchmark suites
+npm run build:plugin    # regenerate the Claude Code plugin from src/
+npm run test:docker     # clean-room install of the packed tarball
+npm run test:linux      # build + full suite on Linux (781/781)
 ```
 
 ---
 
 ## Status
 
-Active development, v0.14.5. Core retrieval, consolidation, MCP integration, hooks, task
+Active development, v0.15.4. Core retrieval, consolidation, MCP integration, hooks, task
 management, and the HTTP API are stable and in daily production use. PGlite backend stable;
-networked Postgres experimental. Real-store benchmark replaces LoCoMo as of 0.13.x.
+networked Postgres experimental.
+
+Release notes, and every benchmark correction recorded against the release that made it:
+[CHANGELOG.md](CHANGELOG.md).
 
 **License:** Apache 2.0 — [LICENSE](LICENSE) · [NOTICE](NOTICE)

package/dist/adapters/claude-code.d.ts

@@ -1,4 +1,13 @@
 import type { CLIAdapter } from './types.js';
+/**
+ * DB-mutation reminder hook (PostToolUse on Bash|PowerShell).
+ * Fires when a shell command runs sqlcmd/mysql/psql with mutation keywords and
+ * injects a reminder that the mutation must be recorded via memory_write.
+ * Origin: 2026-07-29 tblOSCMPImportDivisionMatch incident — an unrecorded
+ * script INSERT broke a production upload six days later, and no recall could
+ * surface a cause that was never written.
+ */
+export declare const DB_MUTATION_HOOK_SCRIPT = "#!/usr/bin/env node\n// AWM DB-mutation reminder hook (PostToolUse on Bash|PowerShell). Installed by awm setup.\nlet raw = '';\nprocess.stdin.on('data', (d) => (raw += d));\nprocess.stdin.on('end', () => {\n  try {\n    const j = JSON.parse(raw || '{}');\n    const cmd = (j.tool_input && j.tool_input.command) || '';\n    const isDbClient = /\\b(sqlcmd|mysql|psql)\\b/i.test(cmd) || /(sqlcmd|mysql|psql)\\.exe/i.test(cmd);\n    const isMutation = /\\b(INSERT|UPDATE|DELETE|ALTER|TRUNCATE|DROP|MERGE)\\b/i.test(cmd);\n    if (isDbClient && isMutation) {\n      console.log(JSON.stringify({\n        hookSpecificOutput: {\n          hookEventName: 'PostToolUse',\n          additionalContext:\n            'AWM REMINDER: this command contains a production DB mutation (INSERT/UPDATE/DELETE/ALTER/DROP/TRUNCATE/MERGE). ' +\n            'The change is NOT complete until it is recorded: call memory_write NOW with the table, what changed, row counts, date, and why ' +\n            '(memory_class canonical if other agents must recall it), and confirm a rollback/backup exists. ' +\n            'If the keywords were only in a string/comment or on temp tables (#...), no write is needed.',\n        },\n      }));\n    }\n  } catch (e) { /* never block the tool result */ }\n  process.exit(0);\n});\n";
 declare const adapter: CLIAdapter;
 export default adapter;
 //# sourceMappingURL=claude-code.d.ts.map

package/dist/adapters/claude-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAkC,MAAM,YAAY,CAAC;AAsC7E,QAAA,MAAM,OAAO,EAAE,UAoOd,CAAC;AAEF,eAAe,OAAO,CAAC"}
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAkC,MAAM,YAAY,CAAC;AAK7E;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,sxCAyBnC,CAAC;AAkEF,QAAA,MAAM,OAAO,EAAE,UAoQd,CAAC;AAEF,eAAe,OAAO,CAAC"}