seekdb: an embeddable MySQL-compatible engine that forks databases for agent sandboxes

The gap seekdb is aimed at: agent state that is written constantly and read milliseconds later

Most retrieval stacks are built for a corpus that changes slowly. You embed documents offline, build an index, and serve queries against a mostly static snapshot. An agent does the opposite. It writes a memory, a tool result or a scratchpad entry, and then reads it back almost immediately, often in the same turn. The README frames this as "continuous write + millisecond-later read" and names the failure it is trying to avoid: the P99 latency spike that appears when index construction sits on the write path.

The target user is fairly narrow. It is someone building an agent or a RAG pipeline who is currently gluing a vector store, a keyword index and a relational table together in application code, and who has started to resent the glue. The README's own framing is "No N+1 client-side merging, no glue code to combine results." If your retrieval is a single vector lookup over a static set of a few thousand chunks, this project is heavier than the problem.

How the write path avoids blocking on index construction

The mechanism the README describes has two parts. First, an async index pipeline it calls Change Stream: DML commits and returns without waiting for index construction. The pipeline consumes the redo log asynchronously and updates a delta index. Second, a two-level HNSW structure, described as incremental plus snapshot, so that newly written vectors are searchable without a full rebuild. Queries then hit both the delta and the snapshot index under fine-grained read locks.

The repository layout backs this up. The README points to src/observer/change_stream/ and src/observer/vector_index/ as the source for the claim. That is the level of detail available here: the directory names exist and are cited, but the material does not include the tuning parameters, the flush thresholds, or what happens when the delta index grows large relative to the snapshot. If you are evaluating this for a production write load, those thresholds are exactly what you need to read in the source, because they determine when a merge stalls your query latency.

The performance claim in the README is specific: "1,523 QPS with 21.7 ms concurrent P99," described as 10.7x the QPS of Milvus and a P99 jitter of 1.1x versus roughly 10x for Elasticsearch and Milvus on the same workload. Treat that as the vendor's number from the vendor's benchmark. The README links a separate repository, oceanbase/vdb-streambench, for reproducing it, which is the useful part: the claim is at least testable rather than asserted.

FORK DATABASE and MERGE TABLE: copy-on-write at the storage layer, not in your application

This is the feature that distinguishes seekdb from a conventional vector database. FORK DATABASE agent_state TO agent_sandbox_42 takes a snapshot of an entire database, and the README states it completes in seconds with no data copy. An agent then writes and queries against the fork. When it is done, MERGE TABLE agent_sandbox_42.memory INTO agent_state.memory STRATEGY THEIRS commits the work back, or DROP DATABASE discards it.

The README is explicit that this is kernel-level copy-on-write rather than application-layer save and restore. That distinction matters for cost. An application-level snapshot means serializing rows and shipping them somewhere, which scales with data size. A storage-level COW fork should scale with metadata, though the material does not give a figure for how fork latency grows as the parent database grows, and that is the number that decides whether this works for a database measured in gigabytes.

The MERGE TABLE syntax exposes a conflict-resolution strategy with at least three documented values: FAIL, THEIRS and OURS. That is a real design decision, not a detail. FAIL means the merge refuses on conflict and the agent's work is not silently lost; THEIRS and OURS mean one side wins. Choosing between them is a policy question about whether the sandbox is an experiment that can be discarded or a branch that carries authority. The README does not say what granularity the conflict is detected at, row or table, and that gap is worth closing before you build a workflow on it.

Getting it running: one pip install, then a decision about deployment mode

The documented entry point is the Python SDK. The README gives exactly one install command: pip install -U pyseekdb. The 30-second example is described as requiring no servers, no schemas and no embedding setup, because embedded mode runs in-process. The README states that switching to server or OceanBase mode is a one-line change, though the material here does not show that line, so the migration path is asserted rather than demonstrated.

A working hybrid query, taken from the README, looks like this:

SELECT id, title, l2_distance(emb, '[0.12,0.34,...]') AS dist FROM docs WHERE MATCH(content) AGAINST('quarterly report') AND author_id = 42 AND created_at > '2026-01-01' ORDER BY dist APPROXIMATE LIMIT 10;

Three things are worth noting in that statement. The vector distance function is l2_distance. Full-text uses MySQL's MATCH ... AGAINST syntax. The ORDER BY clause carries an APPROXIMATE keyword, which signals that the vector search is doing approximate nearest-neighbour traversal rather than exact ordering. That last keyword is the one to understand before you ship, because it is the switch between a fast answer and a correct one, and the README does not document a way to force exact search.

