VelesDB

<p align="center">
  <img src="velesdb_icon_pack/favicon/android-chrome-512x512.png" alt="VelesDB Logo" width="180"/>
</p>
<h1 align="center">
  <img src="velesdb_icon_pack/favicon/favicon-32x32.png" alt="" width="32" height="32" style="vertical-align: middle;"/> VelesDB
</h1>
<h3 align="center">
  Three engines. One language. A memory your agents can explain.
</h3>
<p align="center">
  <strong>One ~9 MB binary fuses vector + graph + columnar under <a href="docs/VELESQL_SPEC.md">VelesQL</a> —
  persistent agent memory with an evidence trail (<code>why()</code>) and a deterministic
  context optimizer that cuts your <em>real, billed</em> token spend.</strong><br/>
  Zero cloud, zero LLM, zero API key in the memory path. Every number on this page links to a
  <a href="crates/velesdb-memory/BENCHMARK.md">committed, reproducible harness</a>. Measured, not vibes.
</p>
<p align="center">
  <sub><em>The name nods to <strong>Veles</strong>, a deity of old Slavic myth — a keeper of hidden knowledge and boundaries.</em></sub>
</p>
<p align="center">
  <a href="https://github.com/cyberlife-coder/VelesDB/actions/workflows/ci.yml"><img src="https://github.com/cyberlife-coder/VelesDB/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://app.codacy.com/gh/cyberlife-coder/VelesDB/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://img.shields.io/codacy/grade/58c73832dd294ba38144856ae69e9cf2?branch=main&label=code%20quality" alt="Codacy code quality"></a>
  <a href="https://crates.io/crates/velesdb-core"><img src="https://img.shields.io/crates/v/velesdb-core.svg?cacheSeconds=3600" alt="Crates.io"></a>
  <a href="https://crates.io/crates/velesdb-core"><img src="https://img.shields.io/crates/d/velesdb-core.svg" alt="Crates.io Downloads"></a>
  <a href="https://pypi.org/project/velesdb/"><img src="https://img.shields.io/pypi/v/velesdb.svg?cacheSeconds=3600" alt="PyPI"></a>
  <a href="https://www.npmjs.com/package/@wiscale/velesdb-sdk"><img src="https://img.shields.io/npm/v/@wiscale/velesdb-sdk.svg?cacheSeconds=3600" alt="npm"></a>
  <a href="https://app.codacy.com/gh/cyberlife-coder/VelesDB/dashboard"><img src="https://img.shields.io/codacy/coverage/58c73832dd294ba38144856ae69e9cf2?branch=main" alt="Codacy coverage"></a>
  <img src="https://img.shields.io/badge/tests-9k%2B_(Rust%2BTS%2BPy)-brightgreen" alt="Tests">
  <a href="https://github.com/cyberlife-coder/VelesDB/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-VelesDB_Core_1.0-blue" alt="License"></a>
  <a href="https://github.com/cyberlife-coder/VelesDB"><img src="https://img.shields.io/github/stars/cyberlife-coder/VelesDB?style=flat-square" alt="Stars"></a>
</p>
<p align="center">
  <a href="#get-started-in-60-seconds">Quick Start</a> &bull;
  <a href="#the-numbers--every-one-from-a-committed-harness">Proof</a> &bull;
  <a href="#velesdb-premium--the-enterprise-control-plane">Premium</a> &bull;
  <a href="ARCHITECTURE.md">Architecture</a> &bull;
  <a href="ROADMAP.md">Roadmap</a> &bull;
  <a href="https://velesdb.com/en/">velesdb.com</a> &bull;
  <a href="https://deepwiki.com/cyberlife-coder/VelesDB">DeepWiki</a>
</p>

---

## Why VelesDB exists

Every AI agent today has the same two problems:

1. **It forgets.** Session ends, context gone. Teams bolt on three databases to fix it — vectors for *"what feels similar"*, a graph for *"what is connected"*, SQL for *"what I know for sure"* — three deployments, three query languages, and a pile of glue code.
2. **It overpays.** Most of the budget goes to re-reading redundant context, and "memory" products fix it by putting *another paid model call* inside every memory write — generative, non-reproducible, unexplainable by construction.

**VelesDB answers both with two layers that ship as one project:**

| | What it is | How you use it |
|---|---|---|
| **1 · The tri-engine agentic database** | Vector + graph + columnar fused in one ~9 MB Rust binary, queried in **[VelesQL](docs/VELESQL_SPEC.md)** — one language across all three. | Embedded (Rust/Python), REST server, WASM in the browser, mobile. |
| **2 · The agent memory model** | Built *on* that database: `remember` / `relate` / `why()` with typed links and an evidence trail, resumable working contexts, and the deterministic **context token optimizer** — measured against **real provider bills**. | A local **MCP server** for any agentic CLI (Claude Code, Codex, …) + **Python and Node bindings**. |

The database stands on its own. The memory model is why agents pick it.

