State & Memory

An agent isn't a stateless function. Between a bare axon.request("hello") and a multi-day project thread there are four layers of state, each with its own scope and lifetime. Knowing which layer holds what explains why the agent remembers some things and not others — and how to make it remember the things you want.

Base state

Base state is what the agent is when nothing is happening. It comes entirely from the agent folder: boot.vue, tools, prompts, config, installed modules. Nothing that happens during execution changes it — which is why identity and working practices don't drift over a session. They come from source, not from conversation history.

In local development, hot reload applies source edits to future work without rewriting existing history.

Session state

A session is the agent's lifetime — from boot to shutdown. Everything in between — every exchange, every tool call, every file written — belongs to it. The three session shapes have different lifetimes:

axon              # TUI — session lasts until you close it
axon run scout    # Script — session lasts one script run
axon deploy       # Cloud — session spans requests; restarts after idle periods

The cloud shape is the one that surprises people: a deployed agent's session can end and restart with scaling events. What never restarts is data/ — thread history, knowledge files, and anything the agent has written survive cold starts and redeploys. The session is ephemeral. The folder is not.

Thread state

A thread is a scoped slice of working memory for one conversation. The agent sees the full history of a thread on every call to it, and nothing from other threads. Named threads persist: "project-alpha" on Monday is still "project-alpha" on Tuesday, prior context intact.

The composition patterns — side threads, parallel branches, persistence — are covered in Threads.

Request context

Request context is what you pass to a single invocation — rendered prompts, policy narrowing, inline data. It's consumed and cleared when the loop completes. Loading a support ticket for one invocation doesn't permanently teach the agent about that ticket; the next invocation starts clean.

This is what makes agents predictable: a hundred tasks in a day, no cross-contamination between them.

What persists, and where

Three mechanisms, from automatic to deliberate:

Thread history — automatic

The runtime writes every session to data/sessions/ as a JSONL trace — every entry, every tool call, every result. Named threads resume by loading it. You don't manage this and there's no persistence API to call.

Knowledge files — deliberate

data/knowledge/ is yours by convention: scripts write here during execution, the boot prompt reads here at render time. It's accumulated memory the agent builds on purpose — what it has learned about a domain, a codebase, a set of rules.

// src/scripts/learn.ts
const result = await axon.request({ prompt: [context, learnPrompt] })

const match = result.text.match(/```knowledge\n([\s\S]*?)```/)
if (match) {
    await writeFile("data/knowledge/domains/tracing.md", match[1].trim())
}

Next boot, boot.vue loads the file. The agent arrives pre-oriented — it starts from where it left off, not from scratch.

The folder — durable everywhere

In cloud deployments, data/ is backed by durable storage transparently. The agent calls writeFile the same way locally and in production; no storage SDK, no environment checks. The folder is not just source — it is live runtime state.

The progression

Most agents are stateless execution units. Axon agents can compound:

1. Passive persistence — traces written automatically; the agent remembers what happened.
2. Active accumulation — scripts write knowledge; memory grows deliberately.
3. Capability expansion — policy permitting, the agent writes a new tool or installs a module. Next session it can do something it couldn't before.
4. Shared state — the .agents/ workspace standard lets knowledge and tools be shared across every agent working the same repo.

None of these require implementing anything. The folder is the interface; the agent writes files; the runtime handles the rest.