Hanzo KV

Hanzo KV is a Redis-compatible in-memory key-value store used as the caching, streaming, and message broker layer across the Hanzo ecosystem. C codebase built with CMake, ships as `ghcr.io/hanzoai/...

Overview

Hanzo KV is a Redis-compatible in-memory key-value store used as the caching, streaming, and message broker layer across the Hanzo ecosystem. C codebase built with CMake, ships as ghcr.io/hanzoai/kv. Includes a native ZAP binary protocol module for high-throughput access. Default port 6379 (RESP), ZAP port 9653. License: BSD-3-Clause.

Why Hanzo KV?

Redis drop-in replacement: Any Redis client works out of the box

ZAP binary protocol: Native module on port 9653 (17x faster than JSON-RPC)

Persistence: RDB snapshots and AOF for durability

Replication: Primary-replica with Sentinel automatic failover

Cluster mode: Horizontal scaling with automatic sharding

Module system: Extensible via C module API (kvmodule.h)

Tech Stack

Language: C

Build: Make (top-level delegates to src/Makefile), CMake also available

Image: ghcr.io/hanzoai/kv (based on kv/kv:9-alpine)

Modules: ZAP binary protocol (modules/zap/)

OSS Base

Repo: hanzoai/kv (Valkey/Redis fork). Default branch: main.

When to use

Caching layer for any Hanzo service

Session storage and rate limiting

Pub/Sub messaging between services

Streams for event sourcing

Queue backend (via lists or streams)

High-throughput data access via ZAP protocol

Hard requirements

Port 6379 available for RESP protocol

Port 9653 if using ZAP binary protocol module

Docker or C build toolchain (gcc, make) for building from source

Quick reference

Item	Value
Default Port	6379 (RESP)
ZAP Port	9653
Image	`ghcr.io/hanzoai/kv`
Config	`kv.conf`
Sentinel Config	`sentinel.conf`
License	BSD-3-Clause
Repo	`github.com/hanzoai/kv`
Docs	`github.com/hanzoai/kv-doc`

One-file quickstart

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"

Build from source

make
make test
make install

Core Concepts

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Application │────>│   Hanzo KV   │────>│  Persistence  │
│  (any Redis  │     │  (port 6379) │     │  (RDB / AOF)  │
│   client)    │     └──────┬───────┘     └──────────────┘
└──────────────┘            │
                     ┌──────┴───────┐
                     │  ZAP Module  │
                     │ (port 9653)  │
                     └──────────────┘

CLI Tools

Command	Description
`kv`	Interactive CLI (symlink to kv-cli)
`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

ZAP Binary Protocol

The ZAP module (modules/zap/) implements the luxfi/zap binary protocol natively:

# Load module at startup
kv-server --loadmodule /path/to/zap.so PORT 9653

ZAP endpoints:

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

Custom modules use 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;
}

Configuration

# Pass config file
kv-server /etc/kv/kv.conf

# Or command-line options
kv-server --port 6379 --maxmemory 256mb --appendonly yes

Docker default CMD: --bind 0.0.0.0 --dir /data --maxmemory-policy allkeys-lru --protected-mode no

Client SDKs

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

Any Redis-compatible client library also works.

Directory Structure

kv/
  CMakeLists.txt         # CMake build
  Makefile               # Top-level make (delegates to src/)
  Dockerfile             # Container build (kv/kv:9-alpine base)
  kv.conf                # Default server configuration
  sentinel.conf          # Sentinel configuration
  src/                   # C source code
  modules/
    zap/                 # ZAP binary protocol module
      zap_module.c       # Module implementation
      zap_protocol.h     # Protocol header
      Makefile           # Module build
  deps/                  # Vendored dependencies
  tests/                 # Integration tests
  utils/                 # Utility scripts
  cmake/                 # CMake modules

Development Guidelines

C style: snake_case variables, camelCase functions, UPPER_CASE macros

Unit tests in src/unit/, integration tests in tests/

Line length: keep below 90 chars when reasonable

Use static for file-private functions

License header: BSD-3-Clause (SPDX)

Troubleshooting

Issue	Cause	Solution
Connection refused	KV not running or wrong port	Check `kv-server` is running, verify port
OOM	maxmemory reached	Set `--maxmemory` and `--maxmemory-policy`
Persistence issues	AOF corruption	Run `kv-check-aof --fix`
ZAP module not loading	Missing .so file	Build with `cd modules/zap && make`

hanzo/hanzo-sql.md - PostgreSQL database

hanzo/hanzo-orm.md - ORM with KV cache backend

hanzo/hanzo-platform.md - PaaS deployment

hanzo/hanzo-universe.md - Production K8s infrastructure

On this page