Memory is a directory, not a mystery

Three different things share one word

When somebody says an agent needs memory, ask which of these they mean, because the engineering is completely different.

1. Within a run. Keeping track across twenty steps, when the transcript is being compacted.
2. Across runs, about an entity. This customer prefers Hindi; this repository uses tabs; this supplier always sends PDFs.
3. Across runs, over past conversations. Search over everything that was ever said.

The first two are ordinary engineering and they work. The third is the one people mean and the one that disappoints.

Within a run: write it down

The strongest and least glamorous technique in agent engineering is a file.

Have the agent maintain plan.md and notes.md in its working directory, re-read them at the start of each step, and update them as it goes. Compaction destroys context; it does not destroy a file. An agent that wrote down the API has no refund endpoint, use credits instead on step three still knows that on step nineteen.

It also gives you something to read. A plan file is a window into what the agent believes it is doing, in language a person can check, at a moment when the transcript is too long to read.

Across runs about an entity: a table with fields you chose

Do not let a model decide freely what is worth remembering. Do that and after a month you have four hundred rows of trivia, half of which contradict each other, and no way to know which one gets used.

Pick the fields:

CREATE TABLE account_memory (
  account_id   text primary key,
  language     text,
  timezone     text,
  billing_note text,
  updated_at   timestamptz not null default now()
);

Five columns you can inspect, correct, show to the customer, and delete. That last one is not a detail: if somebody exercises a right to have their data deleted, you can honour it for a table. You cannot honour it for facts smeared across a vector index and half-remembered inside old transcripts.

Across past conversations: the honest position

Semantic search over old chats returns what is similar, not what is relevant: those come apart badly here. A near-duplicate of a question you once answered wrongly scores extremely well, and now yesterday’s mistake is today’s authority.

If you do it anyway, two mitigations earn their keep. Store the outcome alongside the transcript so you can retrieve only from runs that succeeded. And store a written-at date with every remembered fact, and put that date in the context, because nothing in an index knows that a price changed in March.

Staleness has no expiry date

This is the failure mode that ships to production and stays there. A stored fact never notices the world moved. Fixes, in order of cost: a date on everything, a short time-to-live for anything volatile, and re-verification through a tool for anything that matters: remembered facts as hints about where to look, not as answers.

The free path

SQLite, genuinely. One file, no server, transactional, queryable from every language, and you can open it in a GUI and look at what your agent believes. Add a memory/ folder of markdown files for anything narrative. Reach for a vector database when you have a real retrieval problem over documents, which is a different subject from an agent remembering things about you.