Aller au contenu principal

Agent storage layout

This page is the desktop-specific binding of the agent storage and recovery contract. The RFC owns the abstract session model; this page records only which Desktop process keeps which files, and why they stay separate.

Owners​

OwnerLocationHolds
Native agent hostA private chat-state directory under Desktop's userDataPer-workspace and per-document runtime state: the SQLite chat store, host configuration, retained attachments and documents.
Retained media sidecarThe canonical Grida agent homerecent.json, workspaces.json, daemon-owned OAuth records (auth.json), and media output under its host-supplied root.
Shared provider custodyOne private provider credential file per Grida home (GRIDA-SEC-014)BYOK API keys shared by native applications.
Electron mainpreferences.json under Desktop's userDataSmall, non-secret Desktop lifecycle preferences such as versioned onboarding completion.
Electron mainMain's ChatGPT subscription host (GRIDA-SEC-008)ChatGPT subscription credentials, separate from every file above.

Gateway grants are memory-only and never written to disk (GRIDA-SEC-006).

Separation rules​

  • Chat state is the native host's alone. The sidecar never opens a chat store, and native command profiles deny the chat-state directory, the sidecar's state, and the shared provider credential root to model commands.
  • Credentials are not user data. Credential files are owner-only and written atomically; chat stores hold user content and are protected by their owner's process boundary instead.
  • Preferences are not agent data. preferences.json never contains account or provider credentials and is outside every agent owner above.

Chat-state ownership​

The chat-state directory is claimed once. Its first use writes a small ownership record that binds the directory to the profile's path facts — the agent home, provider home and media root it was created beside. A later launch opens the directory only when that record matches; a directory that holds anything else, or a record for other paths, is refused rather than adopted. A directory of another name is never consulted, so data that is not the current store is neither read nor changed.

Backups​

Backups are the user's job. A backup helper for any SQLite store MUST use the engine's backup API, not a raw file copy — a copy during a WAL checkpoint risks tearing.

See also​