Write-once records
Set a key with the WORM flag and normal SET and DEL commands reject changes to it. Use the append-log procedures for Merkle proofs, signed checkpoints, and witness receipts.
TOP OF FORMFICHE ARCHIVE COPY 0x57 0x57 HANDSHAKE OK PAGE 001 · SYSTEM LOG
WRITE ONCE.READ MANY.
An open-source key-value store and embeddable engine in Zig. Keep selected records write-once, run compiled procedures next to your data, and search vectors in the same store. Start with a local server and a Bun client.
Under active development. Read the deployment notes before running beyond localhost.
SET audit:001 ready WORM
OK
GET audit:001
ready
SET audit:001 changed
ERR WORM violation: key is immutable
DEL audit:001
ERR WORM violation: key is immutable
-- 4 statements · 0 rewrites --
PAGE 002JOB CONTROL — EXECCONT'D FROM 001
Bring your logic to the data.
Stored procedures in WormDB are native Zig functions compiled into the server
binary. Call them with one EXEC request over WormWire.
Handlers can work with keys, publish events, and query vectors without a series of
application-to-database round trips.
Built-in handlers cover counters, audit proofs, agent memory, coordination, and vector search. Extend the registry or register procedures from an external domain package when embedding the engine.
Locking and durability are explicit. Some helpers write only to memory until the next snapshot; durable helpers have different locking behavior. Choose the right contract for each handler. Read the procedure guide.
COMPILED HANDLERS · ONE EXEC REQUEST
# inspect stored keys and namespace state EXEC scan audit: EXEC vstats vec:articles: # rebuild a derived vector index from its keys EXEC vreindex vec:articles:
KEYS + COUNTERSkv_put · kv_get · kv_stats · scan · transfer · increment
AUDIT PROOFappend_log_append · verify · mmr_proof · checkpoint · witness ×4 · proof_bundle
VECTORvinsert · vsearch · vsearch_cluster · vsim · vstats · vreindex · vrabitq · vdelete
AGENT MEMORYmem_init · mem_add · mem_query · mem_range · mem_verify · mem_stats
COORDINATIONappend_log_claim · claim_status · claim_release · claim_supersede
TRUST + AUTHtrust_grant · trust_revoke · trust_fold · auth_mint_scoped · cluster_presence
PAGE 003CAPABILITY REPORT[1B OPCODE][4B LENGTH][PAYLOAD]
Keep records. Run logic. Find context.
Build around an append-only audit history, an application event stream, or searchable agent memory. The same engine provides the storage and the operations around it.
A compact binary protocol
WormWire uses a two-byte handshake, an opcode, and length-prefixed payloads. The Bun TCP client and browser WebSocket client handle framing for you; Redis and text clients are not compatible.
Pub/sub that matches prefixes
Subscribe to a channel or prefix and receive matching EVENT frames on the same connection. Use it for application events or to follow vector insert notifications by namespace.
Peer discovery and replication
On Linux, MeshGuard provides peer discovery and failure detection. WormDB replicates committed writes and synchronizes joining peers. Configure trust and transport protection for your network.
Vectors live with your data
Store embeddings as keys, then query a per-namespace HNSW index, a quantized prefilter, or exact search. Cosine, dot product, and L2 metrics use SIMD distance kernels.
Procedures compiled into the binary
Run native Zig handlers with access to the store, events, and cluster. Built-in memory and audit procedures give you a starting point; your handler chooses its locking and persistence behavior.
PAGE 004VECTOR SEARCHKEYS + CONTEXT
Your vectors belong with your records.
Embeddings are ordinary vec:<ns>:<id> keys backed by the write-ahead log.
A derived index accelerates search within each namespace. Native vector inserts and
the Bun vector wrapper default to WORM; mutable vectors are an explicit choice.
- HNSW graphTraverse a per-namespace graph and refine candidates with the selected metric.
- Quantized prefilterRank a smaller candidate set with binary hashes, then refine using the original vectors.
- Exact searchScan the vectors directly when requested or when no suitable index is available.
vsearch searches one node. vsearch_cluster
is the separate fan-out procedure. Rebuild derived indexes with vreindex
after raw ingestion or WAL recovery beyond the last snapshot.
FOLLOW THE DATA
VINSERT / VBULKINSERT write vector keys through the store KV + WAL | derived namespace index | EXEC vsearch query locally, return nearest matches
- Explore vector searchIndex lifecycle, metrics, and query modes.
- Explore agent memoryMemory procedures, retrieval, and verification.
- Run the vector benchmarkMeasure your build and hardware with the included harness.
PAGE 005REPLICATION TOPOLOGY0x05 · CLUSTER STATUS
Start local. Connect peers on Linux.
MeshGuard supplies SWIM gossip, node identity, and WireGuard integration. WormDB adds best-effort replication and full-state synchronization for joining peers.
- Discovery — a new node joins through a seed and learns its peers.
- Trust — configure org-trust grants and node certificates for replication authorization.
- Transport — replication uses TCP; verify that the actual route is protected by a tunnel or another secure transport.
- Write behavior — the local commit is authoritative. Replication failures are logged without failing the client write.
Replication does not provide quorum acknowledgements. Windows currently supports single-node operation.
FOLLOW A WRITE
Client → local node local commit: store + write-ahead log | replication attempts → peers peer failure does not undo local commit | client response
Choose trust and network settings before connecting nodes. Configure replication trust.
PAGE 006INSTALLATIONZIG 0.16.0 + BUN
Run your first write-once record.
Build from source, start on localhost, and try the Bun client. You need Git, Zig 0.16.0, and Bun.
1. Build and start the server
git clone https://github.com/igorls/wormdb.git cd wormdb git submodule update --init deps/meshguard zig build -Doptimize=ReleaseSmall -Dcrypto-backend=std ./zig-out/bin/wormdb --config examples/local.json
The std crypto backend avoids an external libsodium dependency.
The example binds to 127.0.0.1:6389 with authentication and the browser gateway disabled.
2. In another terminal, from the repo root
bun run apps/bun/src/bin/client.ts SET audit:001 ready --worm
bun run apps/bun/src/bin/client.ts GET audit:001
# both commands below return a WORM violation
bun run apps/bun/src/bin/client.ts SET audit:001 changed
bun run apps/bun/src/bin/client.ts DEL audit:001
The first two commands return OK and ready. The next two demonstrate an immutable key. Use a fresh key to repeat the example.
Linux supports clustering; Windows supports the standalone server. Windows setup · Authentication and deployment limits