| If you are… | What you get |
|---|---|
| **A developer living in an agentic CLI** (Claude Code, Codex, …) | Your agent remembers across sessions, answers `why()` with an evidence trail, and burns measurably fewer tokens — [installed in 3 commands](#give-your-agent-a-memory-3-commands). |
| **A CTO** | One auditable ~9 MB binary instead of 3 databases + glue. Deterministic writes, an audit trail per decision — the kind of explainability the [EU AI Act (enforceable Aug 2026)](https://artificialintelligenceact.eu/implementation-timeline/) asks of AI systems — running in your jurisdiction, air-gapped if needed. |
| **A company running agents at scale** | The same engine with an enterprise control plane on top: RBAC, audit trail, multi-tenancy — see [VelesDB Premium](#velesdb-premium--the-enterprise-control-plane). |

## The differentiator no one else combines

The leading agent-memory products ([Mem0, Zep, Letta — detailed comparison, as of mid-2026](docs/WHY_VELESDB.md)) put an AI model **in the memory write path**: every save runs model calls — by default paid, cloud, keyed. VelesDB is built on the opposite bet:

| Property | What it means concretely |
|---|---|
| 🎯 **Deterministic** | The same input always compiles to the **same bytes** — asserted twice per turn in every committed benchmark. No model in the loop: no drift, no surprise rewrites, and a [byte-stable cache prefix](crates/velesdb-memory/examples/context_savings/real_measures/cache_prefix.mjs) provider prompt-caching can actually hit. |
| 🔍 **Explainable** | `why()` returns the **evidence trail** behind every recall; `explain_compilation` gives every kept/dropped fragment a stable rule id, a reason, and a risk level. A built-in audit trail, not a slide-deck promise. |
| ♻️ **Reversible** | Nothing is silently lost. Over-budget content becomes a recoverable `ctx://source/` handle — `retrieve_context_source` brings the original bytes back on demand, always. |
| 🏠 **Local-first** | One ~9 MB binary on your machine: vector + graph + columnar in-process, **zero AI calls and zero API keys** to store a memory. Works offline, air-gapped, in your jurisdiction. |

---

## Get started in 60 seconds

**Fastest path — Python, under 5 seconds median, [measured](docs/quickstart/timing-results.md):**

```bash
pip install velesdb
curl -O https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/examples/python/hello_velesdb.py
python hello_velesdb.py
```

Expected output (byte-for-byte — [read the 25-line script](examples/python/hello_velesdb.py)):

```
Query: "tech"
  score=1.000  Rust 1.89 release notes
  score=0.600  AI-generated jazz: the new wave
  score=0.000  Best ramen in Tokyo

Query: "tech + music"
  score=0.990  AI-generated jazz: the new wave
  score=0.707  Rust 1.89 release notes
  score=0.707  Miles Davis discography
```

### Give your agent a memory (3 commands)

```bash
# 1. The MCP memory server (or grab a prebuilt .mcpb bundle from the latest release)
cargo install velesdb-memory

# 2. Point your agentic CLI at it (Claude Code shown; any MCP client works)
claude mcp add velesdb-memory -- ~/.cargo/bin/velesdb-memory

# 3. Teach the agent the workflow — both skills, no repo clone needed
curl -L https://github.com/cyberlife-coder/VelesDB/releases/latest/download/velesdb-skills.tar.gz \
  | tar -xz -C ~/.claude/skills/
```

Want the memory used *continuously*, not just available? [`integrations/agent-hooks/`](integrations/agent-hooks/README.md) wires `SessionStart`/`Stop`/`PreCompact` hooks that resume and save the working context automatically — one global install covers every project. No Rust toolchain? `npm i @wiscale/velesdb-memory-node`.

Want Claude Code, Claude Desktop, and Windsurf sharing the *same* memory instead of one client at a time? [`scripts/install-memory-daemon.sh`](crates/velesdb-memory/README.md#http-transport-multi-client) runs `velesdb-memory` as a single local HTTP daemon and wires every client to it.

<details>
<summary><strong>Other install paths — Rust, Docker, WASM, REST server</strong></summary>

**Cargo (Rust + REST server):**
```bash
cargo install velesdb-server velesdb-cli
```

**Docker (REST server, multi-arch linux/amd64 + linux/arm64):**
```bash
docker run -d -p 8080:8080 -v velesdb_data:/data --name velesdb \
  ghcr.io/cyberlife-coder/velesdb:latest
curl http://localhost:8080/health
```

**Browser / edge:** the WASM build is ~550 KB gzipped — the engine runs entirely client-side ([TypeScript SDK](sdks/typescript)).

**REST:** the server exposes 54 REST endpoints ([OpenAPI spec](docs/openapi.yaml)).

</details>

---

## The numbers — every one from a committed harness

No figure below is an estimate from a slide. Each links to the log or script, in this repo, that produced it — rerun them yourself.

| Claim | Measured | Source |
|---|---|---|
| Real **billed dollars** saved on an A/B agent session (raw vs compiled, same session, real Claude billing) | **10.9 %** at cropped-screenshot weight → **21.9 %** at real Retina screenshot weight; **14.7 %** on a 36-turn day-scale arc | [real-session-benchmark](examples/real-session-benchmark#billed-campaign-results-2026-07-19-cli-runner-claude-sonnet-5) · [raw logs](examples/real-session-benchmark/results/2026-07-19-vibe-cli/) · [day-scale logs](examples/real-session-benchmark/results/2026-07-19-day-scale/) |
| Direct Messages-API **input tokens** saved (no CLI cache routing diluting the sig