MDBX Product Specification

Version: MDBX-1-DRAFT

MUST, MUST NOT, SHOULD, SHOULD NOT, MAY follow RFC 2119 semantics.

1. Summary

MDBX is a local-first encrypted password database format and implementation architecture. It targets core KDBX pain points around sync conflicts, large-vault performance, attachment growth, and long-term maintenance.

MDBX MUST keep project as the primary container and MUST natively support attachments at the schema level.

2. Product goals

MDBX MUST provide:

• full offline open/edit/search/export/recovery
• long-term readability, migration, and archival stability
• low-cost small-save behavior and sync deltas
• explicit conflict behavior for multi-device edits
• attachment support without degrading normal edit flows
• modern secure defaults with switchable Tiga modes

3. Non-goals

MDBX does not require:

• a central sync server
• proprietary cloud backend
• always-online collaboration
• undocumented private binary formats

4. Core principles

• Local-first operation is mandatory.
• Compatibility must be preserved across revisions.
• Tiga security modes MUST affect crypto/caching/convenience behavior.
• Git-like history and causal conflict detection are required.
• Real-world save/load/search/sync performance should be measurably better than KDBX.

5. Domain model

5.1 Project-centered model

Secrets are organized by project. A flat password bag model is non-compliant.

5.2 Entry model

entry is a typed record under project (login, note, card, identity, totp, passkey, etc.).

5.3 Attachment model

Attachments are first-class from v1, with stable IDs, ownership, integrity hash, size/media metadata, storage mode, and timestamps.

6. Rejection rules

The following are non-compliant:

• no first-class project
• no first-class attachment model
• daily small edits requiring full-vault rewrite
• server dependency in normal local workflows
• silent auto-merge of conflicting secret-field values