AgentWorkingMemory MCP server

AgentWorkingMemory (AWM)

Your AI agent forgets. AWM gives it a memory that finds the right fact, knows which version is current, and says when it doesn't know. It runs entirely on your machine, and one command teaches it a whole project.

Every session with an AI assistant starts blank, and every long one decays: the context window fills, compaction summarises the detail away, and by the time you come back to a job its facts are gone. So the agent re-derives everything. It reads files again, re-runs searches and asks you again, and on a large project it confidently rebuilds something that was already decided against. That is where your time and your tokens go.

AWM fixes that at the source. The agent's context is drawn fresh from memory at every turn: a recall primed on each prompt and after every compaction, which returns the two or three memories that matter and nothing when nothing fits. On a real 30,000-memory work store it puts the right memory first for 96% of topic questions and 93% of identifier lookups. A corrected fact replaces the old one instead of competing with it. And with /awm-learn the agent reads an entire repo, manuscript or docs folder into memory, so recall is useful on day one, not day ten. One local process, one SQLite file, no cloud, no API keys, no telemetry, and every number above is published with how to check it.

Why use it

		Evidence
One thread, any number of topics	Context comes from memory each turn, so a single long-running agent can switch topics, lose detail to compaction, and get it back	Early: in a measured multi-task run, compaction + AWM was fully right 4 of 5 times — above the full-history ceiling (3/5) and every memory-less arm. AWM's own share is not yet isolated; what would settle it
Knows what's current	A corrected fact supersedes the old one, and recall serves the new version — the old one surfaces only with a warning	Measured: plain keyword search over a raw store returns a superseded memory first 8–15% of the time; AWM's lifecycle is why it doesn't
Knows what it doesn't know	A gate calibrated on the store itself withholds answers it doesn't have, and flags the ones it isn't sure of	Measured, one store: withholds 58 of 73 never-stored facts and 1 of 712 correct answers on keyword-shaped questions; on natural-language questions it withholds 10 of 97 correct answers once memories carry questions (opt-in, details)
Learns a project in one command	/awm-learn reads a repo or folder into memory, map first, then every part, and resumes where it stopped. Refresh re-learns only what changed	One run, measured: a 374-file production API learned by 5 agents in about 10 minutes, 344 memories, 12 of 20 newcomer questions answered in the top 3 — short of its own 80% target, and its token estimate ran 2.5× low (details)
Selective, not a sponge	It keeps what is worth keeping and returns the two or three memories that matter, not the top-K of everything	By design; the salience filter and its audit are in docs/cognitive-model.md
Less digging, fewer tokens	The agent recalls where the answer is instead of searching for it again	One controlled test, four real support tickets with and without AWM: half the lookups (49 vs 100), 26% fewer output tokens, and 2× the facts the answer needed — n = 4, directional (claims §5)
Costs the same at any scale	A scoped recall costs about the same whether the store holds a hundred memories or thirty thousand	Measured as flat; the size is disputed — published as ~630 tokens, the harness measures ~1,518. Either way against ~1.3M to carry the store (claims §3)
Lets a cheap model punch up	A small model with the right memory beats a frontier model without it on domain work	One experiment: 14/15 vs 7/15 on a 15-task workload, at ~1/40th the cost — n = 15, not reproducible (claims §4)
Keeps secrets out — or keeps them safely	Credentials are masked before anything is stored; with the vault on, AWM keeps them sealed and can use one in a command without ever saying it	Measured: 0 of 40 sealed values left anywhere in a migrated real store (redaction, vault)
Yours, on your machine	No cloud, no account, no API keys, no telemetry	One process, one SQLite file

npm install -g agent-working-memory && awm setup --global

Restart Claude Code. 20 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.

