Local database schema

Everything OOMU stores, and how. All of it lives on your Mac.

---

1. Encryption

The database is encrypted with SQLCipher. Every connection opens with:

PRAGMA key='<key>';
PRAGMA cipher_memory_security=ON;
PRAGMA foreign_keys=ON;
PRAGMA secure_delete=ON;

• The key is held in the macOS Keychain, under a service namespace specific to Beta 2. It is never written to disk in plain text and never transmitted.
• cipher_memory_security wipes sensitive pages from memory.
• secure_delete overwrites deleted content rather than merely unlinking it.
• After opening, OOMU verifies the database is actually encrypted before proceeding. Failure raises data_encryption_failed rather than continuing against a readable file.

A copied database file is not enough to read your data. The key is bound to your Keychain, on this Mac.

What is not in here

Secrets. API keys, OAuth refresh tokens, and channel bot tokens live in the Keychain. The database stores only an opaque reference (credential_ref, account_binding_digest) plus non-secret metadata.

---

2. Schema conventions

Every table is written with constraints rather than trusting the caller.

The last is worth dwelling on. Illegal states are rejected by the database, not just avoided by the code above it.

---

3. Projects

---

4. Chat

completed_turns and accepted_turn_routing are keyed by turn_id and store a request digest, which is what makes a turn replay-safe.

---

5. Activity and evidence

activity_records is one row per turn, with a state of queued, routing, running, verifying, completed, failed, or recovery_required.

Its constraint is the interesting part:

• completed requires receipt_count > 0, an evidence_digest, and no failure category.
• failed requires receipt_count = 0, no evidence digest, and a failure category from routing, local_model, cloud_service, native_execution, persistence, setup, or unknown.
• Any other state requires no receipts, no evidence, and no failure category.

A turn cannot be recorded as completed without evidence behind it. The database refuses the row.

---

6. Ledger

Token counts are nullable, but only together: a row cannot have input tokens without output tokens. Where a cloud provider did not return usage, the interface reports it: "{count} cloud responses did not include token totals." It does not estimate.

---

7. Agents

---

8. Workflows and schedules

The uniqueness constraint on (routine_id, scheduled_for_ms) is what makes scheduled execution exactly-once across restarts. The lease token is what stops two processes claiming the same routine.

workflow_instances references workflow_graphs with ON DELETE RESTRICT: a graph version with runs against it cannot be deleted, so history never dangles.

---

9. Documents produced

artifact_inspections deliberately holds no filesystem path. The preview is addressed by content key, so a preview record cannot leak where a file lives.

---

10. Connections

mcp_setup_secret_cleanup_obligations exists so that a secret whose connection is removed is recorded as needing removal from the Keychain, and cannot be forgotten because the delete happened between two failures.

---

11. Models and providers

Recording device, inode, and modification time alongside the hash means OOMU can tell a model file that moved from one that was replaced.

---

12. Mods

Trust state and integrity state are separate columns because they answer different questions: who signed it, and do the files still match.

---

13. Memory and profile

Every memory record carries its provenance. A saved fact can always be traced to the turn that produced it.

---

14. Mutation journal

data_mutations records one row per durable change:

This is what makes the bridge idempotent. Replaying an operation_id returns the recorded result rather than repeating the change.

---

15. What is stored outside the database

---

Related

• Application Bridge API: the commands that read and write this.
• Privacy & security: the reasoning behind the layout.
• Enterprise security: exporting the audit ledger.