---
title: Overview
description: OMGDB is an embedded document database written in Rust — SQLite's deployment model with a MongoDB-style API, designed so an AI agent can create, understand, debug, and drive it with no external service.
---

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`](/docs/storage/) 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**.

```sh
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
```

```text
$ 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](/docs/install/) 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:

| Invariant | Claim |
| --- | --- |
| **I1 — Text completeness** | `oplog.ndjson` fully determines the logical state; caches and indexes hold **zero** authoritative bits. |
| **I2 — Rebuild equivalence** | Delete every derived artifact and rebuild from the log → **identical query-visible behavior** (same results, same order). Byte-identical *binary* rebuild is an explicit non-goal. |
| **I3 — Export stability** | Canonical export is deterministic: `dump → load → dump` is **byte-identical**. This is the headline, property-tested claim. |

## What's in the box

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

- **[Document database](/docs/data-model/)** — a MongoDB-style value model with a bit-exact canonical codec.
- **[Query engine](/docs/query-operators/)** — `$eq/$gt/$in/$regex/$elemMatch/…`, dotted paths, projection.
- **[Update operators](/docs/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](/docs/aggregation/)** — `$match/$group/$lookup/$facet/$unwind` plus an expression engine.
- **[Indexes](/docs/indexes/)** — ordered secondary indexes for equality, range, and multikey predicates.
- **[Schema validation](/docs/schema-validation/)** — declarative per-collection rules enforced on insert.
- **[Transactions & durability](/docs/transactions/)** — ACID, serialized single-writer transactions, crash recovery, compaction.
- **[Full-text search](/docs/search/)** — typed BM25 with stemming, fuzzy, weighted fields, highlights; semantic and hybrid modes from pinned local models.
- **[Vector search](/docs/vector-search/)** — a pluggable embedder, flat cosine kNN, hybrid search, persisted/synced vectors.
- **[Context packs](/docs/context-packs/)** — token-budgeted, cited retrieval bundles for agent tasks.
- **[Native Markdown](/docs/markdown/)** — import `.md` into typed frontmatter fields and a section tree.
- **[Introspection](/docs/introspection/)** — `describe`, `dump`, `verify`, `explain`, `diagnose`.
- **[Agent-safe mutations](/docs/agent-mutations/)** — dry-run `plan-update`, `apply` by token, `rollback`.
- **[MCP server](/docs/mcp/)** — 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](/docs/cli/).
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](/docs/mcp/).

> 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](/docs/architecture/) for the full
map.

| Crate | Responsibility |
| --- | --- |
| `omgdb-core` | Value model, canonical codec, op-log, replay, transactions, indexes, compaction, verify |
| `omgdb-query` | Filter compilation & matching, value ordering, projection, explain, diagnose |
| `omgdb-agg` | Aggregation pipeline: stage dispatch + expression engine |
| `omgdb-change` | Agent-safe mutations: dry-run plans, apply-by-token, rollback |
| `omgdb-introspect` | Schema inference, `describe` (live Markdown manual), `dump` |
| `omgdb-md` | Native Markdown parsing (frontmatter + section tree) |
| `omgdb-vector` | Embedders, verified local models, named/chunked exact vectors, context packs |
| `omgdb-search` | Typed search AST, analyzers, deterministic BM25, semantic & hybrid fusion |
| `omgdb-cli` | The `omgdb` binary + the MCP server |

## Next steps

New here? Start with **[Install & build](/docs/install/)**, then walk the
**[Quickstart](/docs/quickstart/)** from an empty folder to an agent-ready database.