VelesDB Memory

VelesDB

One ~14 MB binary fuses vector + graph + columnar under a single query language — with an agent memory that shows its evidence and a deterministic context compiler that cuts your real, billed token spend.

Local-first: nothing leaves the machine, no LLM and no API key in the memory path. Every number below links to a committed harness you can rerun.

Quick start • Proof • Limitations • Architecture • Roadmap • velesdb.com

---

Start here — three commands that work

pip install velesdb

curl -O https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/examples/python/hello_velesdb.py python hello_velesdb.py

To search your own text instead of hand-written vectors, install the opt-in local adapter (pip install "velesdb[embed-sentence-transformers]") and run hello_velesdb_text.py; its first run downloads all-MiniLM-L6-v2.

Expected output, byte-for-byte (read the script — no server, no embedding model):

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

An embedding model determines the vector dimension, while your similarity semantics determine the metric. Both are fixed when a collection is created; to change either, create a new collection and re-index your documents.

Give your agent a persistent memory — three more commands:

cargo install velesdb-memory                                    # the local MCP memory server

claude mcp add velesdb-memory -- ~/.cargo/bin/velesdb-memory # any MCP client works curl -L https://github.com/cyberlife-coder/VelesDB/releases/latest/download/velesdb-skills.tar.gz | tar -xz -C ~/.claude/skills/

No Rust toolchain? npm i @wiscale/velesdb-memory-node, or grab a prebuilt .mcpb bundle from the official MCP Registry (io.github.cyberlife-coder/velesdb-memory).

Other paths — always-on hooks, shared daemon, Rust, Docker, WASM, REST

**Memory used *continuously*, not just available:** integrations/agent-hooks/ wires six Claude Code hooks — SessionStart/Stop/PreCompact resume and save the working context, PreToolUse requires successful recall before an opted-in repository edit, PostToolUse both records that recall and compiles an oversized tool result *before* it enters the transcript, and PostToolUseFailure records a failed check so the Stop checklist can cite verified outcomes for feedback. One global install covers every project without enabling the edit guard outside explicitly configured repositories.

One memory shared by several clients (Claude Code, Codex CLI, Claude Desktop, Windsurf, Devin CLI): scripts/install-memory-daemon.sh runs velesdb-memory as a single local daemon — HTTPS by default, with a natively generated local CA.

Cargo (Rust + REST server): cargo install velesdb-server velesdb-cli — Docker (multi-arch linux/amd64 + linux/arm64): docker run -d -p 8080:8080 -v velesdb_data:/data --name velesdb ghcr.io/cyberlife-coder/velesdb:latest, then curl http://localhost:8080/health.

Browser / edge: the WASM build is ~710 KB gzipped and runs entirely client-side (TypeScript SDK). REST: 54 REST endpoints (OpenAPI spec). Full matrix: installation guide.

---

Why VelesDB

• One database instead of three. Vectors for *"what feels similar"*, a graph for *"what is connected"*, typed columns for *"what I know for sure"* — normally three deployments, three query languages, and glue code. Here it is one binary and one language.
• A memory that can be audited, not just queried. Every recall can show the evidence behind it; every compression decision carries a rule id, a reason, and a risk level. Deterministic by construction — no model in the write path, so no drift and nothing to re-litigate.
• Local-first is a sovereignty decision, not a latency one. No cloud, no API key, no data processor: air-gapped if you want it, in your jurisdiction by default. Why that matters · positioning in depth.

How it works, in plain terms

Four things happen, and none of them calls an AI provider.

1 · It stores facts, not conversations. You give it one statement — *"the API port is 6333 because 3000 collided with the web UI"* — and it lands in a local file store. No model call, nothing sent anywhere.

2 · It finds them by meaning. Asking *"which port did we settle on"* reaches that fact even though none of the words match. A local embedding model turns text into coordinates; close meaning means close coordinates.

3 · It connects them, and that is the part a search engine cannot do. Each fact is linked to the topics it mentions. why() starts from the best match and then walks those links, so it returns the answer *plus the facts that explain it* — including ones sharing no vocabulary with your question.

The links have to exist. Store facts one by one and the graph stays flat, so

why() behaves like a search. Hand a paragraph to remember_extracted and it

splits it into facts and wires the links for you.

4 · It compresses what is too big, before you pay for it. Give the compiler your accumulated context and a token budget; it returns a smaller version with one recorded decision per fragment — kept, abstracted, or dropped — and a handle to fetch any original back verbatim. Same input, same bytes out, every time. That is what the 82.5 % below measures.

---

What no one else combines

1 · Three engines, one query

One statement crosses all three — similarity, relations and typed filters, no glue code:

MATCH (doc:Document)-[:AUTHORED_BY]->(author:Person)

WHERE similarity(doc.embedding, $question) > 0.8 AND author.department = 'Engineering' RETURN author.name, doc.title ORDER BY similarity() DESC LIMIT 5

2 · A memory that shows its evidence — why()

Most "agent memory" is vector recall: it finds text that *looks like* your query. VelesDB connects memories with typed links, so it can answer *why* something happened by walking the graph to context that shares no words with your question — across process restarts, offline, no API key:

from velesdb import MemoryService            # pip install velesdb

mem = MemoryService("./agent_memory") # a real on-disk store; survives restarts reason = mem.remember("Robert is recovering from knee surgery") mem.remember("Booked the aisle seat on Robert's flight", links=[(reason, "because")])

A *new* process, weeks later, reopens the same store and asks why:

mem.why("why the aisle seat on Robert's flight?") # walks booking → reason — recall() can't

MemoryService defaults to the offline hash embedder: deterministic, but

lexical rather than semantic, so unrelated wording can score 0.000.

Opening it now says so once on stderr. For meaning-based recall, pass

embedder="ollama"; follow Real semantic recall in 5 minutes.

Memories are permanent by default; forget(id) deletes one, ttl_seconds gives a fact a durable expiry. Every remember auto-stamps its storage day, so recency-weighted recall works with zero setup. Same wedge in Python, Node, the MCP server, and in-memory in the TypeScript SDK.

Proof it is not a weak-embedder trick — four runnable demos in which recall stays blind to the reason even under a real semantic embedder (ollama / all-minilm), because the reason is connected by a decision rather than by surface similarity: why_across_sessions.py (survives a process restart) · why_magic_constant.py (a business reason sharing no words with the code) · memory_builds_its_own_graph.py (raw prose in, auto-wired graph out) · why_magic_constant.mjs (Node). Benchmark position, including LoCoMo and why cross-lab scores are not fairly comparable: BENCHMARK.md · Agent Memory guide.

3 · A deterministic context compiler

Agents burn most of their budget re-reading redundant context. compile_context / compile_transcript (MCP, or ContextCompiler in Rust) shrink it with no LLM and no network:

• Deterministic — the same input always compiles to the same bytes, asserted twice per run in every committed benchmark. That also yields a byte-stable cache prefix provider prompt-caching can actually hit.
• Auditable — explain_compilation gives every kept or dropped fragment a stable rule id, a reason and a risk level.
• Reversible — over-budget content becomes a recoverable ctx://source/ handle; retrieve_context_source brings th