Reference for the local SQLite storage that holds your assistants, conversations, settings, and installed capabilities. Everything in this document lives on your Mac.
1. Storage model
OOMU uses two SQLite databases inside your private workspace (app_data_root, under ai.eldris.oomu.gpd):
| File | Purpose |
|---|
oomu_state.sqlite | Primary application state; assistants, providers, capabilities, conversations, routing, workflows, agentic execution records, and the delegated-work loop (Projects, Tasks, Routines, connectors, artifacts, automation, media, remote access, capability bundles, learning). |
oomu_ops.db | Operational records kept separate from your working data. |
1.1 Protection
- Encryption. Sensitive rows carry an
encryption_state column describing how their contents are protected. The database key is derived from a device secret stored in the macOS Keychain; it is never written to disk in the clear and never leaves your machine. The key is resolved once and cached for the session. - Journal mode. Databases run in WAL (write-ahead logging) mode for durability and concurrent reads.
- Integrity.
PRAGMA foreign_keys = ON is enforced; JSON columns are validated with json_valid(...) checks; schema upgrades are applied as additive migrations on startup.
Because the key is bound to this device's Keychain, the database is only readable by OOMU on the machine that created it.
2. Assistants & providers (oomu_state.sqlite)
agent_configs
One row per assistant you create.
| Column | Type | Notes |
|---|
id | TEXT | Primary key. |
name | TEXT | Assistant's display name. |
system_prompt | TEXT | Compiled working instructions / role. |
model_id | TEXT | The model this assistant uses. |
provider_id | TEXT | Provider; defaults to local_model. |
description | TEXT | Optional description. |
image | TEXT | Optional avatar. |
personality_profile | TEXT | JSON profile (tone, traits, identity). Defaults to {}. |
favorited | INTEGER | 0/1. |
status | TEXT | e.g. active. |
created_at_ms, updated_at_ms | INTEGER | Timestamps (epoch ms). |
agent_mods
Join table binding capabilities to assistants. A Mod affects an assistant only when bound here and globally active.
| Column | Type | Notes |
|---|
agent_id | TEXT | FK → agent_configs(id), ON DELETE CASCADE. |
mod_id | TEXT | The bound Mod. |
| | Primary key (agent_id, mod_id). |
provider_configs
One row per configured cloud provider.
| Column | Type | Notes |
|---|
id | TEXT | Primary key. |
provider_id | TEXT | Catalogue provider id (e.g. anthropic, gemini, openai). |
provider_name | TEXT | Display name. |
auth_method | TEXT | e.g. api_key. |
base_url | TEXT | Provider endpoint base. |
api_key_label | TEXT | Label for the key field. |
api_key | TEXT | The API key (stored in the encrypted database). |
custom_model_ids | TEXT | User-supplied model ids. |
auto_route_target | INTEGER | 1 if this provider is the Auto-Route escalation target. A partial unique index enforces at most one target, and a local provider cannot be set as the target. |
created_at_ms, updated_at_ms | INTEGER | Timestamps. |
3. Installed capabilities (oomu_state.sqlite)
installed_mods
One row per installed .oomu capability package (see Capability Package Specification).
| Column | Type | Notes |
|---|
id | TEXT | Primary key; the manifest id. |
name | TEXT | Display name. |
description | TEXT | Plain-language description. |
is_active | INTEGER | Global active toggle (0/1). |
version | TEXT | Manifest version. |
author | TEXT | Publisher. |
category | TEXT | Declared or inferred category. |
package_size | TEXT | Display size label. |
last_updated | TEXT | Display date label. |
permissions_json | TEXT | JSON array of {label, detail}; json_valid enforced. |
endpoints_json | TEXT | JSON array; json_valid enforced. |
installed_path | TEXT | On-disk install location in the workspace. |
manifest_json | TEXT | Full manifest; json_valid enforced. |
default_system_prompt | TEXT | Optional prompt applied when bound. |
entrypoint | TEXT | Engine file name. |
installed_at_ms, updated_at_ms | INTEGER | Timestamps. |
Indexed by (is_active, name COLLATE NOCASE) for the Mods list.
4. Routing & session preferences (oomu_state.sqlite)
routing_preferences / app_preferences
General key/value preference stores. routing_preferences holds routing/maintenance keys; app_preferences holds application preferences such as the active interface locale and the default pre-warmed local model.
| Column | Type | Notes |
|---|
key | TEXT | Primary key. |
value | TEXT | Serialized value. |
updated_at / updated_at_ms | INTEGER | Timestamp. |
encryption_state | TEXT | Protection state. |
user_routing_preferences
Primary/fallback engine routing (see Smart Model Routing).
| Column | Type | Notes |
|---|
key | TEXT | Primary key. |
primary_route_id | TEXT | Preferred engine. |
fallback_route_id | TEXT | Engine used when the primary is unavailable. |
updated_at | DATETIME | Defaults to current timestamp. |
active_session_configs
Per-session overrides for reasoning and context.
| Column | Type | Notes |
|---|
session_id | TEXT | Primary key. |
reasoning_depth | TEXT | Defaults to medium. |
context_budget | INTEGER | Defaults to 2048. |
model_id, provider_id | TEXT | Optional per-session engine. |
updated_at | DATETIME | Defaults to current timestamp. |
5. Conversations (oomu_state.sqlite)
chat_sessions
| Column | Type | Notes |
|---|
id | TEXT | Primary key. |
agent_id | TEXT | Owning assistant. |
title | TEXT | Session title. |
provider_id, model_id | TEXT | Engine used. |
web_grounding_override | INTEGER | Per-session web grounding override (nullable). |
created_at_ms, updated_at_ms | INTEGER | Timestamps. |
encryption_state | TEXT | Protection state. |
chat_messages
| Column | Type | Notes |
|---|
id | INTEGER | Primary key (autoincrement). |
session_id | TEXT | Owning session. |
agent_id | TEXT | Assistant. |
role | TEXT | user / assistant / etc. |
content | TEXT | Message text. |
timestamp_ms | INTEGER | Timestamp. |
encryption_state | TEXT | Protection state. |
message_queue
Queued messages awaiting execution (with provider/model/reasoning/steering metadata, status, and error tracking).
6. Agentic execution records (oomu_state.sqlite)
These tables back OOMU's approval-gated planner; the path taken when a request needs local actions.
| Table | Holds |
|---|
intents | Parsed intent for a plan (plan_id, prompt, metadata). |
actions | Individual tool actions within a plan (tool, input, output, status). |
certificates | Logical certificates attesting to actions (mlc_path, mlc_content), FK → actions. |
plan_generation_states | In-progress plan state (plan_json, current_step_index, status). |
agent_execution_logs | Structured execution log lines (execution_id, phase, level, message). |
7. Workflows (oomu_state.sqlite)
The workflow system stores its definitions, runs, approvals, and schedules here. Workflows are composed from a capability catalogue and compiled to a node-based IR (see Building Automated Workflows).
| Table | Holds |
|---|
workflows | Legacy/simple workflow records (name, steps). |
workflow_blueprints | Versioned workflow definitions (visual_state_json, workflow_ir_json, compilation_status). Primary key (workflow_id, version). |
compiled_instructions | Per-node compiled instructions (node_kind ∈ input/agent/router/permission/output, system_prompt, mappings). |
execution_instances | Workflow runs (status ∈ Pending/Running/Paused/Completed/Failed, payloads, memory). |
workflow_approvals | Records of approval-gate decisions during a run (approval_token, workflow_instance_id, node_id, target_tool_name, arguments_hash, decision ∈ approve/deny, expires_at). |
workflow_schedules | Scheduled runs (schedule_expression, next_run_at_ms, is_active). |
The IR node kinds are: input, agent, router, conditional, loop, permission, mcp_tool, system_action, and output.
8. The delegated-work loop (oomu_state.sqlite)
Migrations 0010–0024 add the tables behind Projects, Tasks, Routines, connectors, artifacts, automation, media, remote access, capability bundles, and learning. Many domain tables carry a nullable project_id so legacy rows remain valid. This is a map of the surface, not a column-by-column dump; the migration files are authoritative.
Projects (0010)
| Table | Holds |
|---|
projects | The Project boundary (name, description, archived/deleted state). |
project_sources | Approved knowledge folders and their indexing state. |
project_instructions | Standing per-Project instructions. |
project_policy | The data policy: local_only, ask_before_cloud, or allow_configured_cloud. |
project_policy_decisions | Recorded policy decisions (no private content logged). |
Tasks (0011)
| Table | Holds |
|---|
task_runs | The canonical task registry; Task/Run id, project, runtime kind, owning-runtime reference, state, origin, timestamps, correlation. |
task_events | Ordered, reconnectable task events (Sprint-224 envelope). |
task_effects | Idempotency records for effectful steps (so retries never repeat a confirmed effect). |
task_recovery_audit | Startup reconciliation decisions and user-visible next actions. |
Connectors & onboarding (0012, 0017)
| Table | Holds |
|---|
connector_accounts / connector_account_metadata | Connected accounts; only opaque credential references and non-secret metadata (secrets stay in the Keychain). |
connector_oauth_attempts | In-flight OAuth (PKCE) attempts. |
connector_project_bindings | Which connectors are enabled for which Project. |
connector_metadata (Microsoft) | Microsoft 365 connector configuration (0017). |
setup_progress / setup_sample_tasks | The resumable first-run setup state machine and its sample task. |
activation_receipts | Signed receipts proving a capability was really activated. |
Routines, background helper & channels (0013)
| Table | Holds |
|---|
routine_runs | Registered runs of a Routine (also projected into task_runs). |
routine_authority_grants | Task/project-scoped preauthorization for headless consequential actions. |
routine_delivery_receipts | Delivery success/failure for channel notifications. |
routine_remote_approvals | Approvals issued from a messaging channel. |
scheduler_owner_lease / background_service_state | Single-owner background-helper lease and status. |
channel_configs | Signal/Telegram/WhatsApp/Discord configuration and authorized owner. |
gateway_message_receipts | Inbound/outbound channel message receipts. |
Browser automation (0014)
| Table | Holds |
|---|
browser_automation_sessions / browser_automation_actions | Guarded browser sessions and their reference-based actions. |
browser_download_quarantine | Downloaded files held in quarantine until validated and approved. |
Artifacts; DOCX/PDF, XLSX, PPTX (0015, 0018, 0019)
| Table | Holds |
|---|
artifact_records / artifact_versions / artifact_source_links / artifact_exports | Word/PDF artifacts, versions, provenance links, and signed exports. |
workbook_records / workbook_revisions / workbook_source_links / workbook_exports / workbook_template_imports | Excel workbook pipeline. |
presentation_records / presentation_revisions / presentation_source_links / presentation_exports / presentation_template_imports | PowerPoint pipeline. |
Delegation & trust UX (0016)
| Table | Holds |
|---|
delegation_plans / delegation_child_runs | Parent plans and their bounded read-only child workstreams (helpers). |
reviewed_approval_scopes / approval_scope_audit | Reusable, audited approval scopes for the trust UX. |
| Table | Holds |
|---|
media_assets / media_asset_relationships | Voice, image, and screenshot assets and their derivatives. |
media_transcripts / media_interpretations / media_evidence | Transcripts, vision interpretations, and provenance. |
Remote dispatch (0021)
| Table | Holds |
|---|
remote_devices / remote_pairing_challenges | Paired devices (revocable public identity only) and pairing challenges. |
remote_commands / remote_audit_receipts | Signed, scoped, nonce-bound remote commands and their audit trail. |
remote_artifact_grants | Expiring, encrypted access to a result for a paired device. |
Capability bundles (0022)
| Table | Holds |
|---|
capability_bundle_records / capability_bundle_receipts | Installed bundles and transactional install/rollback receipts. |
capability_registry_entries | Curated registry entries (signing and review status kept distinct). |
capability_runtime_denials | Runtime records of undeclared/revoked capabilities that failed closed. |
Adaptive learning & analysis (0023, 0024)
| Table | Holds |
|---|
saved_methods / saved_method_versions | Reviewed, versioned, reversible task recipes. |
learning_offers | Candidate learnings awaiting your review (nothing self-promotes). |
analysis_runs / work_graph_suggestions | The analysis workbench and bounded work-graph suggestions (0024). |
9. Trust & grounding (oomu_state.sqlite)
Sovereign Trust
Directory-scoped trust policies that govern what OOMU may do in a given folder, with resource budgets. See Privacy & Sandboxing.
| Table | Holds |
|---|
sovereign_trust_policies | Per-directory policy: directory_path / canonical_directory_path, allowed_tool_categories (JSON), permission_level ∈ one_time/session_gated/global_trust, expires_at_ms, and daily budgets (daily_token_cost_limit, daily_cpu_seconds_limit) with usage counters. |
active_trust_sessions | Time-boxed grants derived from a policy (session_id, policy_id, directory_path, allowed_tool_categories, expires_at_ms, daily budgets/usage). |
Grounding & memory
| Table | Holds |
|---|
grounding_cache | Cached results from web-search grounding. Committed long-term memories must cite a cache entry, so every remembered fact has traceable provenance. |
global_memory | Committed cross-session insights (insight, channel, source_cache_id → grounding_cache, embedding_json, logical_certificate, ledger_signature). |
10. Operations database (oomu_ops.db)
Kept separate from your working data.
| Table | Holds |
|---|
license_compliance_telemetry | Append-style compliance records (hashed hardware id, masked IP, ASN, signed). |
compliance_beacon_delivery_cache | De-duplication cache for compliance beacons (hashed identifiers, last dispatch). |
Compliance beacons can be disabled by the user via the privacy settings; see Privacy & Sandboxing.
