AgentWorkingMemory (AWM)
Give your AI coding agent a memory that survives the conversation — and knows when to stay quiet.
Every session with an AI assistant starts blank. It has forgotten what your team decided last week, which approach was tried and rejected, and which table actually holds the thing it needs. So it re-derives all of it — reading files, running searches, asking you — and on a large project it will confidently rebuild something that was already decided against.
AWM fixes that with one local process and one SQLite file. The agent writes short notes as it learns; AWM decides which are worth keeping, hands back the two or three that matter when asked, and says nothing when nothing fits.
npm install -g agent-working-memory && awm setup --global
Restart Claude Code. 19 tools appear. No cloud, no API keys, nothing leaves your machine.
What it does, measured
Measured against a frozen copy of a real work store — 29,853 engrams, 11,262 of them retrievable, which is the honest denominator for a retrieval score. Not synthetic data, and not a corpus we can publish: it is a real store with real colleagues and real decisions in it, so it is gitignored and so is everything derived from it.
What you can run: npm run bench:public scores the same runner through the same
ground-truth derivation against a synthetic corpus you rebuild yourself. It verifies the method,
not the figures — a synthetic corpus scores lower. Current numbers, stamped with the commit that
produced them, are in docs/benchmarks-current.md; every claim
below, what produced it, and who can reproduce it is in docs/claims.md,
including the ones we think are weakest.
Two independently built fixtures agree within a point. A warm recall takes about a quarter of a
second (p50 256 ms). Those figures are for memories written the way
docs/writing-memories.md says to — the rules hold for any model
that writes to the store, and the write is where recall quality is decided.
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. 41% of the technical identifiers the agent used had entered the conversation only through a recall.
Is this for you?
The honest version, because the overhead is real and it does not pay back for everyone.
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.
It is also not a chatbot, a generic vector database, or a RAG pipeline over your files.
Get started
npm install -g agent-working-memory
awm setup --global # MCP config, CLAUDE.md guidance, hooks
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:
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. Install the npm package either way.
Requires Node.js 22+. Restart Claude Code.
What to expect. The first conversation takes minutes rather than seconds while three ONNX models download — ~600 MB once, into a local cache (134 MB embedder + 92 MB reranker + 377 MB query expander; nothing is bundled in the package). 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:
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:
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.
Upgrading
npm install -g agent-working-memory@latest
That alone is not enough — it updates the engine, not the wiring. Do the second step for however you installed it:
Then restart Claude Code (or Desktop). A running MCP connection keeps the code it loaded at spawn time, so nothing changes until a fresh session starts.
A plugin marketplace installed from a local directory does not refresh itself. Measured:
a GitHub-sourced marketplace on one machine refreshed on a schedule, while a directory-sourced
one had not moved in 167 days. Since the npm route registers a directory marketplace, the
/plugin marketplace update line above is required, not optional — skip it and you get new
engine code with old hooks, which half-works and is confusing for it.
memory_whoami
reports the version, store and agent the running process actually has. It is the fastest way to confirm an upgrade landed, and the only one that cannot be fooled by a stale cache.
Your memories are not touched by any of this. Every release so far has been backward compatible, and the store is the same SQLite file before and after.
What's new — v0.20.1
Full history, including every benchmark figure that was corrected and why: CHANGELOG.md.
Why it works when a vector store doesn't
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.
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.
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.
The whole thing, one memory followed end to end with every threshold sourced:
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.
The theory and its citations: 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 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. 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.
Reference
The README points outward; it does not duplicate. Everything below is the authoritative source.
Stack: TypeScript · SQLite + FTS5 (or PGlite / Postgres) · Fastify · @modelcontextprotocol/sdk ·
local ONNX via @huggingface/transformers — bge-small-en-v1.5 embeddings, ms-marco-MiniLM cross-encoder,
flan-t5-small expansion. Node 22+.
npx vitest run # 1097 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
Status
Active development, v0.20.1. 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.
Release notes, and every benchmark correction recorded against the release that made it: CHANGELOG.md.