Storage Layout

Xenocept’s AeorDB store organizes data into a deliberate path tree. Treat these paths as stable but private — consumers should use the Xenocept HTTP API, not the underlying store paths.

The On-Disk File

A single file:

xenocept.aeordb

The directory it lives in is resolved by Tauri’s app_data_dir at startup and depends on platform conventions (typically under ~/.local/share/, ~/Library/Application Support/, or %APPDATA%). The Settings UI surfaces the active path.

This file contains the entire on-disk Xenocept state: submitted sessions, captured screenshots, settings, destinations, and the index config. Undo/redo state is not in here — undo is in-memory only.

Path Tree

Inside the AeorDB file, paths look like:

/sessions/
  {session-id}/
    session.json # the structured session metadata
    screenshot.png # the submitted (possibly cropped) screenshot
    screenshot-clean.png # optional — background only, no markup
    focus-0.png # one PNG per Note
    focus-1.png
   ...
 .aeordb-config/
    indexes.json # session content index config (see Indexes)

/screenshots/
  {screenshot-id}.png # raw captures saved by the always-on screenshot
                             # export feature (independent of sessions)

/config/
  settings.json # user-facing settings (hotkey, autostart, etc.)
  destinations.json # configured destinations
  auto-send-destinations.json # which destinations auto-send + master enable

/processes/
  active.json # bookkeeping for active subprocess plugins

Sessions

/sessions/{session-id}/session.json is the authoritative artifact of a Submit. See Session for the shape and Session JSON Schema for the schema details.

The session-id is a timestamp string like session-2026-05-15-18-30-00.123. Sorting session IDs lexicographically gives chronological order.

A Submit operation roughly:

Generates a new session-id from the current UTC timestamp.
Decodes and stores screenshot.png (and optionally screenshot-clean.png).
For each Note in the request, decodes and stores focus-{i}.png.
Builds session.json and stores it.
Broadcasts a created event on the internal session-events channel. The Sessions list UI is subscribed via /api/v1/sessions/events.
Auto-send (if enabled) then triggers via the frontend’s plugin loader, which calls POST /api/v1/sessions/{id}/dispatch.

The store write itself produces an entries_created event on AeorDB’s internal event bus — but Xenocept does not currently re-broadcast those events to HTTP consumers. The session-event created broadcast at step 5 is the consumer-visible signal.

Content-Addressed Deduplication

AeorDB stores file content addressed by BLAKE3 hash; identical content chunks are stored once on disk. Two screenshots that share most pixels share most bytes. Two focus-{i}.png files derived from the same screenshot share their backgrounds at the chunk level.

In practice:

A long-running install with many similar captures inflates the database surprisingly little.
Backup is cp xenocept.aeordb /backup/path/.

The HTTP Surface

Use the HTTP API rather than reading the store directly:

Endpoint	Purpose
`GET /api/v1/sessions/list`	List submitted sessions
`GET /api/v1/sessions/search?q=...`	Fuzzy-search submitted sessions
`GET /api/v1/sessions/{id}/meta`	Fetch a session’s `session.json`
`GET /api/v1/sessions/{id}/files/{*path}`	Fetch a session file (e.g. `screenshot.png`, `focus-0.png`)
`GET /api/v1/screenshots/list`	List raw captured screenshots
`GET /api/v1/screenshots/{filename}`	Fetch a raw capture
`GET /api/v1/sessions/events`	SSE stream of session events (`created` / `dispatched`)

Do Not Manually Edit the File

Tooling that edits the .aeordb file outside Xenocept will:

Cause running readers (the Xenocept process, any SSE-subscribed consumer) to misbehave.
Invalidate every content-hash reference for any chunk you touch.

If you need to programmatically modify state, do it through the HTTP API. If the API doesn’t expose what you need, file an issue.

Keyboard shortcuts