Agent state: codestate & memstate

Every agent is three layers: a frozen seed-core kernel, a mutable codestate (its code & capabilities), and a memstate (its learned memory). Codestate and memstate version and swap independently — and capability knowledge always travels with the code, so a swap can never leave the agent “remembering” a skill it no longer has, or missing one it does.

Codestate — the agent's code & capabilities

The codestate is the versioned body of the agent: its bridge code, skills, and capability-memory (the always-true description of what this code can do). Capability knowledge ships with the codestate, so it is always in sync with the code.

• Base seeds are the stock starting points (e.g. gina-seed, techne-seed). They are read-only baselines.
• Saved codestates are snapshots you capture from a running agent, tagged with a name, commit, and capture time.
• Deploying a codestate rebuilds the agent from that code. Its learned memory (memstate) is retained. A full backup is taken first.

Memstate — the agent's learned memory

The memstate is everything the agent has learned: its brain (event memory), wiki, and personal notes. It does not include capability knowledge — that lives with the codestate — so swapping memory never changes what the agent can do.

• Fresh / empty wipes the learned tier to a clean slate. Built-in capabilities are kept. (Shown with a warning, because learned memory is cleared.)
• Saved memstates are snapshots you capture, tagged with a name, memory count, and capture time.
• Restoring a memstate replaces the learned tier with that snapshot. Code and capabilities are unchanged. A full backup is taken first.

Why they stay coherent

Memory is split by where it lives, which guarantees capabilities and memory never drift apart:

• Core memory (seed-core, frozen): what the agent is, how to use it, built-in troubleshooting. Identical in every codestate.
• Capability memory (ships with the codestate): what this code can do. Swapping codestate refreshes it to match the new code.
• Learned memory (the memstate): runtime learnings, decisions, notes. The only tier a memstate swap touches.

Saving, restoring & backups

• Save current state captures the live codestate and/or memstate as a named restore point — save both together or just one.
• Every swap is backed up first: the prior state is auto-tagged and a full volume snapshot is taken, so any change is reversible.
• Saved states and snapshots are bounded by per-agent quotas and an automatic retention window, so they do not accumulate without limit.

Good to know

• Swap and save actions are queued and applied by the orchestrator within a few minutes — refresh the State tab to see the result.
• A codestate deploy briefly restarts the agent; an in-flight memstate restore drains running work first.

Manage these from an agent's State tab in the console.