Sessions & Persistence

A session is the agent's lifetime — from boot to shutdown. Threads live inside sessions. Requests live inside threads. Understanding what persists at each level is what makes the difference between an agent that executes and one that compounds.

What a session is

When you run axon, a session starts. When you close it, the session ends. Everything that happens in between — every exchange, every tool call, every file written — belongs to that session.

The three session shapes have different lifetimes:

axon                  # TUI — session lasts until you close axon

axon run scout        # Script — session lasts for the duration of one script run

axon deploy           # Cloud — persistent session across all requests

The cloud shape is the one that surprises people. With min: 1 (keep-warm), your agent runs as a single long-lived process — every API call, every incoming request is threaded into that persistent session. With min: 0 (scale to zero, the default), the container restarts on the next request after an idle period. The session restarts too.

What doesn't restart either way: data/. Thread history, knowledge files, and anything the agent has written survive cold starts, restarts, and redeployments. The session is ephemeral. The folder is not.

What persists

Three layers, each with different ownership:

Thread history

The runtime writes every session to data/sessions/ as a JSONL trace — every entry, every tool call, every model output, billing included. Named threads resume with full prior context by loading this trace. This is automatic. You don't manage it.

// run 1
const project = axon.thread("project-alpha")
await project.request("what schema approach should we use?")

// run 2 — next day, same thread name
const project = axon.thread("project-alpha")
await project.request("what did we decide about the schema?")
// agent loads the prior session trace — full context restored

Knowledge files

data/knowledge/ is yours by convention. Scripts write here during execution. The agent reads here at boot. It is deliberate, accumulated memory — the agent mapping 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 that file. The agent arrives pre-oriented. It doesn't start from scratch — it starts from where it left off.

The folder itself

In prod, data/ is backed by GCS. The API is identical. The agent calls writeFile the same way locally and in the cloud — the runtime maps the path to durable storage transparently. No cloud storage SDK. No environment checks. It just works.

This means knowledge accumulated in a prod session survives restarts, redeployments, and scaling events. The folder is not just source — it is live runtime state.

The progression

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

Passive persistence. The runtime writes session traces automatically. Thread history survives. The agent remembers what happened because the JSONL is there.

Active accumulation. Scripts write to data/knowledge/. The agent maps a domain, writes a file, loads it next boot. Memory that grows deliberately over time.

Capability expansion. Policy permitting, the agent writes a new tool to src/tools/ or installs a module. Next session it has a capability it didn't have before. It didn't just remember — it grew.

Cross-session shared state. The .agents/ workspace standard lets knowledge and tools be shared across agents in the same repo. An agent writes a shared tool, another picks it up. Collective memory across a fleet of agents working the same codebase.

Each level builds on the last. None of them require you to implement anything — the folder is the interface. The agent writes files. The runtime handles the rest.