Skip to main content
Glama

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).

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.


Related MCP server: gbrain

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

Engine

What it does

Vector

Semantic similarity (HNSW + AVX2/NEON SIMD)

Graph

Typed relationships, BFS/DFS, native MATCH clause (patterns)

ColumnStore

Typed columnar metadata filtering, secondary indexes

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.

recall() finds the booking but misses the reason; why() reaches it through typed links, across a session restart

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 the original bytes back on demand.

  • Bounded — it compresses only what your agent explicitly hands it, never the harness's system prompt, and nothing enters recallable memory without an explicit remember.

Code, URLs, numbers and negative constraints survive verbatim. The velesdb-context-optimizer skill teaches the workflow — including when not to compress.


Proof — three numbers, each tied to its harness

No figure here is an estimate from a slide; each links to the log or script in this repo that produced it.

Claim

Measured

Harness

Real billed dollars saved, same agent session sent raw vs compiled (real Claude billing, deterministic fact-checklist grader — no LLM judge)

21.9 % at real Retina screenshot weight, quality at parity (23.0/23 facts both arms)

real-session-benchmark · raw logs

Real (cl100k) input-token savings on a committed 12-turn agent-session corpus

82.5 %, compiled in ~0.7 ms mean stateless (~24.5 ms with source persistence on)

context_savings

Vector search latency on the full production path (Python SDK → HNSW → payload hydration, WAL ON)

450 us p50 (10K/384D, recall ≥ 96 %), measured 2026-03-27 on 1.7.2, when Balanced ran at ef 128

velesdb_benchmark.py · its report

Same campaign, less flattering: 10.9 % on cropped screenshots, 14.7 % on a 36-turn day-scale arc, 15.1 % input tokens on the direct Messages API, and 2.5 % for the no-screenshots variant — that spread is the measured value of the media mechanisms, so we publish it as prominently as the headline. Honest reading, limitations and full protocol. Every number on this page is CI-guarded by a promise contract that pins the README to its committed sources.

Billed A/B sessions (2026-07-19, claude-sonnet-5; raw logs committed verbatim):

Session

Runner

$ saved

Quality (raw vs compiled)

19-turn feature session, cropped screenshots

Claude CLI

10.9 %

22.8/23 vs 23.0/23 facts

Same session, real Retina-weight screenshots

Claude CLI

21.9 %

23.0/23 vs 23.0/23

36-turn day-scale session

Claude CLI

14.7 %

49.6/50 vs 49.2/50 *

19-turn session, direct Messages API

API

15.1 % input tokens

23.0/23 vs 23.0/23

* Two turns' grading key was later found defective (both arms scored full marks there; the parity conclusion stands) — disclosure. Over a 36-turn session compiled context grows 1.7× slower, so one session lasts far longer before hitting the window.

Memory retrieval quality, public test sets, no AI grader in the loop: +7.2 pts multi-hop (HotpotQA), +9.7 pts time-scoped recall (TimeQA), +29 pts on a controlled task needing both engines at once — BENCHMARK.md.

End-to-end search (canonical): search p50 450 us (10K, 384D, WAL ON; measured 2026-03-27 on 1.7.2, Balanced then at ef 128 — harness, report) · quantization PQ (2 × dim / m smaller: dim/4 at the default m = 8), RaBitQ (32x smaller), SQ8 (4x smaller), Binary (32x smaller) — scope & caveats.

Index-only micro-benchmarks (no WAL, no payload, hot cache — not comparable to the end-to-end figure above), each reproducible with cargo bench -p velesdb-core --bench <name>: HNSW Search index-only (10K/768D, k=10) 55 us (hnsw_benchmark -- hnsw_search_latency) · SIMD Dot Product (768D, AVX2) 21.7 ns (simd_benchmark) · Recall@10 balanced 99.8% and accurate mode 100% (10K/128D, recall_benchmark) · BM25 Sparse Search index-only (10K docs, top-10) 57.6 us (sparse_benchmark -- top10_10k_corpus).

Search mode

ef_search

Recall@10

Use case

Fast

96

97.4%

Real-time suggestions, typeahead

Balanced (default)

160

99.8%

Production search, RAG pipelines

Accurate

512

100%

Evaluation, ground truth comparison

ef_search is each preset's base value, used as-is for k ≤ 32 on up to 10K vectors; ef_search_for_scale raises it beyond. Recall@10: recall_benchmark, 10K/128D, 2026-09-10 on Apple M5 Pro.

Distance metrics — 5 with SIMD acceleration (AVX-512, AVX2, NEON). At 768D on the i9-14900KF reference (AVX2, hot cache; the April 3, 2026 run in docs/BENCHMARKS.md §1): Cosine 32 ns · Euclidean 26 ns · Dot Product 22 ns · Hamming 35 ns · Jaccard 27 ns.

