Overview

OMGDB is an embedded, serverless document database with a MongoDB-compatible single-node API. It deploys like SQLite — one path on disk, no server to run — and it is built so an AI agent can create, understand, debug, and drive it without any external service. The live store is a directory of legible files; omgdb pack turns it into a single-file .omgdb archive for transport.

The defining idea: the on-disk source of truth is an append-only, human-readable NDJSON operation log (oplog.ndjson) that you can cat. Every index, vector record, and cache is a derived, rebuildable artifact that holds zero authoritative bits. Because the truth is plain text, the database can explain, verify, and repair itself.

omgdb create app.omgdb
omgdb insert app.omgdb users '{"name":"ada","age":36}'
omgdb find   app.omgdb users '{"age":{"$gte":30}}'
omgdb describe app.omgdb      # a Markdown manual of the live DB
omgdb verify   app.omgdb      # re-reads the log and proves it reproduces the state

$ cat app.omgdb/oplog.ndjson
{"lsn":0,"ts":{"$date":...},"op":"insert","ns":"users","id":{"$oid":"..."},"doc":{...}}	7556c941

Status — early project (v0.0). The durability and codec layers are hardened (crash recovery, a repair tool, a bit-exact canonical codec proven by a property test, a crash-truncation matrix, and Linux/Windows/macOS + MSRV CI), but OMGDB is not yet production-ready at scale. See Install & build for the honest list of current limitations.

The three invariants

OMGDB’s thesis is testable, not just a slogan. Three named invariants are enforced and property-tested:

What’s in the box

OMGDB is a single store that natively combines layers most stacks bolt together:

• Document database — a MongoDB-style value model with a bit-exact canonical codec.
• Query engine — $eq/$gt/$in/$regex/$elemMatch/…, dotted paths, projection.
• Update operators — $set/$inc/$push/$addToSet/… with overflow-safe semantics, applied through immediate bounded updates, ordered bulk writes, or the reviewable plan/apply/rollback flow.
• Aggregation pipeline — $match/$group/$lookup/$facet/$unwind plus an expression engine.
• Indexes — ordered secondary indexes for equality, range, and multikey predicates.
• Schema validation — declarative per-collection rules enforced on insert.
• Transactions & durability — ACID, serialized single-writer transactions, crash recovery, compaction.
• Full-text search — typed BM25 with stemming, fuzzy, weighted fields, highlights; semantic and hybrid modes from pinned local models.
• Vector search — a pluggable embedder, flat cosine kNN, hybrid search, persisted/synced vectors.
• Context packs — token-budgeted, cited retrieval bundles for agent tasks.
• Native Markdown — import .md into typed frontmatter fields and a section tree.
• Introspection — describe, dump, verify, explain, diagnose.
• Agent-safe mutations — dry-run plan-update, apply by token, rollback.
• MCP server — expose the engine to agents as JSON-RPC tools with enforced capability scopes.

How you talk to it

There are two real surfaces today, both fully inspectable:

1. The omgdb CLI — one binary covering CRUD, query, aggregation, full-text search, introspection, durability, vectors, and the MCP server. See the CLI reference.
2. The MCP server (omgdb mcp) — a stdio JSON-RPC 2.0 server exposing the engine as agent-callable tools with read / read-write / dangerous capability scopes. See MCP server.

TypeScript and Python clients exist and ride a versioned local driver protocol (omgdb driver) — including immediate updates, bulk writes, and one-request transactions. They are in final testing and ship with the first public release; until then, the supported programmatic surface is the Rust crates, the CLI, and the MCP server.

Architecture at a glance

OMGDB is a Cargo workspace of nine focused crates. See Architecture for the full map.

Next steps

New here? Start with Install & build, then walk the Quickstart from an empty folder to an agent-ready database.