# Kv

URL: https://docs.hanzo.ai/docs/projects/hanzoai/kv

> Ultra-fast key-value store with Redis API compatibility

![kv](https://docs.hanzo.ai/docs/projects/hanzoai/.github/hero.svg)

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](https://github.com/hanzoai/kv/actions/workflows/ci.yml/badge.svg)](https://github.com/hanzoai/kv/actions)

[![Release](https://img.shields.io/github/v/release/hanzoai/kv)](https://github.com/hanzoai/kv/releases)

[![License](https://img.shields.io/github/license/hanzoai/kv)](https://github.com/hanzoai/kv/blob/main/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](https://github.com/luxfi/zap) on port 9653 (17x faster than JSON-RPC)
- **Multi-arch** -- linux/amd64 and linux/arm64

## Quick Start

### Docker

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

### Connect

```bash
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

```bash
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:

```bash
kv-server /etc/kv/kv.conf
```

Or set options via command line:

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

## ZAP Binary Protocol

Hanzo KV can speak [ZAP](https://github.com/luxfi/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:

```bash
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:

```c
#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](https://pypi.org/project/hanzo-kv) | `pip install hanzo-kv`            |
| Go       | [hanzokv/go](https://github.com/hanzokv/go)   | `go get github.com/hanzokv/go/v9` |
| Node.js  | [hanzokv/js](https://github.com/hanzokv/js)   | `npm install @hanzo/kv`           |

Any RESP client library will also work.

## Documentation

Full documentation is available at [docs.hanzo.ai](https://docs.hanzo.ai).

## License

BSD-3-Clause

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

## Links

- [Source](https://github.com/hanzoai/kv)