A Redis-compatible in-memory key-value store written in Rust. kvns speaks RESP and works with redis-cli and Redis client libraries.

This project is an experiment and in part uses code generated with models from Anthropic.

• RESP2 server with RESP3 handshake support via HELLO 3
• Redis-like command surface across strings, lists, hashes, sets, and sorted sets
• Key namespacing via namespace/key syntax
• TTL/expiry management (EXPIRE*, PEXPIRE*, PERSIST, EXPIRETIME, PEXPIRETIME)
• Configurable memory limit with OOM rejection or namespace-scoped eviction (lru, mru)
• Memory-limit guardrails when configured (KVNS_MEMORY_LIMIT is capped at 70% of host RAM)
• Optional on-disk persistence with periodic flush and shutdown flush
• Prometheus metrics endpoint with per-namespace labels
• Structured logs via tracing

Keys may include a namespace prefix separated by /:

namespace/localkey

• SET db1/x 42 stores key x in namespace db1
• GET db1/x reads key x from namespace db1
• Keys with no / are stored in the default namespace

Only the first / is treated as the separator, so local keys may also contain / (for example SET ns/a/b value uses namespace ns and key a/b).

Namespaces are isolated: db1/x and db2/x are different keys with independent memory/accounting metrics.

Command names are case-insensitive.

Compatibility notes:

• HMSET is accepted as an alias for HSET.
• SUBSTR is accepted as an alias for GETRANGE.
• XADD currently returns ERR stream type not supported.
• Some server/introspection subcommands are compatibility shims and return static or empty responses.
• SELECT only supports database index 0.

TTL and expiry return semantics match Redis-style integer responses:

• TTL/PTTL return -2 for missing keys
• TTL/PTTL return -1 for keys without expiry
• EXPIRE, EXPIREAT, PEXPIRE, and PEXPIREAT support NX, XX, GT, LT

Examples:

