I run my business with a team of agents. There are twenty-seven specialists, each skilled at one thing, all working together. Every day, each one learns something the hard way. Maybe a tool fails and the error message is misleading. Maybe there’s a booking edge case no one expected, or a rule I gave to one agent that another needs a week later.
The challenge isn’t getting them to learn. The real issue is that if no one can find a lesson again, you end up paying for it twice.
A file that no one uses isn’t a memory
A file on your computer that isn’t linked anywhere isn’t a memory - it’s just a file.
So memory isn’t just the note itself. It’s the note plus a way to find it again.
The system has three levels. At the bottom, there’s a topic file for each lesson, with one fact each, written as soon as an agent learns it. In the middle, domain files only load when someone is working in that area, so a lesson about booking shows up when needed and stays hidden otherwise. At the top, there’s one index that loads for every job, for every agent, every time.
The top index is the costly part. The real limit is context - how much an agent can keep in mind for a task. The index uses up that limit every time, so each line is a cost I pay on every job. Every agent reads it before starting. Having a subagent inherit what its parent knows is a design choice, not automatic. A memory system doesn’t fail from too many notes. It fails when the map gets too big to use, so you stop using it and forget the notes underneath. If you use Claude Code, this is the CLAUDE.md file. AGENTS.md works the same way. It started with OpenAI’s Codex and is now an open standard.
You move a lesson down a tier, but you never delete it
Since the index has a strict limit, it’s tempting to clear it out and delete old entries. But that’s how you end up losing everything. In most terminal sessions, whatever the agent learned disappears as soon as you close the window. If I’m going to invest in an AI team, it needs real memory - something I can take to another provider if needed. Plain markdown files in git make that possible. Claude Code keeps its own memory folder for each project, and I point that folder right into the repo, so it’s tracked and portable, not just a second copy sitting somewhere else.
The rule is to move entries down, not delete them. When the index is full, an entry isn’t thrown away - it moves down a tier, from the main map to one that loads only when needed. The lesson stays available for the work that needs it, but it no longer adds extra work to other tasks. If an entry looks outdated, I review it myself instead of letting a script remove it.
Moving a lesson down isn’t enough if it turns out to be wrong. So, a wrong entry gets marked as superseded and points to the correction. The old answer can’t be found without the new one right beside it.
A small job keeps the system in check. It runs at 4:30 every morning and takes care of the boring tasks people forget. It finds any note without a pointer and files it, and it flags duplicates for me to review instead of merging them automatically. I prefer to decide on merging notes myself, not at 4:30 in the morning.
The review itself ended up being wrong, but it exposed something else that it was right about
This is the part I’d rather skip, which probably means it should be included.
Once the system was running, I asked someone from outside to review it. Not a team member, but someone with a fresh perspective, because a system that only checks itself will always think it’s fine. The review found seven issues, and the most serious was rated high: it said the safety rules weren’t reaching the agents at all. If that had been true, every agent would have been running without guardrails.
So we tested it. We used the same check on every agent type, asking each one to repeat the safety rules to show they could see them. The review was wrong. All but two agents had the rules the whole time. That was a relief, but it shouldn’t have been, because the same test found the real problem: the two agents missing the rules could still run shell commands.
While checking the review, we found our own mistakes. My write-up mixed numbers from before and after a cleanup, so the math didn’t add up if you looked closely. And one memory was just wrong, a claim about how a calendar refresh worked, but it looked just as trustworthy as the true ones next to it.
That last mistake is why this all matters. When a memory is missing, it fails loudly - you look for it, can’t find it, and know you’re on your own. But a wrong memory fails quietly. It gives you a confident answer that’s actually false, and you don’t realize it until it causes a problem. That’s what keeps me up at night, not an empty index.
What it comes down to
None of this is complicated. It’s just a filing system with a limit and a rule against throwing things away. But it’s the difference between a team that gets smarter every week and one that keeps solving the same problem, because last month’s answer is stuck in a file no one can find.
If you can’t find a lesson, you pay for it twice. I’d rather only pay once.
If you want to see what the team runs each day, check the Inside page.