File-based State

OpenAlice has no database. State lives as JSON, JSONL, Markdown, and git repositories under ~/.openalice by default. OPENALICE_HOME selects another user root; Docker maps that root to /data.

Directory structure

<OPENALICE_HOME>/
├── data/                         # portable application data
│   ├── config/                   # validated config + migration journal
│   ├── inbox/                    # immutable delivery records
│   ├── entities/                 # tracked assets and topics
│   ├── trading/                  # UTA history and snapshots
│   ├── news-collector/           # RSS archive
│   ├── tool-calls/
│   ├── media/
│   ├── cache/
│   └── _backup/                  # migration snapshots
├── workspaces/                   # default launcher root
│   ├── workspaces.json           # active runtime registry
│   ├── workspaces/               # active git checkouts only
│   │   └── <wsId>/.alice/issues/
│   ├── departed-workspaces/      # retained offboarded checkouts
│   ├── auto-quant-mirror/
│   └── state/
│       ├── workspace-catalog.json
│       ├── resume-identities.json
│       ├── sessions/
│       ├── scrollback/
│       ├── schedule-markers.json
│       ├── headless-tasks.json
│       ├── headless-logs/
│       └── artifact-provenance.json
├── state/
│   ├── guardian.lock
│   └── runtime.lock
├── provider-keys.json
└── sealing.key

Active and historical state are deliberately separate. workspaces.json says what Alice can run now; the catalog, departed checkout directory, Session identities, run history, and provenance explain what existed before. See Lifecycle & Offboarding.

Root overrides

sealing.key is machine-bound and decrypts broker credentials. A backup that includes it is sensitive; omitting it intentionally makes copied broker config unreadable.

Configuration and migrations

Configuration lives under data/config/ and is validated by schemas. Missing files are seeded with defaults. Many user settings hot-reload, while startup/boundary settings require restart; Configuration Reference documents the difference.

accounts.json is the exception to ordinary hand editing: it is sealed with AES-256-GCM and managed through the Web UI.

Upgrade-time transformations live in src/migrations/, are idempotent, declare their affected paths, and journal completion in data/config/_meta.json. Migrations may touch the Workspace launcher root when the persisted contract lives there. Pre-migration snapshots go under data/_backup/.

Workspace Sessions and provenance

OpenAlice owns product identity while native agent CLIs own their conversation stores:

• resume-identities.json maps durable resumeId values to Workspace/runtime identity;
• per-Workspace Session records own interactive tabs and PTY attachment;
• headless-tasks.json owns one record per async turn and its taskId lineage;
• Claude, Codex, opencode, and Pi keep their native transcript/session formats;
• Pi WebPi renders the same Pi JSONL conversation through RPC rather than copying it into an OpenAlice chat database.

artifact-provenance.json joins Inbox entries, Issue mutations, report revisions, and trade decisions back to their Session. See Sessions & Collaboration.

Issues

Each Issue is a Markdown file inside its Workspace:

<workspace>/.alice/issues/<id>.md
<workspace>/.alice/issues/<id>.comments.json

The document holds board fields, ownership, optional schedule, and canonical What. The sidecar holds stable Markdown comments. Schedule markers stay in launcher state; schedule meaning stays in the Issue. See Issue Board.

Inbox

Inbox entries are append-only JSONL under data/inbox/entries.jsonl. Each entry points to live Workspace documents while retaining publication-time revision and Session/run/Issue provenance. Delete rewrites the file atomically rather than mutating individual lines. See Inbox.

Trading history

UTA owns broker and trading state under data/trading/<accountId>/. Trading-as-Git commits, staged operations, snapshots, approvals, broker orders, and fills remain separate from Alice's Session provenance. A Session can be attributed as the initiator of a decision without moving execution authority out of UTA.

Default and override files

The persona uses a tracked default and a user override:

The override is created on first run and is not silently overwritten by upgrades. Workspace instructions and skills follow the same durable principle: creation snapshots are explicit files and later guidance upgrades should remain diff-visible.

Next Steps

• Data & Credentials — Auth, sealed credentials, backup, and ports.
• Structure — Active/departed Workspace and Session layout.
• Sessions & Collaboration — Product identity and provenance.
• Configuration Reference — Config file schemas and change surfaces.