KEYS *           # all keys in all namespaces
KEYS ns/*        # all keys in namespace "ns"
SCAN 0 MATCH ns/* COUNT 50
KEYS h[ae]llo    # hello or hallo

Development run:

cargo run

Release build and run:

cargo build --release
./target/release/kvns

Or use the Makefile:

make run
make build
make release

Build a local image:

make podman-build IMAGE=kvns:local

Run directly:

make podman-run IMAGE=kvns:local

Use podman compose with docker-compose.yaml:

make podman-compose-up
make podman-compose-logs
make podman-compose-down

Push a multi-arch image to GHCR:

make podman-login-ghcr GHCR_USER="<github-user>" GHCR_TOKEN="<github-token>"
make podman-push-ghcr GHCR_IMAGE="ghcr.io/<owner>/<repo>" TAG="v0.3.0"

Notes:

• podman-push-ghcr builds and pushes linux/amd64,linux/arm64 by default
• Set PLATFORMS to override target platforms
• Set PUSH_LATEST=false to skip publishing latest

All settings are read from environment variables at startup.

Examples:

# Custom port + memory limit
KVNS_PORT=6379 KVNS_MEMORY_LIMIT=536870912 cargo run

# Enable persistence
KVNS_PERSIST_PATH=/var/lib/kvns/db.rkyv KVNS_PERSIST_INTERVAL=60 cargo run

# Enable LRU eviction at 80% memory usage
KVNS_EVICTION_POLICY=lru KVNS_EVICTION_THRESHOLD=0.8 cargo run

# Override one namespace to MRU while global policy is LRU
KVNS_EVICTION_POLICY=lru KVNS_NS_EVICTION=cache:mru cargo run

# Run the experimental sharded backend
KVNS_SHARDED_MODE=true KVNS_SHARD_COUNT=64 cargo run

Sharded mode notes:

• KVNS_SHARDED_MODE is experimental and currently optimized for throughput-oriented string workloads.
• Under concurrent writers, multi-key command atomicity may differ from classic mode.

Memory limit behavior:

• If KVNS_MEMORY_LIMIT is unset, kvns uses the default 1073741824 bytes (1 GiB)
• If KVNS_MEMORY_LIMIT is set above 70% of detected host RAM, kvns clamps it to that 70% cap
• If KVNS_MEMORY_LIMIT=0, kvns uses the same 70% cap directly
• If host memory cannot be detected, kvns keeps the configured value; 0 falls back to the 1 GiB default

When a write would exceed the effective KVNS_MEMORY_LIMIT, kvns either rejects it with OOM or evicts keys depending on policy.

KVNS_EVICTION_THRESHOLD controls when eviction begins. With 1.0 (default), eviction starts only at full configured capacity. Lower values (for example 0.8) start eviction earlier.

KVNS_NS_EVICTION supports comma-separated namespace:policy overrides. Eviction is namespace-scoped: a write in one namespace never evicts keys from another namespace.

When KVNS_PERSIST_PATH is set, kvns periodically snapshots the full store to disk using rkyv. Writes are atomic: data is written to a temporary file (*.tmp) and then renamed into place.

• Persistence is opt-in (unset KVNS_PERSIST_PATH for in-memory only)
• Flush interval is controlled by KVNS_PERSIST_INTERVAL
• On startup, persisted data is loaded if present
• Expired entries are dropped during load
• On clean shutdown (SIGINT/SIGTERM), kvns flushes immediately
• Parent directories for KVNS_PERSIST_PATH are created automatically

The periodic persistence flush needs a consistent snapshot of the store. By default (KVNS_SHARED_VALUES=true), entry values are held via Arc so the snapshot step is a pointer-bump rather than a deep byte copy. In exchange each write allocates a small Arc header.

Set KVNS_SHARED_VALUES=false when persistence is disabled or when raw write throughput matters more than snapshot-time tail latency. The flag is read once at startup; changing it requires a restart.

kvns exposes Prometheus metrics at http://<KVNS_METRICS_HOST>:<KVNS_METRICS_PORT>/metrics.

Per-namespace gauges are created on first write and are set to 0 when the last key in a namespace is removed.

# Start kvns with persistence enabled
KVNS_PERSIST_PATH=kvns.db cargo run &

# Write namespaced and default keys
redis-cli -p 6480 SET db1/x 42
redis-cli -p 6480 SET db2/x 99
redis-cli -p 6480 SET counter 0
redis-cli -p 6480 INCR counter

# Query data
redis-cli -p 6480 GET db1/x
redis-cli -p 6480 KEYS "db*/*"
redis-cli -p 6480 SCAN 0 MATCH "db*/*" COUNT 100

# Inspect metrics
curl -s http://localhost:9090/metrics | grep -E '^kvns_(memory|keys|evictions)'

cargo test
make lint
make fmt-check

Run benchmark profiles against kvns:

make benchmark

Run the same benchmark suite against kvns experimental sharded backend:

make benchmark-sharded

Run classic and sharded back-to-back and print a direct speedup table:

make benchmark-compare

Notes:

• Output artifacts are written under /tmp/kvns-bench-* (or BENCH_DIR if set)

Numbers are single-run samples on a development laptop and move ±10% run-to-run with thermal/load state; treat them as order-of-magnitude.

KVNS_SHARED_VALUES (see Value sharing) controls whether entry values are held via Arc so persistence snapshots clone pointers rather than bytes. Throughput impact is small; the payoff is in tail latency during a snapshot.

Classic mode, memtier direct profile (-c 20 -t 8 -d 256 --test-time=60 --ratio 1:0 / 0:1):

Persist-stall scenario (200k × 256-byte keys pre-loaded, KVNS_PERSIST_INTERVAL=2, -c 50 -P 1, so individual request stalls aren't masked by pipelining):

Same throughput either way; max latency during a snapshot flush drops by ~58% with shared values because the persist task deep-copies Arc refcounts instead of payload bytes.

Key takeaways:

• Sharded mode delivers a ~5x pipeline-SET and ~2x pipeline-GET speedup over classic, with modest gains on direct (non-pipelined) workloads.
• KVNS_SHARED_VALUES=true costs about 0–3% direct throughput but cuts persist-snapshot max latency by more than half.