filesystem

Filesystem components

The relational half of an agent points at config; the on-disk half lives under the install root. The layout is organized by scope, not one flat tree: instance-wide state, cross-agent shared resources, and per-agent private data each get their own top-level directory.

<install>/
├── data/                         — instance-wide state (not per-agent)
│   ├── sessions/                 — chat session stores
│   │   └── sessions.db, acp-sessions.db
│   ├── state/                    — runtime state
│   │   └── costs.jsonl, runtime-trace.jsonl
│   ├── devices.db                — paired-device metadata
│   └── memory/                   — shared instance memory
│       └── brain.db, audit.db, response_cache.db,
│           MEMORY_SNAPSHOT.md, archive/
├── shared/                       — resources agents draw on in common
│   └── skills/<bundle>/          — skill bundles
│       └── SKILL.md, scripts/, references/, assets/
└── agents/                       — per-agent private data
    └── <alias>/
        └── workspace/            — the agent's jailed filesystem sandbox
            └── memory/
                └── brain.db

The three roots map to three scopes:

• data/ holds state that belongs to the whole install, not to any one agent: chat sessions/, runtime state/ (cost tracking and the like), the paired-device metadata in devices.db, and the shared instance memory under data/memory/. Valid gateway bearer tokens remain config state; devices.db makes paired devices visible and manageable.
• shared/ holds resources agents draw on in common, notably skill bundles under shared/skills/<bundle>/.
• agents/<alias>/ holds everything private to one agent. By default an agent's workspace is <install>/agents/<alias>/workspace/, and everything the agent reads or writes stays inside it. The agent's identity source is resolved relative to this workspace. Agents are jailed to their own workspace unless you explicitly grant cross-agent access.