velesdb-memory

The explainable, local-first memory engine for AI agents, as a single MCP server.

Portability: ✅ the server and all of its tools work in any MCP client over stdio · ⚙️ sharing one store between several clients at once requires the HTTP transport (--features http) · ⚠️ the .mcpb bundles are a one-click packaging format (Claude Desktop and registry-aware clients), not a transport, and are built stdio-only · ⚠️ the automatic agent hooks are harness-specific, and tool-result replacement (updatedToolOutput) is Claude Code only.

Objective

A coding agent forgets everything between sessions, and a vector store only gives it back text that looks like the question. Neither can answer "why did we do this?", because the answer is usually a fact that shares no words with the question — the ticket behind the decision, the incident behind the constant.

velesdb-memory gives an agent durable memory that never leaves the machine: it remembers facts, recalls them semantically, connects them with typed links, and walks those links to return the evidence trail behind an answer. It also ships a deterministic context compiler that shrinks an agent's prompt under a hard token budget with no model call at all.

What you actually gain

Two problems cost you real money and real quality every day, and this fixes both.

Your agent forgets. Close the session, and everything it learned about your codebase is gone. Tomorrow you explain it again. velesdb-memory keeps those facts on your disk and hands them back at the start of the next session.

Every turn re-sends the whole conversation. That is what you are billed for, and a context stuffed with repeated logs is also a context where the model pays less attention to what matters. The compiler shrinks that payload before it is sent — deterministically, with no AI call of its own.

The honest part: those percentages come from our corpus on our sessions. The spread is published as prominently as the best figure, and every number above is pinned to its source by a contract the CI enforces — if a figure drifts from what the code produces, the build goes red.

How it works, in four steps

Nothing here needs an AI provider. Everything runs on your machine.

1. It stores facts, not transcripts. You (or your agent) call remember with one fact: "the API port is 6333 because 3000 collided with the web UI". It is written to a local file store. No model call, no network.

2. It finds them by meaning, not keywords. recall matches on sense, so asking about "which port did we settle on" finds that fact even though the words differ. This uses a local embedding model of your choosing — and the honest caveat is that until you pick one, the out-of-the-box default is a deterministic offline embedder that matches surface form, not meaning (great for zero-dependency demos, wrong for real recall). Picking a real model is one env var, no rebuild: two commands, below.

3. It connects them, which is the part that matters. Facts are linked to the topics they mention. 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 words with your question. A plain search cannot do that.

Those links have to exist. If you only ever call remember, the graph stays flat and why behaves like a search. Point remember_extracted at a paragraph and it splits it into facts and wires the links for you.

4. It compresses what is too big, at the right moment. Five agent hooks fire automatically in Claude Code: two remind it to save and reload its state around a session, one does the same before a compaction, PreToolUse requires successful recall before an opted-in repository edit, and PostToolUse is the one that replaces an oversized Bash result with a schema-compatible compiled view — so the bulky text never enters the conversation when Claude accepts the replacement. Nothing is deleted: the complete original Bash output object is serialized as JSON and its path is quoted in the replacement, so the agent can read the full thing whenever the compiled view is not enough.

Use cases

• A coding agent that must still know, three weeks later, why a timeout is set to 8 s — and can show the PR and the incident it came from.
• Regulated or air-gapped work where context cannot transit a third-party LLM API, and "show why it recalled that" has to be answerable.
• Long agent sessions that hit the context window: compile the prompt instead of summarizing and restarting.

Prerequisites

Installation

cargo install velesdb-memory

No Rust toolchain? velesdb-memory is on the MCP registry as io.github.cyberlife-coder/velesdb-memory, with prebuilt .mcpb bundles on each release. Full options: MCP server setup.

First success in 60 seconds

Wire it into Claude Code:

claude mcp add velesdb-memory \
  --env VELESDB_MEMORY_PATH="$HOME/.velesdb-memory" \
  -- ~/.cargo/bin/velesdb-memory

Then ask your agent to store a decision and recall it. These are the MCP calls it makes, and exactly what comes back:

remember { "fact": "we chose parking_lot to avoid lock poisoning",
           "metadata": { "project": "checkout" } }
→ { "id": 9876543210, "id_str": "9876543210" }

recall { "query": "locking strategy", "limit": 5 }
→ { "memories": [ { "id": 9876543210, "id_str": "9876543210",
                    "score": 0.59,
                    "content": "we chose parking_lot to avoid lock poisoning",
                    "metadata": { "project": "checkout", "_veles_date": 20260725 } } ] }

A non-empty memories array means the server is wired and the store is writable. (_veles_date is stamped automatically — see automatic dating.)

Every other client — Cursor, Zed, Codex CLI, Claude Desktop, Windsurf, Devin CLI — is one config block away in MCP server setup.

Real semantic recall in 5 minutes

The 60-second setup above runs the offline hash embedder: deterministic, zero-dependency — and lexical, not semantic. Both semantic backends are compiled into the binary you just installed, so upgrading is configuration, not a rebuild. With Ollama installed, the recommended model is bge-m3 (multilingual, 1024-dim):

ollama pull bge-m3
claude mcp add velesdb-memory \
  --env VELESDB_MEMORY_PATH="$HOME/.velesdb-memory" \
  --env VELESDB_MEMORY_EMBEDDER=ollama \
  --env VELESDB_MEMORY_EMBEDDER_MODEL=bge-m3 \
  -- ~/.cargo/bin/velesdb-memory

