Duxxdb

Hybrid retrieval (vector + BM25 + structured), agent-native primitives (MEMORY / TOOL_CACHE / SESSION), and embedded-or-server deployment from one Rust codebase. Speaks RESP2/3, gRPC, and MCP out of the box.

[](https://github.com/bankyresearch/duxxdb/actions/workflows/ci.yml) [](LICENSE) [](https://www.rust-lang.org/) [](https://github.com/bankyresearch/duxxdb/actions/workflows/ci.yml) [](docs/PROJECT_OVERVIEW.md) [](docs/)

[Install](#install) · [Quickstart](#quickstart) · [Why](#why-duxxdb) · [Features](#features) · [Integrate](docs/INTEGRATION_GUIDE.md) · [FAQ](docs/FAQ.md) · [Architecture](#architecture) · [Benchmarks](#benchmarks) · [Roadmap](docs/ROADMAP.md) · [Contribute](CONTRIBUTING.md)

---

TL;DR

docker run -d --name duxxdb -p 6379:6379 ghcr.io/bankyresearch/duxxdb:latest

redis-cli -p 6379 REMEMBER alice "I lost my wallet at the cafe"
redis-cli -p 6379 RECALL    alice "wallet" 3
# 1) 1) (integer) 1
#    2) "0.032787"
#    3) "I lost my wallet at the cafe"

DuxxDB just spoke RESP — redis-cli, valkey-cli, redis-rs, node-redis, go-redis, all work unchanged. Now switch to the [Quickstart](#quickstart) for Python, gRPC, or MCP.

> Status: self-hosted beta — feature-complete through Phase 7 > with auth + RBAC, native TLS, health, Prometheus, graceful shutdown, > persistence, mTLS client verification, configurable protocol limits, > offline snapshot/restore, importance-based eviction, and deletion-safe > recall (graph compaction). See the [Roadmap](docs/ROADMAP.md). > > Multi-tenancy, the control plane, replication/HA, and the Cloud Console > live in DuxxDB Cloud (a separate managed-services product); this repo > is the Apache-2.0 single-node engine. See [LICENSING.md](LICENSING.md).

---

The Duxx Stack

DuxxDB is the storage engine half. The framework half is duxx-ai — an Apache 2.0 Python SDK for building, fine-tuning, orchestrating, and governing AI agents:

   ┌─ duxx-ai (Python) ────────────────────────────────────┐
   │  agents · graph · crew · tools · memory · guardrails  │
   │  RBAC · observability · fine-tune · adaptive routing  │
   └────────────────────┬──────────────────────────────────┘
                        │ uses (memory / traces / prompts / eval / cost)
   ┌────────────────────▼──────────────────────────────────┐
   │  DuxxDB (Rust) — storage + retrieval + observability  │
   │  hybrid recall · TLS · MCP · gRPC · RESP · Parquet    │
   └───────────────────────────────────────────────────────┘

| You're building... | Reach for | |---|---| | The agent itself (Python) | duxx-ai — agents, crews, tools, governance | | The storage / retrieval layer | duxxdb (this repo) — single binary, six client surfaces | | Both together | pip install duxx-ai duxxdb — the full Apache 2.0 agent stack |

Why one stack, two projects? Rust gets you sub-ms hybrid recall + TLS + multi-platform binaries. Python gets you the agent-developer ergonomics — typed primitives, LLM SDKs, tools, governance — without dragging C++ deployment headaches into the storage tier. Each side plays to its strengths; they ship independently with semver.

---

Why DuxxDB?

A typical agent stack today glues three databases together:

┌──────────┐    ┌──────────┐    ┌──────────────┐
│  Redis   │    │ Qdrant   │    │  Postgres    │
│  session │    │  vectors │    │  facts/users │
│  ~0.5ms  │    │  ~10ms   │    │  ~1-5ms      │
└────┬─────┘    └────┬─────┘    └──────┬───────┘
     ▼               ▼                 ▼
            3 round-trips per turn
            3 client libs · 3 sets of credentials
            eventual consistency between them

The tax shows up in three places:

| Tax | Cost | |---|---| | Latency | 3 hops = 300 µs–3 ms before any work. Voice bots blow their 200 ms budget. | | Consistency | A user message, its embedding, and its session metadata land in three stores at three times. | | Glue code | Cross-store transactions, retries, drift — the silent killer of agent reliability. |

DuxxDB collapses the three into one engine with first-class agent primitives, a single hybrid query plan (vector ANN + BM25 + structured filters fused via Reciprocal Rank Fusion), and six integration surfaces out of one codebase. Pure Rust, no GC pauses.

---

Features

Hybrid retrieval

• HNSW vector ANN (hnsw_rs)
• BM25 full-text (tantivy)
• Structured filters
• All three fused in one query plan (RRF, k=60)

Agent-native primitives

• MEMORY — sticky long-term recall with importance decay
• TOOL_CACHE — exact + semantic-near-hit lookup (cosine ≥ 0.95)
• SESSION — sliding-TTL KV with lazy eviction
• All first-class types — not generic tables

Six integration surfaces

• Embedded Rust crate
• Python wheel (PyO3, abi3-py38, one wheel for 3.8–3.13)
• Node / TypeScript native module (napi-rs v2)
• RESP2/3 TCP server (Valkey/Redis-compatible)
• gRPC with streaming Subscribe (tonic)
• MCP stdio for Claude / GPT / Cline agents

Production hardening (Phase 6.1 + 6.2)

• Token auth (--token / DUXX_TOKEN)
• Role-based RESP API keys (DUXX_AUTH_KEYS) with read/write/admin roles
• JSON-lines security audit log (DUXX_AUDIT_LOG)
• Native TLS on RESP + gRPC (rustls)
• mTLS client verification with --tls-client-ca
• Configurable RESP resource limits (DUXX_MAX_*)
• Connection and per-connection command-rate caps
• Prometheus /metrics + /health
• gRPC grpc.health.v1.Health protocol
• Graceful shutdown drain
• Memory cap + importance-based eviction
• Offline duxx-snapshot create/verify/restore
• Apache Parquet cold-tier export

---

Install

Postgres-style — pick your platform.

| Platform | Command | Details | |---|---|---| | 🐳 Docker (any OS) | docker run -p 6379:6379 ghcr.io/bankyresearch/duxxdb:latest | [Docker guide](docs/INSTALLATION.md#docker-single-command) | | 🐳 Docker Compose (production) | cd packaging/docker && cp .env.example .env && docker compose up -d | [Compose guide](docs/INSTALLATION.md#docker-compose-production-grade) | | 🐧 Debian / Ubuntu | sudo apt install ./duxxdb_*.deb | [.deb install](docs/INSTALLATION.md#linux--debian--ubuntu-apt-deb) | | 🐧 RHEL / Fedora / Rocky | curl -fsSL …/install.sh \| sudo sh + systemd unit | [.rpm install](docs/INSTALLATION.md#linux--rhel--fedora--rocky--alma-dnf-rpm) | | 🍏 macOS | brew install bankyresearch/duxxdb/duxxdb | [Homebrew](docs/INSTALLATION.md#macos--homebrew) | | 🐚 One-line installer | curl -fsSL …/install.sh \| sh | [Installer](docs/INSTALLATION.md#linux--macos--one-line-installer) | | 🪟 Windows | zip from Releases | [Windows guide](docs/INSTALLATION.md#windows--zip-download-manual) | | ☸ Kubernetes | kubectl apply -f packaging/k8s/duxxdb.yaml | [k8s guide](docs/INSTALLATION.md#kubernetes) | | 🐍 Python | pip install … (locally built wheel) | [Python](docs/INSTALLATION.md#embed--python-wheel) | | 📦 Node / TS | npm install … (locally built .node) | [Node](docs/INSTALLATION.md#embed--node--typescript) | | 🦀 Rust crate | cargo add duxx-memory --git … | [Cargo](docs/INSTALLATION.md#embed--rust-crate) | | 📐 From source | cargo build --release --workspace | [Source](docs/INSTALLATION.md#from-source-any-os) |

→ Full per-platform install + uninstall + service-control cheatsheet: [docs/INSTALLATION.md](docs/INSTALLATION.md).

---

Quickstart

From a redis client (any language)

redis-cli -p 6379

127.0.0.1:6379> REMEMBER alice "I want a refund for order #9910"
(integer) 1
127.0.0.1:6379> RECALL alice "refund" 5
1) 1) (integer) 1
   2) "0.032787"
   3) "I want a refund for order #9910"
