Where an Agent System Keeps Its State

Agent systems become hard to trust when every important thing goes into the same place.

Put all state in a chat and the system becomes difficult to inspect or rebuild. Put it all in a request ticket and the ticket turns into an unsafe archive. Put it all in source control and you start pretending that live task sessions, open obligations, and access to current tools are static configuration.

The better question is not, “Where is the memory?” It is, “What kind of fact is this, and what job does its location need to support?” A Practical Architecture for Reliable Multi-Agent Systems shows why that boundary supports an owned request and visible delivery.

This is a practical part of the wider architecture. It is also one of the clearest differences between an agent demo and a system that people will have to maintain.

The short version is: keep definitions in source control, live obligations in the Runtime, working context in the task session, substantial evidence in the work area, and reusable lessons in a maintained knowledge system. The rest of this article explains why those boundaries matter.

Five places hold different kinds of truth

In my system, state is deliberately spread across a few locations. That is more work than one shared object, but it avoids asking any one store to mean everything.

Each location answers a different question.

Source control answers, “How should this role or system be made?” The Runtime answers, “What work is happening and what is still owed?” The task session answers, “What does this role currently know how to work with?” The domain work area answers, “What evidence and artifacts belong to this job?” The knowledge system answers, “What should future people and agents be able to find?”

Git is a factory, not a photograph of the running system

I want source control to describe how to create a clean generation of the system.

That means keeping the stable definitions there: service interfaces, role charters, bootstrap instructions, model profiles, topology, Runtime code, and a rebuild process. A future operator should be able to understand what an endpoint is for without excavating an old conversation.

It does not mean committing a snapshot of the machine’s current state. Current task identities, saved-project bindings, locks, open requests, connector sessions, and application databases are live facts. They change while the system runs. Treating them as portable source produces brittle copies and accidental exposure of sensitive material.

This distinction makes the honest recovery claim much clearer. Source control can be ready for a rebuild before a clean rebuild has actually been demonstrated. A documented procedure is evidence. A successful fresh creation is stronger evidence. They are not the same claim.

That is why the proof ladder starts with source readiness and then separates creation, activation, routing, delivery, natural product proof, and retirement.

Building One Agent from Coordinated Roles in Codex shows how those source definitions become a live role without confusing the two.

A ticket is a record of an obligation, not an archive

The Runtime needs a small ticket before it starts work. The ticket should preserve enough information to explain the request even if the worker never launches: the target, caller, request identity, current status, duplicate key, return path, and pointers to the work.

It should not become a second copy of the world.

Do not fill a ticket with source files, huge transcripts, workspaces, credentials, or every artifact a worker produces. That creates cost, privacy risk, and confusion about which copy is authoritative. It also makes callback and recovery behavior harder to reason about because the transport layer starts carrying material it cannot safely interpret.

Instead, keep the substantial work in the domain project or evidence packet and let the ticket point to it. The prompt says what the receiving role should do now. The evidence pointer says where that role can inspect the larger body of work. Those are different things.

This small separation prevents a common failure: treating a packet full of materials as though it were the agent’s current instruction. It is neither a focused request nor a sensible transport record.

For the controls around tickets, callbacks, and recovery, see Reliable Agent Work Needs Tickets, Locks, and Recovery.

A task session is useful but not a source of truth for everything

Persistent task sessions can carry valuable role-specific context. They may know the current project, the local instructions, the tools that are available, and the history that helps a specialist avoid rebuilding the same understanding every time.

That is why a persistent specialist can be useful. It is also why two overlapping turns in the same session can be risky: each may act on the same starting context and then make incompatible changes. A lock protects the session from that kind of collision. It does not make its answer correct.

But a session is not a reliable inventory of the system. It is app-managed live state. It can change, become stale, or fail to exist on a replacement machine. A saved task should be read back and validated as a live endpoint; it should not be inferred from a definition or silently copied as though it were a file.

This is the right kind of humility about persistent context. It is helpful operating state, not a permanent record of every decision the organization has made.

Let work and learning have their own homes

Substantial work needs room to breathe. A release review, investigation, code change, or research task may have source documents, a plan, validation, artifacts, and a final recommendation. Keep that material in the domain’s work area, where the owner and worker can inspect it together.

Learning has a different time horizon. A closeout may reveal that a tool guide is old, a dependency was easy to miss, or a feature has a relationship future reviews should know about. That lesson belongs in a source guide, runbook, structured Markdown vault, or another maintained knowledge system—not as an accidental fact buried in a completed ticket.

How to Make an Agent System Learn explains how a closeout, manager reflection, and evolution proposal turn those discoveries into reviewed change.

The key is to preserve links back to evidence. A knowledge note can summarize a feature, component, failure pattern, or risk. It should still make clear where the source came from, who owns the note, and when it was last reviewed. Otherwise, a tidy knowledge system becomes a tidy source of stale confidence.

Follow one request through the state model

Here is what the separation looks like in a normal request:

Source control
  -> defines the role, interface, and route

Runtime ticket
  -> records a request, its return path, and its current obligation

Agent task session
  -> receives the focused instruction in the correct role context

Domain work area
  -> holds source material, plan, validation, and substantial artifacts

Shared knowledge system
  -> receives a reviewed lesson that should help later work

The result may pass back through the Runtime as a compact response and delivery receipt. The full work stays where it can be inspected. The lesson moves only after someone has decided it deserves a future home.

That is not duplication. It is deliberate separation by purpose.

Design the state boundary before the system gets busy

You do not need five products to use this idea. Even a small system benefits from a few clear rules:

• Keep role definitions and rebuild instructions in source control.
• Write a compact request record before long-running work begins.
• Keep the working evidence with the domain task, not inside the ticket.
• Treat task sessions as live context that needs validation and concurrency care.
• Move reusable lessons into a reviewed knowledge system with links and dates.

The tradeoff is real. Distributed state means more interfaces and more responsibility for keeping the parts aligned. But the alternative is worse: one opaque container that is simultaneously the prompt, the database, the workspace, the memory, the audit trail, and the recovery plan.

Agent systems need context. They also need to survive beyond any one context window. Giving each kind of state the right home is how you get both.