No Ollama? Any OpenAI-compatible server (oMLX, llama.cpp, LM Studio, vLLM) works with VELESDB_MEMORY_EMBEDDER=openai and a URL — the model still runs on your machine, and memory still never leaves it. All options: embedding backend.

Two things to know when switching:

• Your agent can check. The memory_status tool reports which embedder actually runs and whether recall is semantic — ask "call memory_status" and read embedder.semantic. The server also flags a degraded (hash) run in its instructions to every connecting client.
• Your memories survive the switch. The store records which model filled it; on a mismatch the server refuses to serve nonsense and names the migration command (velesdb-memory migrate-embeddings, dry-run first), which re-embeds every fact under its original id. Switching embedders never costs you your memories.

See the wedge (offline, one command)

cargo run -p velesdb-memory --example wow_offline

recall("why we chose parking_lot")   [vector similarity only]
   0.47  we chose parking_lot to avoid lock poisoning after a panic
   0.18  PR #42 swaps the std Mutex for parking_lot
   └─ EPIC-317 is nowhere here — it shares no words with the question.

why("why we chose parking_lot")      [vector seed + graph traversal]
   hop 0  we chose parking_lot ...
   hop 1  PR #42 ...
   hop 2  EPIC-317: intermittent CI hang under load
   └─ the graph reached the very ticket the decision fixed.

A vector search ranks by resemblance, so it is blind to the ticket. why() follows the typed links and reaches it. That gap is the product.

Not a weak-embedder trick. In each retrieval demo, recall stays blind to the reason even under a real semantic embedder (ollama / all-minilm), not just the offline hash default.

The graph's contribution, isolated

cargo run --release -p velesdb-memory --example bench_multihop runs 24 decision → PR → problem chains with the same embedder throughout and only the graph toggled. Each question ("why did we adopt <tech>") has a 1-hop answer (the decision, which shares words) and a 2-hop answer (the original problem, which shares none):

The direct control confirms the vector engine is healthy — it aces look-alike retrieval. On multi-hop, a real semantic embedder still recovers only a third of the answers; the graph recovers all of them, +67 pp with a real model. Run that arm yourself:

cargo build --release -p velesdb-memory --features ollama && ollama pull all-minilm
VELESDB_MEMORY_EMBEDDER=ollama \
  cargo run --release -p velesdb-memory --features ollama --example bench_multihop

bench_multihop measures the engine's contribution on controlled data with the graph pre-wired, so the numbers reflect retrieval, not an LLM. The end-to-end extraction comparison on the real LoCoMo dataset lives in examples/locomo/.

What the server exposes

22 MCP tools in the default build, in three families:

Parameters, returns, and error codes for every one: MCP tool reference.

By design the server exposes memory semantics only — never raw database capabilities (query, create_collection, upsert, traverse).

Where to go next

Measured, generation-free retrieval lift against a pure-vector baseline on public datasets — HotpotQA +7.2 pp, 2WikiMultiHopQA +2.1 pp overall, TimeQA +9.7 pp, tri-engine +29 pp — is tabulated with its full method in BENCHMARK.md.

Compatibility

Other verified clients: Cursor, Cline, Zed, opencode, Devin CLI.

Known limits

• Memory semantics only. No query, create_collection, upsert, or traverse — deliberate, and enforced by the tool surface.
• One process per store. The store takes a single-writer flock, so two stdio clients against the same VELESDB_MEMORY_PATH fail with Storage(DatabaseLocked). Run the HTTP daemon to share one memory across clients.
• The HTTP transport has no authentication. It binds loopback-only by default; a non-loopback bind is refused unless you explicitly allow it, and is only safe behind an authenticating reverse proxy.
• A store is fixed to one embedder. The embedding dimension is probed from the model, so do not switch embedders on an existing store.
• Bring-your-own-links by default. The graph is built by relate and links; automatic extraction needs --features extract plus a local model.
• path ingestion is off unless allowlisted via VELESDB_MEMORY_INGEST_ROOTS.
• Binding parity is incomplete. compile_transcript is MCP-only; the Node binding has no context_savings / explain_compilation; the published PyPI wheel predates the compiler entirely — see the surface matrix.
• No selective source purge. Compiled sources are kept permanently by default; you can set a TTL going forward, or delete the whole store.

Troubleshooting

License

The distributed binary embeds velesdb-core and is governed by the VelesDB Core License 1.0 (source-available): a derivative of the Elastic License 2.0, not an OSI-approved license. The wrapper source in this crate is intentionally readable and forkable.

• Can you use it at work, or in a commercial product? Yes. Running the server locally, or embedding the library inside your own application where your users only ever receive results, is the license's expressly-permitted embedded, local-first use.
• What is forbidden? Re-hosting VelesDB as a multi-tenant service where third parties drive the database. This server makes that impossible by design: memory semantics only, never raw query / create_collection / upsert / traverse.
• What do you owe when redistributing? Keep the LICENSE file and copyright notices, and add a velesdb.com attribution in any public app that ships the binary. Internal, dev, and test use need no attribution.

Full terms and the canonical FAQ: LICENSE. Questions: contact@wiscale.fr.

velesdb-memory v0.12.0 · Last updated: 2026-08-08 · Report a docs error