.agent/

Everything the runtime generated or recorded, grouped by what it is. Created by axon prepare, added to by axon bundle, and written to while the agent runs.

Authored content sits directly under the agent root. .agent/ is the other half — nothing in here is yours to edit, and the generated parts are rebuilt on every prepare.

.agent/
├── types/          # generated declarations — what your editor reads
├── cognet/         # the compiled brain
├── build/          # deployment artifacts, from `axon bundle`
├── data/           # what the agent RECORDED — sessions, state, senses
├── identity/       # this agent's keypair
└── cache/          # build caches, safe to delete

The split that matters is generated versus recorded. types/, cognet/, build/ and cache/ are rebuilt from your source at any time. data/ and identity/ are not: they are the agent's memory and its name, and deleting them is a real loss.

`types/`

The declarations that give your editor autocomplete on everything the agent can reach.

File	What it declares
`axon.d.ts`	The ambient `axon` handle, `process`, and injected env
`tool-globals.d.ts`	Every tool, as it is callable — `fs.read()`, `add()`
`prompts.d.ts`	`AxonPromptMap` — the names `axon.prompt()` accepts, and each one's props
`scripts.d.ts`	The names `axon.scripts.request()` accepts
`components.d.ts`	Auto-imported components a `.vue` prompt may compose
`env.d.ts`	The keys this agent's `.env` declares
`tsconfig.json`	Extends the agent's own — this is what `axon.config.ts` points at

Run axon prepare after adding a tool, prompt or script to refresh them. Nothing here is read at runtime; it exists entirely for the editor and the typechecker.

`cognet/`

The compiled brain — cognet.mjs plus its sourcemap and a manifest.json describing what it declares. Rebuilt whenever the cognet source or its version changes.

`build/`

Written by axon bundle, not by prepare.

File	What it is
`source.tar.gz`	The agent's source, as the registry and the cloud receive it
`assets.tar.gz`	Its assets, as a separate archive — absent when there are none
`Dockerfile`	A production container image, self-contained
`image.json`	Metadata about a built image: digest, tags, timestamp

`data/`

What the agent recorded. This is the half that is not regenerable.

Folder	What it holds
`sessions/`	One `.jsonl` per conversation — the durable, append-only record
`state/`	Anything the agent persisted across runs
`sensory/`	Bounded windows of dense sense streams, one per session

A session file is the agent's audit trail: every commit, in order, with the sequence numbers that make that order total. Nothing rewrites it — the runtime only ever appends.

`identity/`

agent.id.json — this agent's did:key and its keypair. Created once, on first boot, and never regenerated: it is how this agent is recognised as itself.

Back it up with your source. Losing it means the agent comes back as a stranger.

`cache/`

Build caches — what the tool scanner and bundler already did, so a second prepare is fast. Safe to delete at any time; the cost is one slower prepare.

`.gitignore`

Add .agent/ to your .gitignore — with one exception worth thinking about.

.agent/
!.agent/identity/

The generated half is noise in a diff and a source of merge conflicts. identity/ is not generated, and committing it is how the agent keeps its name across clones. Whether you want that depends on whether the agent is one thing or a template many people run.