Memory architecture for teams that adopted AI

Legacy from day one

When we went AI-first at helloo, working code started to arrive faster than the team could absorb it. Features were done, and after a while the team couldn't change those parts with confidence, because the reasoning behind them stayed in a chat session that was already closed. We arrived in a dead end with code that worked.

Slowing down was an option and it wouldn't solve anything. What fixed it was making each project describe itself: conventions written for the agents, the why of each decision next to the code, docs updated in the same change as the code, and files written for an agent to read first when it opens the repo. The test I use now is simple. A person or a model clones the repo, reads what is there, and continues the work. If that doesn't happen, the project is legacy already, even if it was written last week.

A project only its original agent understands is legacy from day one, and with agents writing most of the code you get there much faster than with people.

Wrong memory is worse than no memory

It's dangerous because of an asymmetry. Missing memory fails loud: the model asks, or goes and reads the code, and you see the cost. Wrong memory fails in silence. The model goes on confident, the mistake looks like knowledge, and it's still there in the next session. A strong model often finds the right answer in the end, but it already spent time and tokens going around, and if you don't notice, the wrong note survives.

My best example has no AI in it. A number about my own work, 150 million events per day, was right at some point. It became old without anyone noticing, it was copied to 25 files of my notes, and for months I used a number 24% below the real one. The fix had three parts: one source file for numbers with a date on each, a small script that checks every other file against it, and a clear split between living material and historical record.

The layout

where things live

~/.claude/CLAUDE.md                 short: who I am, hard rules, an index
project/CLAUDE.md                   status, commands, ports, known problems
project/CHANGELOG.md                what changed, when
memory/<topic>.md                   one fact per file, with date and source
memory/MEMORY.md                    index of the memory files, one line each

My global file is light, at most an index pointing to files the agent loads only when the subject comes up. The project file is the same idea, smaller. Decisions from meetings go to a third level, and always written as events: "on 2026-08-26 we decided X". Never as a rule like "the company uses X", because decisions change, other people touch the code, and the company changes its mind.

memory/dedup-is-a-net.md

---
name: dedup-is-a-net
description: ReplacingMergeTree is the last dedup layer; the real one is before the insert
type: project
---
Measured 2026-08-30 in production: duplicate factor 1.11 one hour after the write.
Source: investigation notes, section "convergence curve".
Why it matters: never read fresh data from this table with a raw count().

What helped me to think about this is volatility, more than depth. "He was CTO for nine years" never expires. "The table uses ReplacingMergeTree" expires slowly. "The team decided X" may be expired on the day it was written. A fact with date and source never turns into a lie, it turns into history. Without the date it becomes a lie the day reality moves.

Where a fact lives decides how long it lives

On 2026-08-27 I lost 5,794 characters of research. A small tool of mine kept curated notes about companies in a database column, and the routine that revalidates records overwrites that column by design. One normal run, and it was empty. The fix was a new column that the routine doesn't touch. The data was right all the time; it was living in a place whose overwrite rule I didn't know.

Agent memory works the same way, so before you save something, know who else writes in that place.

Rules expire when the reader changes

Memory gets old because the world changes, and you can audit it against the source. Instructions get old because the reader changes, and you can't audit them by truth because they stay true. My own global file had a table saying which model to use for search, which for refactoring, which for complex tasks. It was written for a generation of models that doesn't exist anymore. It looked right and passed any review.

So I audit rules with another question: does the model still make this mistake?

Two cases from my own automation work show both sides. My global file has an old rule: verify visually, don't trust only the HTTP status. That day the assistant ignored it and spent three rounds inspecting the DOM to find out why a form field looked empty. A screenshot solved it in ten seconds. The rule still corrects a live error, so it stays. In another job, a selector has-text("Male") matched the "Female" option, because one string contains the other. There the fix was more determinism (exact match), because for an automated agent filling a known form, determinism is the product. For analysis or for exploring a big codebase it's the opposite, and a tight rule there just gets in the way.

So I keep the rules I have in three groups, and they age in different ways:

Live-error rules stay while the error exists, and you check it from time to time.
Scope and authority rules never expire, because a smarter model doesn't get more permission.
Capability crutches can go when the model doesn't need them anymore. In one benchmark of mine, the same scaffolding took one local model from 23.5% to 38.6% and made another one worse, enough that I reverted it.

Checklist

Keep the root context file as an index; details live in files the agent loads on demand.
Put a date and a source on every fact, and write decisions as events.
Docs change in the same commit as the code. The agent writes them, a person reviews.
Audit each rule with "does the model still make this mistake?"
Once a month, open a clean session and ask the agent to continue a task using only what is in the repo. Where it gets lost is your next doc to write.

Filed under the problem it solves