ColumnStore — typed columnar filtering, 130x faster than JSON scanning at 100K rows on the i9-14900KF reference (JSON scan 3.84 ms → ColumnStore 29.5 us). The ratio is hardware-dependent: on Apple Silicon (M5 Pro, 2026-07-20) the JSON scan itself runs ~2.8× faster, so the same bench measures ~50–105x while the ColumnStore's absolute time holds (~27 µs).

Provenance: Intel Core i9-14900KF (x86_64, AVX2). Per-machine figures vary; Apple-Silicon cross-checks, the SIFT1M standardized ANN run and the full methodology live in docs/BENCHMARKS.md. Reproduce the end-to-end figure with python benchmarks/velesdb_benchmark.py --recall.


Pick your entry point

I want to…

Use

Notes

Try it in one file

velesdb (Python 3.9+)

Fastest onboarding path

Embed the engine

velesdb-core (Rust)

The engine itself

Give my agent memory

velesdb-memory

MCP server + context compiler, any MCP client; one-line guided install; .mcpb bundles on the MCP Registry

Call it from Node

@wiscale/velesdb-memory-node

Memory wedge (full engine via server + TS SDK)

Run it in a browser

@wiscale/velesdb-sdk

WASM, ~710 KB gzipped, fully client-side

Serve it over HTTP

velesdb-server

54 REST endpoints — API reference · OpenAPI · server security

Ship on mobile/desktop

velesdb-mobile · Tauri plugin

iOS / Android / desktop

Tool parity per surface is published honestly — including where a surface is still behind: memory crate README. Worked examples: examples/.

Category

Key Endpoints

Collections

POST /collections, GET /collections, GET/DELETE /collections/{name}

Points

/collections/{name}/points, /collections/{name}/points/raw, /collections/{name}/points/scroll, /collections/{name}/stream/insert, /collections/{name}/stream/enable, /collections/{name}/points/{id}/relations, /collections/{name}/points/{id}/ttl, /collections/{name}/relations

Search

/collections/{name}/search, /collections/{name}/search/batch, /collections/{name}/search/hybrid, /collections/{name}/search/text, /collections/{name}/search/multi, /collections/{name}/search/ids, /collections/{name}/match

Graph

/collections/{name}/graph/edges, /collections/{name}/graph/edges/{id}, /collections/{name}/graph/edges/count, /collections/{name}/graph/traverse, /collections/{name}/graph/traverse/stream, /collections/{name}/graph/traverse/parallel, /collections/{name}/graph/nodes, /collections/{name}/graph/nodes/{id}/degree, /collections/{name}/graph/nodes/{id}/edges, /collections/{name}/graph/nodes/{id}/payload, /collections/{name}/graph/search

Indexes

GET/POST /collections/{name}/indexes, DELETE /collections/{name}/indexes/{label}/{property}, /collections/{name}/index/rebuild

VelesQL

/query, /aggregate, /query/explain

Admin

/health, /ready, /metrics, /guardrails, /collections/{name}/stats, /collections/{name}/config, /collections/{name}/flush, /collections/{name}/analyze, /collections/{name}/empty, /collections/{name}/sanity, /collections/{name}/compact, /collections/{name}/vacuum

Full API reference: docs/reference/api-reference.md | OpenAPI spec: docs/openapi.yaml | Server security: docs/guides/SERVER_SECURITY.md

Repository map — every component has its own AGENTS.md

AI agents (and humans) working in this repo should read the root AGENTS.md first, then the AGENTS.md of the component they touch — on conflict, the file closest to the code wins. Harnesses differ in nested-file support (Codex loads each level from the working directory; recent Claude Code attaches a nested AGENTS.md on @-mention; others read the root only), so the component list is the map:

Component

Path

Component AGENTS.md

Engine (VelesQL, HNSW/BM25/ColumnStore, SIMD, storage)

crates/velesdb-core

AGENTS.md

Agent memory MCP server + context compiler

crates/velesdb-memory

AGENTS.md

REST server (Axum)

crates/velesdb-server

AGENTS.md

CLI / interactive VelesQL REPL

crates/velesdb-cli

AGENTS.md

Python SDK (PyO3 + NumPy)

crates/velesdb-python

AGENTS.md

Node binding (napi)

crates/velesdb-node

AGENTS.md

Browser / edge (WASM)

crates/velesdb-wasm + sdks/typescript

AGENTS.md · AGENTS.md

Mobile (UniFFI: iOS/Android)

crates/velesdb-mobile

AGENTS.md

