How an Agent Finds Its Own Notes: Short Index, Links and Search

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.