Kv

Ultra-fast key-value store with Redis API compatibility

Hanzo KV

High-performance key-value store for the Hanzo ecosystem.
In-memory data store used as database, cache, streaming engine, and message broker.

Features

In-memory key-value store -- sub-millisecond reads and writes
RESP protocol -- speaks RESP2 and RESP3, so existing clients connect unchanged
Persistence -- RDB snapshots and AOF (append-only file) for durability
Replication -- primary-replica with automatic failover via Sentinel
Lua scripting -- server-side scripting for atomic operations
Pub/Sub -- publish and subscribe messaging
Streams -- append-only log data structure for event sourcing
Cluster mode -- horizontal scaling with automatic sharding
Modules -- extensible plugin system for custom data structures
ZAP native -- built-in ZAP binary protocol on port 9653 (17x faster than JSON-RPC)
Multi-arch -- linux/amd64 and linux/arm64

Quick Start

Docker

docker run -d --name hanzo-kv -p 6379:6379 ghcr.io/hanzoai/kv

Connect

docker exec -it hanzo-kv kv

127.0.0.1:6379> SET hello world
OK
127.0.0.1:6379> GET hello
"world"

Any RESP client also works out of the box.

Build from Source

make
make test
make install

CLI Tools

Command	Description
`kv`	Interactive CLI (default)
`kv-server`	Start KV server
`kv-cli`	Command-line client
`kv-sentinel`	High-availability sentinel
`kv-benchmark`	Performance benchmarking
`kv-check-aof`	AOF file integrity check
`kv-check-rdb`	RDB file integrity check

Configuration

Pass a config file at startup:

kv-server /etc/kv/kv.conf

Or set options via command line:

kv-server --port 6379 --maxmemory 256mb --appendonly yes

ZAP Binary Protocol

Hanzo KV can speak ZAP natively on port 9653 via the module in modules/zap — no sidecar needed. ZAP is a zero-copy binary protocol that's 17x faster than JSON-RPC with 11x less memory usage.

Status: source-only, NOT in the published image. modules/zap builds with its own Makefile but is wired into no parent build, so ghcr.io/hanzoai/kv:9 ships without zap.so — a running instance reports an empty MODULE LIST and listens on 6379 only. Enabling it means building the module in the image and loading it as below. Until that lands, treat KV as RESP-only and do not write clients against 9653.

Enable ZAP

Build modules/zap, then load it:

kv-server --loadmodule /path/to/zap.so
# or with custom port:
kv-server --loadmodule /path/to/zap.so PORT 9653

ZAP Operations

Path	Body	Description
`/get`	`{"key":"mykey"}`	GET a key
`/set`	`{"key":"mykey","value":"myval"}`	SET a key
`/del`	`{"key":"mykey"}`	DEL a key
`/cmd`	`{"cmd":"PING","args":[]}`	Execute any command

Module API

Develop custom modules using the KV Module API:

#include "kvmodule.h"

int KVModule_OnLoad(KVModuleCtx *ctx, KVModuleString **argv, int argc) {
    if (KVModule_Init(ctx, "mymod", 1, KVMODULE_APIVER_1) == KVMODULE_ERR)
        return KVMODULE_ERR;
    // register commands...
    return KVMODULE_OK;
}

Client SDKs

Language	Package	Install
Python	hanzo-kv	`pip install hanzo-kv`
Go	hanzokv/go	`go get github.com/hanzokv/go/v9`
Node.js	hanzokv/js	`npm install @hanzo/kv`

Any RESP client library will also work.

Documentation

Full documentation is available at docs.hanzo.ai.

License

BSD-3-Clause