data/

data/ is the durable storage root for everything that grows, changes, or gets written during execution — material the agent accumulates over time rather than authored behavior.

data/
├── knowledge/      # reference material the agent reads
├── sessions/       # thread history — written by Axon
├── state/          # persistent working state across sessions
├── workspace/      # scratch space: cloned repos, working trees, temp output
└── modules/        # module-managed persistent state

Keep the distinction clean: if a file tells the agent who it is or how to behave, it belongs in src/. If a file is durable material the agent consults or writes during work, it belongs in data/.

AXON_HOME

Every capsule gets AXON_HOME injected automatically — the absolute path to the agent's own directory. Use it to construct stable paths to data/ from anywhere in your tools or scripts, regardless of what working directory the capsule happens to be in.

const dataPath = `${process.env.AXON_HOME}/data`
const workspacePath = `${process.env.AXON_HOME}/data/workspace`
const statePath = `${process.env.AXON_HOME}/data/state`

This means agents always know where home is — in local dev, in deployment, across reboots.

knowledge/

Reference material the agent can read. Commit anything here that should be available across sessions: architecture docs, API contracts, codebase conventions, runbooks, decision logs.

data/knowledge/
├── architecture.md
├── api-contracts.md
├── conventions.md
└── decisions/
    ├── 2025-06-db-schema.md
    └── 2025-05-auth-flow.md

The agent doesn't automatically read everything in knowledge/ — a prompt or script directs it to read specific files when relevant. The value is having authoritative reference material on disk, in the repo, versioned with the codebase.

In the .agents/ workspace layer, data/knowledge/ is the canonical location for project-level reference material shared across all agents in the repo.

sessions/

Written entirely by Axon. Thread logs, conversation history, and continuity data live here, organised by session and thread ID.

data/sessions/
└── <session-id>/
    └── threads/
        └── <thread-id>/

Don't write to sessions/ manually. Don't depend on its internal structure in your code. Axon manages it — the format may change between versions.

state/

Persistent working state the agent writes and reads across sessions. Use this for anything that needs to survive a reboot but isn't reference material — scan results, open proposals, sync cursors, computed summaries.

data/state/
├── coverage.json       # last known coverage snapshot
├── proposals.json      # open proposals awaiting human review
└── last-run.json       # metadata about the last execution

Unlike sessions/ (managed by Axon) and knowledge/ (written by humans), state/ is owned by the agent. It reads and writes it freely as part of its work.

The human can inspect it at any time — keep it in plain JSON or Markdown so it's readable without tooling.

workspace/

The agent's scratch space. Clone repos here, check out working trees, write intermediate output, run builds. Anything that needs a real filesystem path during a work session.

data/workspace/
├── my-target-repo/     # cloned for the current task
└── audit-output/       # intermediate files from a multi-step run

Think of it as the agent's equivalent of a developer's ~/projects/ — a place to put things being actively worked on. Use AXON_HOME to anchor paths here:

const repoPath = `${process.env.AXON_HOME}/data/workspace/my-target-repo`
await process.run(`git clone https://github.com/org/repo ${repoPath}`)

workspace/ is not committed. It's ephemeral relative to data/ as a whole — the agent can treat it as a temp dir that persists across sessions but is safe to delete and regenerate. Don't put anything irreplaceable here; put irreplaceable output in state/ or knowledge/.

modules/

Module-managed persistent state, namespaced by module name. If an installed module needs to persist data — a cache, a sync cursor, indexed content — it writes here.

data/modules/
└── @axon/
    └── github/
        └── webhook-cursor.json

Each module owns its subdirectory. Don't write to another module's namespace.

Persistence in deployment

In local agents, data/ is files on disk. In deployed agents on Axon Cloud, data/ is backed by durable storage — every write the agent makes inside data/ persists across restarts and redeployments. Self-hosted deployments need to mount persistent storage to the data/ directory to get the same behaviour.

Anything written outside data/ during execution is ephemeral in deployed environments. Write durable output to data/.