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: your data never leaves the machine, and there is no LLM and no API key in the memory path. The only outbound call is the server's and CLI's opt-out version check, which sends no stored data — version, edition, OS, architecture, binary name, a CI flag and a hashed install id ( what it sends, how to turn it off ). 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 — the guided installer, one line per OS:

# Linux · macOS

curl -fsSL https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/scripts/install-wizard.sh | sh

# Windows (PowerShell)

irm https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/scripts/install-wizard.ps1 | iex

They work from the first velesdb-memory-v* release that publishes the wizard; until then they say so, and the checkout commands below do the same job. Each one downloads the newest velesdb-memory-v* release's wizard for your machine, checks its .sha256 sidecar, and runs it; nothing is left behind but what the wizard installs. Pass wizard flags with | sh -s -- --dry-run (Windows: & ([scriptblock]::Create((irm …/install-wizard.ps1))) --dry-run). From a checkout, the same wizard runs with Python 3.9+:

python3 scripts/velesdb_install_wizard.py            # interactive: boxed plan + menu [1] apply [2] JSON [3] quit

python3 scripts/velesdb_install_wizard.py --apply # non-interactive apply (CI) python3 scripts/velesdb_install_wizard.py --json # machine-readable plan

The wizard detects your platform (macOS / Linux / Windows) and which harnesses are installed (Claude Code, Codex, Cursor, Cline, Zed, OpenCode, Claude Desktop, Windsurf, Devin, Vibe), checks whether the memory store is already locked by a running process (VELES-031), and picks single-client stdio or one shared local daemon accordingly. A missing velesdb-memory is installed from the latest velesdb-memory-v* release archive (sha256-verified; cargo install as fallback). In daemon mode it runs scripts/install-memory-daemon.sh|.ps1 (launchd on macOS, a systemd user unit on Linux, a Scheduled Task on Windows) and only rewires your harnesses once https://127.0.0.1:18090/health answers. It then installs the skills and the agent hooks — working-context load/save, recall-before-edit and the context compiler for oversized tool results — for every harness that has them; the hooks need bash and jq, and without them the wizard installs none and says what to add. It also settles the embedding model, whose dimension is fixed by the store: by default the one the store records (rewiring never switches a store back to hash), or one you pick — menu [4], or --embedder ollama --embedder-model bge-m3 (also all-minilm 384d, nomic-embed-text 768d, mxbai-embed-large 1024d, or any local Ollama embedding model). It offers to install Ollama and pull the model, probes the model's real dimension, and re-embeds an incompatible store with velesdb-memory migrate-embeddings only with your consent (--yes under --apply). Every config write is backed up and atomic; --apply exits non-zero if any step fails.

Release assets. Every velesdb-memory-v* release built by the current release workflow carries the wizard as a self-contained build — no Python needed: velesdb-install-wizard-x86_64-pc-windows-msvc.exe (Windows x64, also run by Windows on ARM), …-aarch64-apple-darwin.tar.gz and .dmg with a double-click Terminal launcher (Apple Silicon), …-x86_64-unknown-linux-gnu.tar.gz and …-aarch64-unknown-linux-gnu.tar.gz (glibc 2.35+), and velesdb-install-wizard-src.tar.gz for everything else, Intel Macs included (Python 3.9+). Each asset has a .sha256 sidecar and an embedded WiScale publisher signature; to check a download by hand:

python3 scripts/validate_package.py velesdb-install-wizard-x86_64-unknown-linux-gnu.tar.gz   # sha256 sidecar + embedded WiScale signature

The checksum proves the transfer, not the publisher: the sidecar comes from the same release. To build one yourself, python3 scripts/package_wizard.py --apply packages the wizard for the machine it runs on (--source for the source bundle).

Prefer the manual commands? cargo install velesdb-memory, then claude mcp add velesdb-memory -- ~/.cargo/bin/velesdb-memory, and install the skills from a verified release with the repo script:

cargo install velesdb-memory                                    # the local MCP memory server

claude mcp add velesdb-memory -- ~/.cargo/bin/velesdb-memory # any MCP client works python3 scripts/sync-skills.py --install --client all # skills from this checkout

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 return