127.0.0.1:6379> PSUBSCRIBE memory.*

From Python

import duxxdb

store = duxxdb.MemoryStore(dim=32)
store.remember(key="alice", text="I lost my wallet")
hits = store.recall(key="alice", query="wallet", k=5)
for hit in hits:
    print(hit.id, hit.score, hit.text)

From Node / TypeScript

import { MemoryStore } from "duxxdb";

const store = new MemoryStore({ dim: 32 });
store.remember("alice", "I lost my wallet");
console.log(store.recall("alice", "wallet", 5));

Embedded in a Rust app

use duxx_memory::MemoryStore;
use duxx_embed::HashEmbedder;
use std::sync::Arc;

let store = MemoryStore::new(Arc::new(HashEmbedder::new(32)));
store.remember("alice", "I lost my wallet", None)?;
let hits = store.recall("alice", "wallet", 5)?;

Over gRPC (any tonic / grpcio / grpc-go client)

grpcurl -plaintext -d '{"key":"alice","text":"I lost my wallet"}' \
  localhost:50051 duxx.v1.Duxx/Remember

grpcurl -plaintext -d '{"key":"alice","query":"wallet","k":5}' \
  localhost:50051 duxx.v1.Duxx/Recall

Over MCP (Claude Desktop / Cline / any MCP agent)