Desktop app embedding (Tauri)

crates/tauri-plugin-velesdb

AGENTS.md

Bulk migration loaders

crates/velesdb-migrate

AGENTS.md

rustdoc link guard

crates/velesdb-rustdoc-guard

AGENTS.md

Python integrations (Haystack, LangChain, LangGraph, LlamaIndex, shared utils)

integrations/

AGENTS.md + one per package (agent-hooks, common, haystack, langchain, langgraph, llamaindex)

Agent session hooks

integrations/agent-hooks

AGENTS.md

CI guards, checks, release + install scripts

scripts/

AGENTS.md

Architecture in one paragraph: ARCHITECTURE.md · storage layout: STORAGE_FORMAT.md · contributing & CI: CONTRIBUTING.md.

How it compares

VelesDB

Chroma

Qdrant

pgvector

Architecture

Vector + graph + columnar, unified

Vector only

Vector + payload

Vector extension for PostgreSQL

Metadata filtering

Typed ColumnStore + secondary indexes

JSON scan

JSON payload

SQL

Graph support

Native (MATCH clause)

No

No

No

Query language

VelesQL (SQL + NEAR + MATCH)

Python API

JSON API / gRPC

SQL + operators

Embeddings from text

Opt-in local / OpenAI adapters; no bundled model

Embedding functions, with a default local model in Python/TypeScript

Opt-in client-side FastEmbed

None; bring vectors from an external model

Deployment

Embedded / Server / WASM / Mobile

Server (Python)

Server (Rust)

Requires PostgreSQL

Binary size

~14 MB

~500 MB (with deps)

~50 MB

N/A (PG extension)

Browser / Mobile

Yes / Yes

No

No

No

Offline / Local-first

Yes

Partial

No

No

Sweet spot: vector + graph + structured filtering in one engine, local-first, auditable. Not the best fit (yet): a managed cloud service with a multi-node distributed cluster. Competitor figures are typical public ranges, not a head-to-head run we performed — run your own. Detailed comparison against agent-memory products (Mem0, Zep, Letta), as of mid-2026: docs/WHY_VELESDB.md.

VelesDB Premium — the enterprise control plane

The core engine is source-available and stays that way. Premium adds the company-grade layer on top of the same binary, for organizations running agent fleets on sensitive data: RBAC on every endpoint including the memory and context-compiler surfaces · audit trail (who, what, when — metadata only, GDPR-conscious) with forensic replay · multi-tenancy with hard per-tenant isolation and two-level deletion rights · clustering and air-gapped deployment · a WebAdmin UI for operators.

Pricing on quote — contact@wiscale.fr · velesdb.com. Built by Wiscale (France; GDPR and data-sovereignty native).


Known limitations — honest boundaries

The items below are deliberate trade-offs or Premium-tracked features, not correctness gaps — the Community Edition is production-ready for single-node, local-first deployments. We publish them next to the strengths, including the ones we have not fixed yet.

#

Limitation

Scope

Tracked

1

Single writer per collection — WAL is serialized; concurrent writers contend on the same fsync lock.

Design trade-off (local-first, crash-safe by default). Read throughput is unaffected.

Concurrent WAL writer planned for Premium. See docs/CONCURRENCY_MODEL.md.

2

No distributed replication — single-node; no Raft, no sharding, no automatic failover in Core.

Deliberate: the sweet spot is local-first / embedded.

Raft-based replication tracked for Premium.

3

No advanced RBAC / multi-tenant isolation in Core — Core ships the DatabaseObserver enforcement seam — live on every HTTP read path since 3.10.0 and still current in 4.0.0 — not the policy engine.

Core ships the hook, not the policy engine.

Premium feature.

4

WASM MATCH: one fixed-length pattern — any number of hops, but multi-pattern MATCH and variable-length relationships ([*1..3]) are rejected with a clear error; both work in native builds.

Browser-build scope limit, not a correctness issue.

Tracked.

5

SIFT1M fingerprint sidecar not yet committed — the loader falls back to TOFU mode until the reference machine commits the pinned hashes.

Not a correctness issue — shape validation still applies.

Bootstrap shipped; sidecar pending.

6

No head-to-head Docker Compose benchmark vs Qdrant / Chroma / FAISS yet — SIFT1M already gives literature-comparable numbers.

Side-by-side numbers need infrastructure not frozen yet.

Tracked.

7

Context-compiler tool parity varies by surface — the MCP server and Rust have the full set; Node, Python and WASM are partially behind, and the WASM working contexts are intra-session only.

Binding scope, not an engine gap; MCP covers any client meanwhile.

Per-surface table in the memory crate README.

Internal technical limitations (query-planner approximations, plan-cache semantics): docs/reference/KNOWN_LIMITATIONS.md.

