Agent memory belongs to the team, not to the developer

The first move most people make with agent memory is local. A memory directory, a notes file, something the agent writes to and reads from on their machine. It works immediately, which is why it is the first move, and it is a genuine improvement over nothing.

It also puts the knowledge in the one place where it helps the fewest people.

Why local memory is the wrong boundary

The finding that is worth keeping is almost never worth keeping only for you. If an agent working with you established that the migration runner skips tables it cannot lock and logs it at debug level, that is not a fact about your workflow. It is a fact about the system, and every person on your team who touches migrations will need it.

Local memory means each of them will establish it separately. Five engineers, five investigations, five private records of the same thing, and no way for any of them to know the other four exist. This is the original problem with an index on it.

There is a second failure that is less obvious. Local memory is only as good as the local record, so it decays privately. Your copy says the runner skips unlockable tables. A colleague changed that behaviour last month. Your agent will keep telling you the old thing, confidently, and nothing in the loop can correct it, because the correction lives in a repository your memory file has no relationship with.

Why the repository is also the wrong boundary

The next move is to scope memory to a repository. Better, and still short.

Consider the findings that cost the most to establish. In our experience they are disproportionately about relationships that span repositories:

• This service and that one share a client, and the retry defaults differ.
• The workflow file was copied into four repositories and only two have the cache fix.
• The event schema is defined here and consumed there, and the consumer tolerates a field the producer stopped sending.
• Deployment ordering matters between these two, and nothing enforces it.

None of these is a fact about a repository. Each is a fact about the seam between two. Store it in one of them and you have filed it where half the people who need it will not look, and where an agent working in the other repository has no access to it at all.

Anything inside a single repository is comparatively cheap to rediscover, because the whole of it can be read. The seams are expensive precisely because no single place contains them.

Why the team is the right one

A team is the smallest unit that owns a set of repositories together and shares the consequences of what happens between them.

That makes it the natural boundary in three ways at once. It matches ownership: the people who own these services are the people who need the findings about how they interact. It matches how the knowledge is produced: a finding about a seam is produced by someone with reason to be looking at both sides, which is a property of the team. And it matches trust: a claim written by someone on your team, about a system you both own, needs no further provenance check, while a claim from an unrelated team about a repository you can read but do not own has a very different status.

Going wider than the team is tempting and expensive. Organisation wide memory sounds strictly better and in practice introduces problems the team scope does not have: relevance falls off sharply, trust has to become explicit, access control becomes real work, and volume grows faster than usefulness. It is the right thing to solve second, not first.

The line that has to hold

Team scope is not the same as recording everything anyone does. There is a distinction worth being explicit about, because it decides whether a system like this is something engineers want or something they route around.

Raw activity belongs to the developer. What you searched, the branches you abandoned, the eleven wrong turns before the right one, the code you deleted. That is your working process and it should stay yours.

Knowledge belongs to the team. The conclusion, the evidence behind it, the explanations that were ruled out. That is a property of the system you all own.

A memory system that blurs those two becomes surveillance, and engineers are right to reject it. One that respects the line has to make consolidation deliberate rather than automatic: observation can be continuous, but what becomes shared knowledge is something a person decides to promote, at a checkpoint, from work they consider finished.

That is a product decision as much as an architectural one, and it is the one we care most about getting right in REM. The team is the memory boundary for the private beta, evidence is immutable, claims are versioned, and raw activity is not the unit that gets shared.

The practical version

If you are not going to adopt a system for this, the boundary argument still applies to what you already have.

Put findings where the team can reach them rather than where you can. Prefer the location that spans repositories over the one inside a repository, for anything that is about a seam. And accept that whatever you write will go stale, so write down the evidence next to the claim, because the evidence is what lets the next person check it in a minute instead of re-deriving it in an hour.