An agent can write a note today and never read it again. Each session starts with only the top of its memory index. Every other note needs a link from there, or a search that matches its words.
Engineer's view. This is the page on your site that no other page links to. A crawler starts at the homepage and only finds what links lead to. An agent starts each session with the top of its memory index and opens only what that points to. So last month's note can sit unread.
TL;DR. An agent loads only a small part of its memory when a session starts, and reaches everything else by a link from there or by a search. Keep that part short and pointing to one page per subject, and keep search as the backup.
Explain Like I'm 5
You keep a notebook of everything you learn. Every morning you are only allowed to read the first page before you start work.
If the first page says "birthdays are on page 12", you can find any birthday. If the first page is just the oldest notes you ever wrote, the newer ones might as well not exist. You wrote them. You will never look.
A good first page is short. It tells you where things are, not what they say.
The Problem
You have shipped this bug before, and it had no model in it.
You published a page on your site. It was good. Nobody found it. Weeks later you learned why. No other page linked to it, and it was not in the sitemap. A search crawler starts from a few known pages and follows links. A page no link reaches is an orphan. It exists, it is correct, and it is never read.
An agent with memory works the same way. Claude Code, or an agent you build on a memory tool, writes notes to files between sessions. A new session starts with an empty context window, the text the model can see right now. The harness then loads one small slice of memory into it. In Claude Code that slice is the first 200 lines or 25 KB of an index file called MEMORY.md, whichever comes first. Everything else is read only if the model chooses to open it.
So memory fails quietly in three ways. The index grows past the cap, and the newest notes fall off the end. A note sits in a folder no loaded line points to. Or several agents write one shared summary page and overwrite each other's lines.
None of these raise an error. Your agent just asks you a question it answered last month.
The fix: keep the loaded index short and make it point to one page per subject, quote facts word for word on those pages, and keep a search over raw history as the backup.
Read the full post on The AI Commit
How an Agent Finds Its Own Notes: Short Index, Links and Search carries the rest: the fix and why it works, the code to change for each role, how to tell it worked, when it is the wrong tool, and an interactive model you can play with.
Originally published at theaicommit.com, a daily AI engineering lab for software engineers. The original has an interactive version you can play with, and the full runnable code is on GitHub.
Top comments (3)
The orphan page thing is so real. I've been fighting my agent's memory for a long time and this is the bug that drove me nuts: the note's right there, it's correct, it's saved, and my agent just... never looks at it again. Then it asks me something it already knew.
What's been working for me: the index is basically a map. One word per subject, and each word opens one whole page, every time. And I route with my own words, so if I say "investing" it pulls that page and tells me "Pulled investing." If it grabbed the wrong thing, I catch it right there instead of three days later.
Your 200-line cap point hit me too. My agent used to load its own memory, say "pulled!", and sometimes all it actually got was a little preview of a way bigger file. It had no idea. So now a dumb little script does the loading and prints what actually loaded. Receipts or it didn't happen.
Do you have your agent say what it opened, or is search doing most of the heavy lifting?
The startup index is the part I watch most in Tokenade, the open-source tool I make: it goes back to the model on every turn, so its size is a cost, not only tidiness.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.