OMGDB
The local-first database agents can actually understand.
Store documents, Markdown, vectors, schemas, history, and debug metadata in one inspectable database — with full-text, semantic, and structured search built in. Built for local AI apps, coding agents, and offline-first tools.
Agents should not have to guess your database.
Most databases were designed for apps, admins, and query engines. AI agents need more: schema context, query explanations, safe mutations, semantic retrieval, and structured errors they can repair from.
One local store. Six native layers.
Document Database
Flexible JSON-like documents, Mongo-style filters, aggregation, validation, and transactions.
Markdown Knowledge
Import docs, specs, notes, and AGENTS.md-style project context as structured, queryable documents.
Full-Text Search
Typed BM25 search with stemming, fuzzy matching, weighted fields, and highlighted snippets — the index definition lives in the op-log like everything else.
Vector Search
Generate and search embeddings locally, with provenance and stale-state tracking — and hybrid ranking that fuses text and semantic scores.
Agent Debug APIs
describe, inspect, explain, validate, dry-run, rollback, and query debugging built into the database.
MCP Native
Expose database tools directly to coding agents through a first-class MCP surface.
From empty folder to agent-ready database.
$ omgdb create app.omgdb created store at app.omgdb
▸ One command, one directory. No server to start, nothing to configure.
$ omgdb insert app.omgdb users {"name":"ada","age":36,"role":"admin"} {"$oid":"6a54f45689b9f58fd8000000"} $ omgdb insert app.omgdb users {"name":"lin","age":29,"role":"dev"} {"$oid":"6a54f456311680eac8000000"}
▸ Mongo-style documents in, ObjectIds back.
$ omgdb find app.omgdb users {"age":{"$gte":30}} {"_id":{"$oid":"6a54f45689b9f58fd8000000"},"name":"ada","age":36,"role":"admin"}
▸ Familiar filter operators, straight from the CLI.
$ cat app.omgdb/oplog.ndjson {"lsn":0,"ts":{"$date":1783952470530},"op":"insert","ns":"users","id":{"$oid":"6a54f45689b9f58fd8000000"},"doc":{"_id":{"$oid":"6a54f45689b9f58fd8000000"},"name":"ada","age":36,"role":"admin"}} c1c4258b {"lsn":1,"ts":{"$date":1783952470766},"op":"insert","ns":"users","id":{"$oid":"6a54f456311680eac8000000"},"doc":{"_id":{"$oid":"6a54f456311680eac8000000"},"name":"lin","age":29,"role":"dev"}} 4a8f984f
▸ The single source of truth is an append-only NDJSON op-log, one checksummed record per line. cat is a debugger.
$ omgdb update-one app.omgdb users {"name":"lin"} {"$set":{"role":"lead"}} {"matchedCount":1,"modifiedCount":1}
▸ Immediate Mongo-style updates, atomic and fail-closed. The change appends a replace record inside a transaction frame — the log keeps history, not overwrites.
$ rm app.omgdb/*.cache # delete every derived cache $ omgdb find app.omgdb users {"role":"admin"} {"_id":{"$oid":"6a54f45689b9f58fd8000000"},"name":"ada","age":36,"role":"admin"}
▸ Every index and cache is derived and disposable. Delete them all — the database rebuilds from the log and answers anyway.
$ omgdb verify app.omgdb OK: 5 record(s), 2 document(s) in 1 collection(s); log reproduces state metadata cache: OK (0 collection spec(s), 0 index definition(s), derived) metadata checkpoint+tail: OK (0 tail record(s), derived) primary _id cache: OK (2 entry(s), derived) primary _id checkpoint+tail: OK (0 tail record(s), derived) secondary index cache: OK (0 index(es), 0 bucket(s), derived) live document cache: OK (2 document(s), derived) document checkpoint+tail: OK (0 tail record(s), derived)
▸ verify re-proves the entire database — every record, every derived cache — and attests each one.
captured from a real session, omgdb 0.0.0
Built for tools that think before they write.
Self-Describing
Produces an agent-readable manual of its collections, schemas, indexes, vector state, and constraints.
Why-No-Results
Debug empty queries by showing which predicate failed and what nearby values exist.
Dry-Run Mutations
Preview changes before applying. Show matched documents, before/after samples, and risk notes.
Undoable Changes
Track agent writes with provenance and rollback metadata.
Context Packs
Return token-budgeted context for the model instead of dumping raw documents.
No benchmark theater. Honest trade-offs.
These are different tools with different contracts. Here is where OMGDB actually sits — including what it does not do yet.
VS SQLITE + JSON1
▸ Same deployment model: an embedded library and a local file. No server, no daemon, no port.
▸ A document-native API and an op-log you can read with cat — not JSON strings inside opaque binary pages.
! At raw scan scale, mature engines are still faster today.
VS MONGODB
▸ The familiar query surface — insert, find, update operators, aggregation pipelines — without running a server.
▸ The whole database is one directory you can copy, diff, and back up like any other file.
! No replication, no sharding. This is an embedded store, not a cluster.
VS VECTOR DATABASES
▸ Vectors live next to the documents that produced them, with provenance and staleness tracking. No second service to keep in sync.
▸ Semantic search, filters, and context packs come from the same store that holds the source documents.
! Flat exact kNN today — no ANN index yet.
One database. CLI, TypeScript, Python.
$ omgdb describe app.omgdb # collections, inferred schema, indexes, samples → $ omgdb verify app.omgdb # re-reads the log, proves it reproduces state → $ omgdb diagnose app.omgdb users '{"role":"admin","age":{"$gt":90}}' # why-no-results: predicate age > 90 eliminated all →
// @omgdb/client — real driver protocol, not CLI parsing. In final testing; // ships with the first public release. ESM + CommonJS, zero runtime deps. import { OmgdbClient } from "@omgdb/client"; await using db = await OmgdbClient.connect("./data", { scope: "read-write" }); const users = db.collection<{ name: string; age: number }>("users"); await users.insertOne({ name: "Ada", age: 36 }); await users.updateOne({ name: "Ada" }, { $set: { active: true } }); const rows = await users.find({ age: { $gte: 18 } }).toArray(); // one ordered program, one atomic commit — steps read earlier writes await db.transaction([ { operation: "insert", arguments: { collection: "users", document: { _id: 1, name: "Lin" } } }, { operation: "replace", arguments: { collection: "users", id: 1, document: { _id: 1, name: "Lin Wu" } } }, ]);
# omgdb for Python — sync and native-asyncio clients over the same versioned # stdio driver protocol. In final testing; ships with the first public release. from omgdb import OmgdbClient with OmgdbClient("./app.omgdb", scope="read-write") as db: users = db.collection("users") inserted = users.insert_one({"name": "Ada", "age": 37}) users.update_one({"name": "Ada"}, {"$set": {"active": True}}) with users.find({"age": {"$gte": 18}}, batch_size=100) as cursor: for user in cursor: print(user) # async? AsyncOmgdbClient — same API, native asyncio subprocess.
Readable by default. Fast when it matters.
Built for the tools you're building now.
Agent memory & context stores
Give a coding agent durable memory over MCP. Plan a change, apply it as one transaction, roll it back if the plan was wrong — with provenance on every write.
Local tools that outgrew JSON files
Keep the human-readable file you can still grep — and gain schema validation, secondary indexes, and transactions on top of it.
RAG prototypes without extra services
Import Markdown with import-md, embed and sync vectors with vsync, and hand the model a token-budgeted context pack. One store, no second service.
Build local AI apps without teaching your agent the database from scratch.
OMGDB is early, local-first, and built in the open.