Give the agent a filesystem it can inspect

We build production GenAI for operations, knowledge, and data. Memory is where those three meet. An operations agent that cannot show what it thought it knew is not ready for a bridge call. A knowledge agent that cannot point at the note it retrieved is not ready for a citation. A data agent that cannot open the last mapping decision is not ready for a review queue. In all three cases the failure looks like a model miss. It is usually a memory miss you cannot see.

Hidden vector stores and opaque session blobs make agent memory a black box. When a run goes wrong — and it will — you cannot read what the agent thought it knew. You can only watch it do the wrong thing again with great confidence. That is not a research inconvenience. That is an operations defect.

Prefer a filesystem. Notes, tickets, diffs, and recall paths a person can open. Addressable memory is debuggable memory. If you cannot cat the file, you cannot explain the decision.

Similarity is not an explanation

Dense retrieval is a good index. It is a poor source of truth. An embedding tells you that two strings were near each other in a space you do not inhabit. It does not tell you who wrote the fact, when it was last true, whether it was a decision or a guess, or which agent was allowed to overwrite it. When the only memory you have is a vector store plus a session blob, incident review becomes folklore: we think it remembered the retry policy; we think it had the customer id; we think last Tuesday’s thread is still in there.

Session blobs fail in a second way. They are convenient for a single client. They are hostile to every other client, and to every person who does not speak that vendor’s export. Resume becomes “open the same window.” Handoff becomes “paste the chat.” Audit becomes “we do not have that.”

The production question is not “did the model retrieve something?” The question is “can a reviewer open the thing it retrieved, see the path, and decide whether the next action is allowed to fire?” If the answer depends on a vendor UI, you do not have memory. You have a souvenir of a conversation.

Memory should be a tree a person can walk

Working memory, session memory, and durable memory are not the same object. Collapsing them into one pile is how stale facts become policy.

Working is the scratch of this turn: the open ticket, the current diff, the three files in play. It should be cheap to throw away and obvious when it is stale.

Session is the thread that should resume: decisions already made, the retry policy in force, the hypothesis ranked an hour ago. Session save and resume against files is how a coding agent comes back to the same job without reconstructing folklore from a chat scroll.

Durable is the estate: entities, schema maps, on-call rotas, service-graph notes, artifact paths. Durable memory is a contract with operations. It is small enough to audit, named enough to search, and boring enough that a person will actually open it.

The tree is the product. Vectors, if you use them, hang off the tree as an index. They do not replace it. When recall fires, the agent should return a path and a snippet, not a ghost of a similar sentence. When write fires, the agent should create or patch a file a reviewer can diff. When a second client — another agent, or a person — arrives, it should see the same tree, not a private embedding it cannot export.

Why MCP is the port, not the memory

OpenStinger is our portable MCP agent memory for that pattern: write, recall, inspect. The protocol is the port. The files are the memory. That distinction matters. If you treat MCP as a place to hide another blob, you have only changed the wire format of the black box. If you treat MCP as the way any serious client reads and writes the same tree, you get something operations can live with.

A coding agent, an ops agent, and a reviewer are not the same process. They should not each invent a store. The coding agent we ship already keeps memory and session save on files, not on a mystery blob, in front of an in-network gateway. The same idea shows up when incident intelligence has to hand a person a ranked hypothesis with evidence attached. If the evidence is “the model remembered,” the handoff failed. If the evidence is a path into the tree, the person can disagree with it. Disagreement is the point. Uninspectable memory cannot be overruled. It can only be suffered.

Portability also kills a quiet vendor lock. The memory that only lives inside one coding client will not be there when the next client is the one your security team approved. Files on a path survive that argument. Blobs do not.

What goes wrong when memory cannot be opened

These failure modes are not theoretical. They are how quiet systems become expensive.

Silent overwrite. Two agents, or two turns, write the same durable fact. There is no diff. The new value wins. The old value was the true on-call rota. The next act pages the wrong person.

Stale recall. Working notes leaked into durable memory. The agent keeps retrieving last month’s retry policy because it is near the query in vector space. No one can see the timestamp because there is no file.

Memory bloat. Everything is remembered. Nothing is ranked. The pack that should have been slim is now a junk drawer. Token spend climbs and the useful completions per thousand tokens fall — the opposite of the 42% lower token spend and 2.4× useful-completion shape a disciplined gateway is supposed to hold.

Unreviewed writes becoming policy. A scratch hypothesis gets written without a reviewer. The next session treats it as durable. You have created institutional knowledge out of a guess.

Cross-client drift. Cursor remembers one story. The ops agent remembers another. The reviewer sees neither. MCP without a shared tree is just three black boxes that can wave at each other.

The mute incident. Mean time to recovery is a memory problem as much as a reasoning problem. The 75% lower MTTR we deliver on incident intelligence assumes the hypothesis arrives with evidence a person can open. A vector neighborhood is not evidence. A file with a path is.

Tradeoffs: retrieval quality versus a throat to choke

Inspectable files are not free. They take design. You have to name things. You have to decide what is working versus durable. You have to prevent the agent from treating the tree like a diary. Vector-only memory is faster to stand up and easier to demo. It will also be the thing you cannot explain to a risk committee.

The honest hybrid is this: use embeddings to find candidate paths; use files as the record; use the harness to refuse an act when the record is missing. That is the same gather-then-verify shape as the rest of the loop. Memory that cannot survive verify is not memory. It is atmosphere.

Another trade is size. Durable memory that cannot be audited will not be audited. Keep entities small. Keep decisions as short notes with dates. Keep artifacts as paths, not as pasted dumps. A person who can open the last write in a minute will open it. A person who has to reconstruct a 40,000-token blob will not.

A third trade is privacy and tenancy. A filesystem makes isolation visible: this tree is this workspace, this agent, this retention. A shared vector soup makes isolation a hope. Production memory is a contract with operations, which means it is also a contract with the people who have to delete it.

What production demands

Keep memory on a path. Keep it hierarchical so scratch cannot quietly become law. Keep a write that produces a diff and a recall that returns a path. Keep the bus portable — MCP — so the coding agent, the ops agent, and the reviewer are looking at the same tree. Keep a human able to open the last write before the next action fires.

That is the standard we build to at sunrisegenai.com and in OpenStinger. The model can forget. The filesystem must not. If you cannot inspect the memory, you cannot defend the act, and if you cannot defend the act you do not have a production agent. You have a conversation that happens to have a disk you are not allowed to see.