// claude_desktop_config.json
{
  "mcpServers": {
    "duxxdb": { "command": "/usr/local/bin/duxx-mcp" }
  }
}

→ Full per-surface walkthrough: [docs/USERGUIDE.md](docs/USERGUIDE.md). → Wiring into a real agent (chatbot / voice bot / migration): [docs/INTEGRATIONGUIDE.md](docs/INTEGRATIONGUIDE.md).

---

Architecture

              AGENT (chatbot / voice bot / autonomous)
                              │
        ┌─────────────────────┴─────────────────────┐
        ▼                                           ▼
    embedded                                ┌───────────────┐
    duxx-memory (lib)                       │ duxx-server   │ RESP TCP
        │                                   ├───────────────┤
        ▼                                   │ duxx-grpc     │ gRPC + streaming
    Python / Node bindings                  ├───────────────┤
                                            │ duxx-mcp      │ stdio JSON-RPC
                                            └───────┬───────┘
                                                    │
                            ┌───────────────────────┼──────────────────┐
                            │                       │                  │
                            ▼                       ▼                  ▼
                      duxx-memory            duxx-reactive       duxx-coldtier
                      MEMORY / TOOL_CACHE     (ChangeBus)         (Parquet)
                      / SESSION + decay
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
         duxx-query   duxx-index    duxx-storage   duxx-embed
         (RRF +       tantivy +     redb /         hash / OpenAI /
          hybrid)     hnsw_rs       memory         Cohere

21 Rust crates, all Apache 2.0. Full design: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

---

Benchmarks

Hybrid recall, k = 10, single thread, debug release, toy 32-dim embedder. Reproduce: cargo bench -p duxx-bench.

| Corpus | Median recall | Throughput | vs 10 ms target | |---:|---:|---:|---:| | 100 docs | 123 µs | 8.1 k QPS | 81× headroom | | 1 000 docs | 166 µs | 6.0 k QPS | 60× headroom | | 10 000 docs | 373 µs | 2.7 k QPS | 27× headroom |

For a cross-system comparison — retrieval quality (recall@k / nDCG@k vs an exact ground truth), latency, and throughput under concurrent load, with DuxxDB run disk-backed against disk-backed Redis / Qdrant / pgvector — run the harness (bench/comparative/run.sh) and read the methodology in [docs/BENCHMARKS.md](docs/BENCHMARKS.md). We don't publish an unqualified "Nx faster" headline: any speed claim carries its workload, dimensions, hardware, and the peer's configuration.

---

How DuxxDB compares

