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.

Hanzo KV - High-Performance Key-Value Store

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-sql.md, hanzo/hanzo-platform.md, hanzo/hanzo-orm.md

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

1. Port 6379 available for RESP protocol
2. Port 9653 if using ZAP binary protocol module
3. 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 |

Related Skills

• 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

---

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: kv, redis, valkey, cache, pub/sub, streams, zap Prerequisites: Docker or C build toolchain