Bundle Format

A .omnidata container is a directory bundle – a directory that behaves like a single file. This pattern comes from macOS, where it has been the standard for packaging complex applications and documents for decades.

The bundle pattern

macOS uses directory bundles everywhere:

Each of these is a directory on disk. But Finder presents them as a single item. You double-click a .app to launch it. You drag a .keynote file to share it. The internal structure is hidden unless you explicitly ask to see it.

How Finder handles bundles

Finder recognizes bundles by their extension and treats them as opaque packages:

• Single-click selects the whole bundle
• Double-click opens the bundle with its default application
• Drag and drop moves the entire directory tree
• Get Info shows a single file size (sum of contents)
• Quick Look previews the bundle’s content

To see inside, right-click and choose Show Package Contents. This opens the directory in a normal Finder window, revealing the internal structure.

The .omnidata bundle

An .omnidata bundle follows the same pattern:

director-of-ai.omnidata/
├── manifest.json       # Identity, schema version, ownership
├── index.db            # Search layer (resources, chunks, embeddings, FTS5, queue, kv)
├── memory.db           # Graph layer (collections, edges, tags, memory records)
├── adapters.json       # Adapter registry and sync state
├── ingress.log         # Append-only ingest operation log
└── blobs/              # Content-addressed binary storage
    ├── ab/
    │   └── ab3f7c9e2d...sha256
    └── c8/
        └── c84d02ee7b...sha256

To the user, director-of-ai.omnidata appears as one item. To the runtime, it is a structured directory where each file has a focused responsibility.

Why a bundle instead of a single file?

The previous design (v0.1.x) stored everything in a single SQLite file. The bundle format solves several problems:

Transport and archival

Bundles are directories, but they travel well:

zip

# Pack for transport
zip -r director-of-ai.omnidata.zip director-of-ai.omnidata/

# Unpack on arrival
unzip director-of-ai.omnidata.zip

tar

# Pack with compression
tar czf director-of-ai.omnidata.tar.gz director-of-ai.omnidata/

# Unpack
tar xzf director-of-ai.omnidata.tar.gz

The bundle structure is preserved exactly. On macOS, the unpacked directory is immediately recognized as a bundle by Finder.

rsync

# Incremental sync to another machine
rsync -av director-of-ai.omnidata/ remote:~/instances/director-of-ai.omnidata/

Because blobs are individual files, rsync only transfers new or changed blobs. This is dramatically more efficient than syncing a single multi-gigabyte SQLite file where one new resource means re-transferring the entire database.

Registering as a macOS bundle type

For Finder to treat .omnidata directories as bundles natively (showing a custom icon, hiding contents by default), the OmniData desktop app registers a UTI (Uniform Type Identifier) that declares .omnidata as a package type. Without this registration, Finder treats it as a regular directory – the contents are still correct, but the user experience is less polished.

Compared to other formats

The .omnidata bundle is closest in spirit to a .git directory: content-addressed objects on the filesystem, with structured metadata alongside them.