| | Vector | BM25 | Structured | Embedded | Server | Reactive | Agent prims | MCP | |---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:| | Redis | ✗ | ✗ | ⚠ | ✗ | ✅ | ✅ | ✗ | ✗ | | Valkey | ⚠ (mod) | ⚠ (mod) | ⚠ | ✗ | ✅ | ✅ | ✗ | ✗ | | Qdrant | ✅ | ⚠ | ⚠ | ✗ | ✅ | ⚠ | ✗ | ✗ | | Pinecone | ✅ | ✗ | ⚠ | ✗ | ✅ | ✗ | ✗ | ✗ | | Milvus | ✅ | ⚠ | ✅ | ✗ | ✅ | ✗ | ✗ | ✗ | | Weaviate | ✅ | ✅ | ✅ | ✗ | ✅ | ✗ | ✗ | ✗ | | pgvector | ✅ | ⚠ | ✅ | ✗ | ✅ | ⚠ | ✗ | ✗ | | LanceDB | ✅ | ⚠ | ✅ | ✅ | ⚠ | ✗ | ✗ | ✗ | | ChromaDB | ✅ | ✗ | ⚠ | ✅ | ✅ | ✗ | ⚠ | ✗ | | DuxxDB | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

Full take with "when each one is the right choice" + coexistence patterns: [docs/PROJECTOVERVIEW.md § 8](docs/PROJECTOVERVIEW.md#8-competitive-landscape).

---

Documentation

| Doc | Use it when | |---|---| | [INSTALLATION.md](docs/INSTALLATION.md) | Picking install method per OS | | [USERGUIDE.md](docs/USERGUIDE.md) | Writing client code in any of 6 languages | | [INTEGRATIONGUIDE.md](docs/INTEGRATIONGUIDE.md) | Wiring DuxxDB into a chatbot, voice bot, or autonomous agent (with diagrams) | | [DUXXSTACKINTEGRATION.md](docs/DUXXSTACKINTEGRATION.md) | How duxx-ai (Python framework) plugs into DuxxDB — backend protocol, API contracts, deployment shapes | | [DRAGONFLYCOMPARISON.md](docs/DRAGONFLYCOMPARISON.md) | Enterprise reliability roadmap inspired by DragonflyDB's operational model | | [FAQ.md](docs/FAQ.md) | "Is DuxxDB right for me?" — when to use, when not to, framework support, migration | | [PROJECTOVERVIEW.md](docs/PROJECTOVERVIEW.md) | Pitching DuxxDB to a teammate / making a build-vs-buy call | | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Understanding the internals before contributing | | [ROADMAP.md](docs/ROADMAP.md) | Knowing what's shipped vs. planned | | [CONTRIBUTING.md](CONTRIBUTING.md) | Opening your first PR |

---

Repository layout

duxxdb/
├── Cargo.toml                 workspace root (21 crates)
├── Dockerfile                 multi-stage, multi-arch image
├── packaging/                 Postgres-style installers
│   ├── docker/                docker-compose.yml + .env.example + prometheus.yml
│   ├── systemd/               duxxdb.service + duxx.env
│   ├── debian/                .deb postinst / prerm / postrm
│   ├── homebrew/              duxxdb.rb formula
│   ├── k8s/                   StatefulSet + Service + ConfigMap
│   └── scripts/install.sh     curl-pipe installer
├── crates/
│   ├── duxx-core/             Schema · Value · Error
│   ├── duxx-storage/          Storage trait + redb / memory backends
│   ├── duxx-index/            tantivy BM25 + hnsw_rs HNSW (+ compaction)
│   ├── duxx-query/            RRF, hybrid recall
│   ├── duxx-memory/           MEMORY / TOOL_CACHE / SESSION + decay + compact
│   ├── duxx-reactive/         ChangeBus pub/sub
│   ├── duxx-embed/            hash + OpenAI + Cohere embedders
│   ├── duxx-trace/            agent trace store (Phase 7.1)
│   ├── duxx-prompts/          versioned prompt registry (Phase 7.2)
│   ├── duxx-datasets/         versioned eval datasets (Phase 7.3)
│   ├── duxx-eval/             eval runs + regressions (Phase 7.4)
│   ├── duxx-replay/           deterministic agent replay (Phase 7.5)
│   ├── duxx-cost/             token + cost ledger (Phase 7.6)
│   ├── duxx-docs/             document-intelligence layer (ingest→cite)
│   ├── duxx-token/            signed short-lived credentials (JWT)
│   ├── duxx-server/           RESP2/3 daemon + auth + Prometheus
│   ├── duxx-mcp/              MCP stdio JSON-RPC ser

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bankyresearch](https://github.com/bankyresearch)
- **Source:** [bankyresearch/duxxdb](https://github.com/bankyresearch/duxxdb)
- **License:** Apache-2.0
- **Homepage:** https://www.duxx.ai/duxxdb

Install and usage instructions live in the source repository linked above.