Contributing & contact

Quality bar: cargo test --workspace — 9k+ tests across Rust, TypeScript and Python run in CI on every merge; exact commands in QUALITY_BAR.md.

Contributions welcome — start with CONTRIBUTING.md and the good first issues. Security reports: SECURITY.md. Roadmap: ROADMAP.md · Changelog · DeepWiki.

License: VelesDB Core License 1.0 (source-available). Premium: commercial license. Contact: contact@wiscale.fr · velesdb.com

The name nods to Veles, a deity of old Slavic myth — a keeper of hidden knowledge and boundaries.

Available Tools

8 tools
forgetA

Delete a memory by id.

Inputs: id (required). Returns: id

recallB

Recall memories semantically similar to a query (vector), most similar first. Optionally narrow to exact-match metadata via filter (ColumnStore), e.g. {"project":"veles","status":"resolved"}.

Inputs: query (required), limit, filter. Returns: memories

recall_fusedA

Fused vector + graph recall: like recall, but also walks the graph from the top vector hit and folds any connected fact into the ranking — the tri-engine ranking (vector similarity + ColumnStore filter + graph reach) measured on multi-hop and temporal benchmarks. Reach for this when an answer needs a fact the query doesn't mention directly but a stored relate/extracted link connects (multi-hop reasoning, temporal chains). hops/graph_boost tune the graph reach; omit them for the proven defaults. Optionally narrow with an exact-match filter. Set date_field (the metadata key holding a YYYYMMDD date) to also get a dated_context timeline and a now anchor for temporal questions. Most relevant first.

Inputs: query (required), hops, limit, filter, +2 more. Returns: now, memories, dated_context

recall_whereA

Fused recall: semantically similar memories (vector) constrained by structured ColumnStore predicates over metadata — ranges and comparisons, not just equality. Each filter is {field, op (eq/ne/lt/le/gt/ge), value}, ANDed. Use for time-windowed or numeric-scoped recall, e.g. facts about a topic with ts in a date range. Most similar first.

Inputs: query (required), limit, filters. Returns: memories

relateB

Create a typed link from one memory to another. Returns the edge id.

Inputs: to (required), from (required), relation (required). Returns: edge_id

rememberA

Store a fact in durable local memory. Optionally link it to existing memories (graph) and tag it with structured metadata like project/author/type/status/date (ColumnStore) for later filtering. Set ttl_seconds to make the fact expire after a delay (a durable TTL that survives restarts); omit it for a permanent memory. Returns the fact's stable id.

Inputs: fact (required), links, metadata, ttl_seconds. Returns: id

remember_extractedA

Store a passage of raw text by extracting its atomic facts and auto-building the fact↔topic graph, so why can later connect them with no manual links. Requires the server to be started with an extraction backend (set VELESDB_MEMORY_EXTRACTOR; build with --features extract). Returns the stored facts' ids.

Inputs: text (required), metadata. Returns: ids

whyA

Explain a decision: find the best-matching memory (optionally scoped by a metadata filter, e.g. the current project) and return the connected subgraph of related memories reachable through typed links — fusing vector, ColumnStore, and graph to surface context a plain similarity search misses.

Inputs: decision (required), filter, max_hops. Returns: edges, nodes

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation4/5

    Tools have distinct purposes (store, retrieve, delete, link, explain, extract), but recall_fused and recall_where both extend recall in different ways, which could cause slight confusion. Why also overlaps somewhat with graph search. Overall mostly clear.

    Naming Consistency5/5

    All tool names use lowercase with underscores for compound names (e.g., recall_fused, remember_extracted). A single word is used for basic operations (relate, forget, recall, remember, why). Naming is consistent and predictable.

    Tool Count5/5

    8 tools cover core memory operations (store, retrieve variants, delete, link, explain, extraction) without being excessive. The count is well-scoped for the server's purpose.

    Completeness3/5

    Missing a direct 'get memory by id' tool; retrieval relies on vector search or filters. No tool to list all links/edges. Core workflows are present but have notable gaps for precise retrieval.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A local-first MCP server for persistent memory with vector search, metadata filtering, fact tracking, and graceful degradation when dependencies fail.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local-first compiled knowledge graph MCP server that provides structured memory for AI agents with full-text search, vector embeddings, and timeline tracking.
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local-first memory server that stores notes, contacts, and future data as a unified entity graph, providing hybrid retrieval (vector + keyword) for AI assistants via MCP.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Self-hosted, local-first knowledge graph and memory server for AI agents. Enables agents to persist, recall, and organize knowledge through MCP with automatic distillation, deduplication, and cross-linking.
      MIT