Files
zeekay b00ea55a05 docs: the shipped surfaces name kv
kv.conf documented extended-redis-compatibility, which no longer exists, and
told operators it was "scheduled to have no effect" — it now has none. The
remaining mentions were upstream's own name in prose about listpacks, TLS user
matching and a deprecation note, plus a link to an essay whose argument the
surrounding paragraph already makes.

README described the wire as Redis-compatible. It is RESP, which is the name of
the protocol; clients connect because they speak RESP2 and RESP3, not because
of who else implements it.
2026-07-26 15:05:35 -07:00

4.4 KiB

kv

Hanzo KV

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

CI Release License


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.