Finds the right memory	In the top five for 98.7% of identifier queries and 98.7% of topic queries — and first for 93.3% and 96.0%. A recall returns three by default, so the top-five figure is what the agent gets; the first-result figure is what the ranker is held to. Baselines on the same questions: plain keyword search (BM25) puts the right memory first for 95.7% / 91.6% — ahead of AWM on identifier lookups, behind it on topic questions. These fixtures are keyword-friendly by construction. On natural-language questions (194, phrased the way a person asks) AWM puts the right memory first for 47.9%, ahead of fused BM25 + vector search (45.4%) and plain BM25 (42.8%) on the same questions — and 52.6% once memories carry the questions they answer (new in 0.22). Over the raw store, with superseded and retracted memories still in it, BM25 falls to 87.7% / 79.8% on the keyword fixtures and returns an outdated memory first 8–15% of the time; AWM's lifecycle is what it adds there
Stays silent when it should	With the opt-in calibrated gate (AWM_ABSTAIN_GATE=calibrated), withholds 58 of 73 questions about facts never stored, while withholding 1 of 712 correct answers to keyword-shaped questions. Natural-language questions get their own model once a quarter of the store's memories carry questions: it withholds 10 of 97 correct natural answers (was 21 of 88 in 0.21), at the price of answering more questions whose fact was deleted. The gate learns its noise floor from the store itself; how it works and what it costs. Off (the default), AWM answers almost every question with its nearest match.
Costs the same at any scale	Scoped recall stays flat as the store grows — published as ~630 tokens, measured by the harness at ~1,518 (claims §3 explains the gap). Carrying the store instead: ~1.3M tokens
Keeps secrets out	On by default: credentials are masked before store, index, embedding or log. A read-only scan of the real store found them in ~70 memories written before this existed — exactly what it now stops. With the opt-in vault, a migration of a copy of that store sealed 40 distinct values and left 0 anywhere in the file, with recall unchanged (same first result for 8 of 8 test questions)
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. A warm recall takes under half a second on the 30k-memory store (p50 375–438 ms, benchmarks); smaller stores are faster. 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, and spends fewer tokens doing it. Same agent, same model, same tools, four real support tickets, with and without memory:

	with AWM	without
File and database lookups	49	100	−51%
Database queries	47	79	−41%
Output tokens	73.7k	99.0k	−26%
Facts the real answer needed, found (of 28, listed before the run)	16	7	57% vs 25%

On one ticket the memoryless arm exhausted its budget and answered nothing. Leaving that ticket out, memory still meant 40% fewer lookups, 20% fewer database queries, 16% fewer output tokens and 22 points more of the facts found. Four tickets is a small sample — directional, not a rate (claims §5).

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.

If you are…	What you actually get	It pays back when
Running one long agent thread across many topics	Context re-drawn from memory each turn, so switching jobs and compaction cost little and the agent comes back to where it was	Your sessions run for hours or days and cover more than one project
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

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 the ONNX models download — ~175 MB once, into a local cache (134 MB embedder + 23 MB keyword reranker + 17 MB natural-language reranker; nothing is bundled in the package, and the 377 MB query expander downloads only if you turn expansion on). After that the agent has 20 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? Ask the agent to learn it: type /awm-learn in Claude Code. It prices the run, asks what to leave out, and reads the project into memory; run it again later to refresh what changed (how it works). Or warm-start the store from its docs without an agent:

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.

Next
Install, first write, first recall	docs/quickstart.md
Separate pools per project, incognito mode, hooks	docs/claude-code-setup.md
As a Claude Code plugin	docs/plugin.md
In Claude Desktop	docs/desktop.md
Teams and multi-agent	docs/team-setup-guide.md
Custom agents over HTTP	docs/reference.md

---

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:

Installed as	Second step
CLI (awm setup)	awm setup --global again. It upgrades in place: your database, agent id, ports and any env you set are all preserved
Claude Code plugin	/plugin marketplace update agent-working-memory then /plugin install awm@agent-working-memory
Claude Desktop	Rebuild the .mcpb and re-install 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.

---