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

Copyright (c) 2024-2026 Hanzo AI Inc. All rights reserved.