Agent memory that isn't a vector database cope

For two years the default answer to agent memory was "embed everything and pray". I tried it. My agent confidently retrieved a grocery list into a deployment plan. We need to talk about what replaced it.

The providers finally made memory a platform feature instead of a weekend project. Anthropic's memory tool gives the model file operations against a directory you control: it writes its own notes, reads them next session, and the files live in your infrastructure. Paired with context editing, which clears stale tool results as the window fills, Anthropic's own 100-turn benchmark showed 84 percent token savings and a 39 percent performance bump. Those are vendor numbers, so apply salt, but the direction matches what I see in practice.

the pattern that works

Two tiers, boring on purpose:

• Inside the window: recent turns, current task state, and nothing else. Context editing or compaction keeps it that way.
• Outside the window: durable facts as files with names a model can guess ("deploy-checklist.md", not "mem_0492"). The agent reads what it needs when it needs it.

The file tier beats embeddings for agent memory because agents need exact recall of specific decisions, not fuzzy similarity to them. "What port did we pick" has one right answer. Cosine distance has opinions.

what the agent actually writes, left alone

Nobody tells you what the files look like after a month, so here is mine. The agent's memory directory converged on four kinds of files: checklists it consults before repeating a task, decision records with the reasoning attached ("we picked port 8443 because 8080 collides with the proxy"), a preferences file about me that is frankly a little too accurate, and a graveyard of notes it wrote once and never read again.

That last category matters. Around 40 percent of what my agent wrote was write-only. The fix was embarrassing: I added one line to the system prompt telling it to record why a note will be needed, not just what happened. Write-only memory dropped by half. Turns out the model has the same problem I have with my own notebook, and the same cure.

The other habit worth forcing early: filenames are an index, and the model treats them that way. When it names files itself you get "notes-2026-07-03.md", which is a diary. When you constrain names to topic slugs you get "stripe-webhook-gotchas.md", which is a database. One is read on demand. The other is read never.

compaction is a lossy codec, tune it

Context editing clears dead tool results, and compaction summarizes the rest when the window fills. Both are lossy, and the loss is not uniform. My rule after burning a week on it: task state compresses fine, decisions compress badly. A summary happily turns "we tried approach A, it corrupted the migration, do not retry it" into "explored several approaches", and the agent cheerfully retries A an hour later.

So the pattern that survives: before compaction eats the turn history, anything with the shape of a decision goes to a file. Files are exempt from the codec. The window is for thinking; the directory is for knowing. If a fact would hurt to lose, it does not belong exclusively to a context window whose whole job is to forget.

the anti-pattern that refuses to die

Stuffing the entire session summary back into the system prompt every turn. It grows without bound, it poisons the cache prefix (see my caching piece), and the model attends to none of it. Summaries are for handoffs, not for heartbeats.

The runner-up anti-pattern: one shared memory directory for a fleet of agents with different jobs. The support agent starts citing the deploy agent's rollback notes to customers. Memory is scoped like any other state, per agent role, shared only through files you deliberately place in both scopes. Two agents sharing a diary works exactly as well as it does for people.

Graph memory is the ambitious cousin of all this, and the best working example I know of is in one of the portfolios I reviewed in December, running a home assistant. Ambition scales down badly though; start with files.

Vector search still earns its keep for retrieval over corpora. Just stop asking it to be a diary.

a starter kit, if you are building this week

Give the agent a directory and three standing instructions: read the index file before starting, write decisions with their reasons, and prune anything it has not read in twenty sessions. Add one index file the agent maintains itself, one line per file, because a directory listing is not a table of contents. Cap the directory at something small enough to fit in a single read, mine is 40 files, and make the agent consolidate when it hits the cap. Consolidation is where the magic quietly happens; forced to merge five stale notes into one, the model writes the summary it should have written the first time.

Then leave it alone for a month and read what accumulated. The directory is the most honest eval of your agent you will ever get: it is what the model thought was worth remembering about working for you. Mine included the note "user says 'quick question' before the hard ones". No benchmark tells you that.