The fork workflow uses plain SQL with no SDK wrapper: FORK DATABASE, USE, INSERT, MERGE TABLE ... STRATEGY THEIRS, DROP DATABASE. The README cites tools/deploy/mysql_test/test_suite/fork_table/ as the test suite for this behaviour, which is where to look for edge cases the prose omits.

Where seekdb is the wrong tool

The README makes a broad claim: "Best for agent storage." That is a positioning statement, not a constraint, and the constraints are what matter.

First, the project is C++ with an OceanBase SQL engine underneath it. The Apache-2.0 licence is permissive, but the operational surface is not small. Running it in server mode means running a database server, which means backups, upgrades and failure handling. Embedded mode avoids that, but embedded mode also means your process and the database share a fate. If the database crashes, so does your agent. The README does not describe crash-recovery guarantees for embedded mode, and that silence is itself a reason to test before depending on it.

Second, the fork feature is only useful if your agent actually needs speculative execution over state. Many agents do not. If your agent writes a memory and reads it back, FORK DATABASE is unused machinery. The complexity is real even when it is dormant.

Third, the material does not establish how seekdb behaves at scale. There is no documented ceiling on database size for embedded mode, no guidance on when to move to server mode, and no published limit on concurrent forks. The README describes three deployment shapes (embedded library, single-node server, OceanBase distributed cluster) without saying what pushes you from one to the next. That is the largest documentation gap in what is available here.

The alternative worth comparing: pgvector on Postgres, and why the trade is different

The obvious comparison is pgvector on PostgreSQL. Both give you SQL, both give you vector search next to scalar filters, and both let you keep structured and unstructured data in one place. The difference is in where the work happens.

pgvector stores embeddings in a column and builds an index with HNSW or IVFFlat. Writes go through the normal Postgres write path, and index maintenance happens as part of that path, subject to Postgres's own vacuum and index-build behaviour. There is no separate async pipeline and no delta-plus-snapshot index split. That is simpler to reason about and simpler to operate, and it inherits everything Postgres already gives you: replication, point-in-time recovery, a mature backup story, and a large pool of people who already know how to run it.

seekdb's answer to the same problem is the Change Stream pipeline and the two-level HNSW, which the README says is what keeps P99 flat under concurrent write and search. If that claim holds on your workload, it is a genuine architectural difference, not a marketing one. The cost is that you are adopting a younger engine with its own operational model. There is no equivalent of a decade of Postgres runbooks.

A second, blunter alternative: if your retrieval corpus is small and static, a local index plus a metadata dictionary in your application is less machinery than either database. The README's own pitch assumes continuous writes and immediate reads. If that is not your workload, the premise does not apply.

Release cadence, licence and what maintenance actually costs

The release history shows v1.2.0 in April 2026, v1.3.0 in May, and v1.4.0 in August, with the last push to master in September. Three minor releases in roughly five months is a fast cadence for a database. Fast cadences cut both ways: fixes arrive quickly, and so do behaviour changes. The README does not include a compatibility policy or a statement about what a minor version is allowed to break, so pinning a version and reading each release note is the safe posture rather than tracking master.

The licence is Apache-2.0, which permits commercial use, modification and redistribution, and includes an express patent grant. That is the permissive end of the spectrum and it is the same licence as PostgreSQL and Kubernetes. It does not, however, tell you anything about the project's governance, whether a foundation holds the trademark, or what happens if OceanBase changes strategic direction. Those are questions the licence text cannot answer. For anything load-bearing, read the contribution and governance files in the repository rather than inferring from the licence badge.

On upgrade cost, the material here is thin. There is no documented migration procedure between v1.3.0 and v1.4.0, no statement about on-disk format stability, and no guidance on whether an embedded database file created by one version opens in the next. Those are the questions to ask before you put agent state in it, because agent state is the kind of data you cannot easily regenerate from a source of truth.

Editorial conclusion

Adopt seekdb if you are building an agent that needs vector, full-text and scalar filters in one query and you want the option to start embedded and move to a server without rewriting your data layer. Do not adopt it if you need a managed service with an SLA, or if your retrieval is small enough that a single-file index and a dict of metadata would do. Before committing, verify three things on your own hardware: that pyseekdb installs and runs in-process on your target platform, that FORK DATABASE and MERGE TABLE behave as the README describes under your write pattern, and that the 1,523 QPS figure from the launch benchmark is reproducible with your embedding dimensions and your concurrency. The benchmark repository is linked from the README, so the check is a clone and a run, not a leap of faith.

Official sources

1. License: Apache-2.0
2. oceanbase/seekdb on GitHub
3. Project website
4. README
5. Releases