{"course":{"slug":"agents-and-automation","title":"Agents and Automation","url":"https://addaly.com/learn/agents-and-automation","level":"intermediate","track":"build"},"lesson":{"slug":"agent-memory","title":"Memory is a directory, not a mystery","url":"https://addaly.com/learn/agents-and-automation/agent-memory","position":19,"of":72,"minutes":8,"answer":"Memory that works is a file you can open and a table you can edit; a vector store of everything the agent ever saw is unauditable, undeletable and usually unhelpful.","keyIdea":"Memory that works is a file you can open and a table you can edit; a vector store of everything the agent ever saw is unauditable, undeletable and usually unhelpful."},"body":{"format":"markdown","text":"## Three different things share one word\n\nWhen somebody says an agent needs memory, ask which of these they mean, because the engineering is completely different.\n\n1. **Within a run.** Keeping track across twenty steps, when the transcript is being compacted.\n2. **Across runs, about an entity.** This customer prefers Hindi; this repository uses tabs; this supplier always sends PDFs.\n3. **Across runs, over past conversations.** Search over everything that was ever said.\n\nThe first two are ordinary engineering and they work. The third is the one people mean and the one that disappoints.\n\n## Within a run: write it down\n\nThe strongest and least glamorous technique in agent engineering is a file.\n\nHave 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.\n\nIt 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.\n\n## Across runs about an entity: a table with fields you chose\n\nDo 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.\n\nPick the fields:\n\n```sql\nCREATE TABLE account_memory (\n  account_id   text primary key,\n  language     text,\n  timezone     text,\n  billing_note text,\n  updated_at   timestamptz not null default now()\n);\n```\n\nFive 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.\n\n## Across past conversations: the honest position\n\nSemantic 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.\n\nIf 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.\n\n## Staleness has no expiry date\n\nThis 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.\n\n## The free path\n\nSQLite, 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."},"check":{"question":"A support agent stores a summary of every past conversation in a vector index and retrieves the three most similar ones for each new ticket. Customers begin receiving answers based on a policy that changed four months ago. Which fix addresses the mechanism rather than the symptom?","options":[{"text":"Retrieve five past conversations instead of three, so the current policy is more likely to appear.","correct":false,"tempting":"Adds more of the same distribution. If old conversations outnumber new ones, more retrieval mostly retrieves more old ones."},{"text":"Add an instruction telling the model to prefer recent information.","correct":false,"tempting":"Asks the model to judge recency it cannot see, since the retrieved text carries no date unless you put one there."},{"text":"Use a better embedding model so the matches are more accurate.","correct":false,"tempting":"Improves similarity, which was never the problem. The retrieved conversations are genuinely similar; they are simply out of date."},{"text":"Keep policy in a dated, editable store the agent reads directly, and use retrieval only for phrasing and precedent, with a written-at date attached.","correct":true}]},"prev":{"slug":"context-window-management","title":"What to throw away, and when","url":"https://addaly.com/learn/agents-and-automation/context-window-management"},"next":{"slug":"multi-agent-or-not","title":"When a second agent helps, and when it just costs more","url":"https://addaly.com/learn/agents-and-automation/multi-agent-or-not"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Exam keys checked blind by a second model: 3,665 of 3,666 agreed. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'Memory is a directory, not a mystery', in Agents and Automation. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/agents-and-automation/agent-memory (Accessed: 13 October 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"Memory is a directory, not a mystery","courseTitle":"Agents and Automation","module":{"index":2,"slug":"how-the-loop-runs","title":"The machinery: transcript, tools, loop"},"answer":null,"keyIdea":"Memory that works is a file you can open and a table you can edit; a vector store of everything the agent ever saw is unauditable, undeletable and usually unhelpful.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"three-different-things-share-one-word","runs":[{"text":"Three different things share one word"}]},{"t":"p","runs":[{"text":"When somebody says an agent needs memory, ask which of these they mean, because the engineering is completely different."}]},{"t":"ol","start":1,"items":[[{"text":"Within a run.","b":true},{"text":" Keeping track across twenty steps, when the transcript is being compacted."}],[{"text":"Across runs, about an entity.","b":true},{"text":" This customer prefers Hindi; this repository uses tabs; this supplier always sends PDFs."}],[{"text":"Across runs, over past conversations.","b":true},{"text":" Search over everything that was ever said."}]]},{"t":"p","runs":[{"text":"The first two are ordinary engineering and they work. The third is the one people mean and the one that disappoints."}]},{"t":"h2","id":"within-a-run-write-it-down","runs":[{"text":"Within a run: write it down"}]},{"t":"p","runs":[{"text":"The strongest and least glamorous technique in agent engineering is a file."}]},{"t":"p","runs":[{"text":"Have the agent maintain "},{"text":"plan.md","code":true},{"text":" and "},{"text":"notes.md","code":true},{"text":" 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 "},{"text":"the API has no refund endpoint, use credits instead","i":true},{"text":" on step three still knows that on step nineteen."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"across-runs-about-an-entity-a-table-with-fields-you-chose","runs":[{"text":"Across runs about an entity: a table with fields you chose"}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"Pick the fields:"}]},{"t":"code","lang":"sql","label":"SQL","text":"CREATE TABLE account_memory (\n  account_id   text primary key,\n  language     text,\n  timezone     text,\n  billing_note text,\n  updated_at   timestamptz not null default now()\n);"},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"across-past-conversations-the-honest-position","runs":[{"text":"Across past conversations: the honest position"}]},{"t":"p","runs":[{"text":"Semantic search over old chats returns what is "},{"text":"similar","i":true},{"text":", not what is "},{"text":"relevant","i":true},{"text":": 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."}]},{"t":"p","runs":[{"text":"If you do it anyway, two mitigations earn their keep. Store the "},{"text":"outcome","b":true},{"text":" alongside the transcript so you can retrieve only from runs that succeeded. And store a "},{"text":"written-at date","b":true},{"text":" with every remembered fact, and put that date in the context, because nothing in an index knows that a price changed in March."}]},{"t":"h2","id":"staleness-has-no-expiry-date","runs":[{"text":"Staleness has no expiry date"}]},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"the-free-path","runs":[{"text":"The free path"}],"role":"free"},{"t":"p","runs":[{"text":"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 "},{"text":"memory/","code":true},{"text":" 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."}]}],"check":{"question":[{"text":"A support agent stores a summary of every past conversation in a vector index and retrieves the three most similar ones for each new ticket. Customers begin receiving answers based on a policy that changed four months ago. Which fix addresses the mechanism rather than the symptom?"}],"options":[{"text":[{"text":"Retrieve five past conversations instead of three, so the current policy is more likely to appear."}],"correct":false,"tempting":[{"text":"Adds more of the same distribution. If old conversations outnumber new ones, more retrieval mostly retrieves more old ones."}]},{"text":[{"text":"Add an instruction telling the model to prefer recent information."}],"correct":false,"tempting":[{"text":"Asks the model to judge recency it cannot see, since the retrieved text carries no date unless you put one there."}]},{"text":[{"text":"Use a better embedding model so the matches are more accurate."}],"correct":false,"tempting":[{"text":"Improves similarity, which was never the problem. The retrieved conversations are genuinely similar; they are simply out of date."}]},{"text":[{"text":"Keep policy in a dated, editable store the agent reads directly, and use retrieval only for phrasing and precedent, with a written-at date attached."}],"correct":true,"tempting":null}],"order":[1,2,3,0],"why":null},"prev":{"slug":"context-window-management","title":"What to throw away, and when","minutes":10},"next":{"slug":"multi-agent-or-not","title":"When a second agent helps, and when it just costs more","minutes":9}}}