Agent state is the durable, writable knowledge an agent carries between runs: facts, decisions, learnings, and work in progress.
The agent reads state to orient itself at the start of a task. The agent writes state to preserve what it discovers. State survives session restarts. It belongs to the agent, not to the runtime.
Example: an agent finishes a deploy and writes the outcome to modules/deploy/log.md. Next session, the agent reads that log before it acts. The file is the state. The write is what makes it state.
Chat history is a transcript. State is the distilled result. Replaying full conversations costs tokens and carries noise. State replaces thousands of tokens with a few lines of knowledge.
RAG retrieves from a corpus the agent does not own. State is owned and mutated by the agent itself. RAG answers "what do we know?" State answers "what have I learned?"
Configuration is human-authored input (CLAUDE.md, cursor rules). State accumulates from work. The difference: who writes it. A human writes config. The agent writes state.
| Chat history | RAG corpus | Configuration | Agent state | |
|---|---|---|---|---|
| Owner | Runtime | Pipeline | Human | Agent |
| Write path | Automatic | Pipeline | Human edit | Agent tool call |
| Lifetime | Session | Indefinite | Until changed | Between runs |
| Granularity | Message | Document | File | Topic |
| Correction | Not correctable | Re-index | Edit file | Edit file or self-correct |
Entry-point routing. Each topic gets a folder with an index.md that routes to sub-files. The agent reads the index first.
Append-then-distill. Write raw observations during work. Periodically summarize into a shorter file.
Decision logs. Append-only record of choices and reasons. The agent checks before repeating a decision.
Run scratchpads. Per-task workspace. Promote durable findings when the task finishes.
gcontext serves a folder of plain text files as agent state over MCP. Three top-level directories: connections/ for services, modules/ for knowledge, agents/ for installed agents.
The agent reads and writes through MCP tools. Any MCP client works: Claude Code, Cursor, Codex.
The practice of giving an AI agent durable, writable storage that it reads at the start of each task and writes to as it works. Good state management keeps that storage inspectable, portable, and scoped to what the current task needs.
"Memory" emphasizes recall. "State" emphasizes that the agent both reads and writes it. In practice they describe the same thing: persistent knowledge the agent maintains across sessions.
Files for most use cases. A database when you need structured queries. Vector storage when you need fuzzy recall over large corpora. Plain files give you the best inspectability and version control with the least infrastructure.
Install gcontext. A folder of plain files, served over MCP, readable and writable by the agent.