Adapter Registry

The adapters.json file stores adapter configuration and sync state inside the .omnidata directory itself. This makes the container self-describing and portable: anyone who opens the container can see exactly which adapters feed it, when they last synced, and how they are configured.

Schema

The file contains a JSON object with a single adapters key holding an array of adapter entries:

{
  "adapters": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "adapter_name": "filesystem",
      "uri_scheme": "file",
      "version": "0.3.0",
      "sync_interval": 3600,
      "configuration": {
        "watch_paths": ["/Users/daniel/Documents"],
        "ignore_patterns": ["*.tmp", ".DS_Store"]
      },
      "state": {
        "last_sync_at": "2026-03-28T14:00:00Z",
        "watermark": "2026-03-28T13:55:00Z"
      },
      "enabled": true,
      "created_at": "2025-11-15T08:30:00Z",
      "updated_at": "2026-03-28T14:00:00Z"
    },
    {
      "id": "c2d4e6f8-1a3b-5c7d-9e0f-2a4b6c8d0e1f",
      "adapter_name": "tosh",
      "uri_scheme": "tosh",
      "version": "0.2.1",
      "sync_interval": 1800,
      "configuration": {
        "handles": ["+15551234567"],
        "since": "2025-01-01"
      },
      "state": {
        "last_sync_at": "2026-03-28T13:30:00Z",
        "last_message_id": 98432
      },
      "enabled": true,
      "created_at": "2026-01-10T12:00:00Z",
      "updated_at": "2026-03-28T13:30:00Z"
    }
  ]
}

Fields

id

String (UUID v4). Required. The unique identifier for this adapter entry. Generated at registration time.

adapter_name

String. Required. The registered name of the adapter (e.g., "filesystem", "tosh", "chrome-capture", "gdrive"). Must match the name the adapter uses when registering itself with the runtime.

uri_scheme

String. Required. The URI scheme this adapter produces (e.g., "file", "tosh", "chrome-capture", "gdrive"). Used to route resources back to the correct adapter for read_content() calls during pipeline promotion.

version

String or null. The version of the adapter that last synced. Useful for diagnosing issues when an adapter is upgraded and behavior changes.

sync_interval

Integer. Seconds between automatic syncs. Defaults to 3600 (one hour). Set to 0 to disable automatic syncing — the adapter will only run when explicitly triggered.

configuration

Object. Adapter-specific settings. Written at setup time and read by the adapter on each sync. Examples:

• Filesystem: {"watch_paths": [...], "ignore_patterns": [...]}
• Tosh: {"handles": [...], "since": "2025-01-01"}
• Chrome capture: {"capture_screenshots": true, "max_captures_per_day": 100}

state

Object. Mutable sync state maintained by the adapter. This is where watermarks, cursors, and sync progress live. The runtime updates this field after each successful sync with the values returned in SyncResult.watermark.

enabled

Boolean. Whether this adapter is active. Set to false to pause syncing without removing the configuration. The runtime skips disabled adapters during scheduled syncs.

created_at / updated_at

String (ISO 8601 UTC). Standard timestamps. created_at is set once at registration. updated_at is refreshed after each sync or configuration change.

Config travels, code stays

Adapter configuration lives in the container so it is portable. When you copy a .omnidata directory to a new machine, the adapter registry travels with it. The new machine’s runtime can read the registry, discover which adapters are needed, and either resume syncing or report which adapters are missing.

Adapter code (the Python or JavaScript implementation) does not live in the container. It is installed separately on each machine as part of the OmniData runtime or as a plugin. The registry tells the runtime what to run; the runtime provides the code to run it.

This is the config-travels, code-stays pattern: configuration is portable and self-describing, while executable code remains a deployment concern.

Soft deletes

Adapter entries are not hard-deleted from the JSON. To remove an adapter, set enabled to false and add a "deleted_at" field with an ISO 8601 timestamp. Implementations should filter out entries where deleted_at is present when listing active adapters.

Reading the registry

import json
from pathlib import Path

container = Path("director-of-ai.omnidata")
registry = json.loads((container / "adapters.json").read_text())

active = [a for a in registry["adapters"] if a["enabled"] and "deleted_at" not in a]
for adapter in active:
    print(f"{adapter['adapter_name']} — last sync: {adapter['state'].get('last_sync_at', 'never')}")

Migration from v1

In Schema Version 1, the adapter registry was stored as a SQL table (omnidata_adapter_registry) inside the monolithic .omnidata SQLite file. Version 2 extracts this to a standalone JSON file. Migration tooling reads the SQL rows, serializes them to the JSON array format, and writes adapters.json to the new directory bundle.