A
licenseNot graded
qualityD
maintenanceA local-first MCP server for persistent memory with vector search, metadata filtering, fact tracking, and graceful degradation when dependencies fail.
31
MIT
velesdb-memory
VelesDB is a local-first AI agent memory server that fuses vector search, graph traversal, and structured (ColumnStore) filtering into a single standalone binary — enabling durable, explainable memory with no cloud dependency.
remember— Store a fact (permanently or with a TTL) with optional structured metadata (project, author, date, etc.) and typed graph links to other memories.remember_extracted— Feed raw text; the server automatically extracts atomic facts and builds a connected fact↔topic graph with no manual linking required.recall— Retrieve memories by semantic similarity to a natural-language query, with an optional exact-match metadata filter.recall_fused— Fused vector + graph recall: finds top vector hits, then walks the graph to surface connected facts not directly mentioned in the query — ideal for multi-hop and temporal reasoning. Supports adate_fieldoption for chronological context and anowanchor.recall_where— Fused vector + ColumnStore recall with range/comparison predicates (eq,ne,lt,le,gt,ge) over metadata fields, enabling time-windowed or numeric-scoped queries.why— Explain a decision: finds the best-matching memory and returns its connected subgraph of related memories via typed links, fusing vector, ColumnStore, and graph to surface evidence that plain similarity search would miss.relate— Manually create a typed directed edge between two existing memories to build the knowledge graph explicitly.forget— Delete a specific memory by its ID.
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.pyTo 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 discographyAn 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).
Memory used continuously, not just available: integrations/agent-hooks/ wires five Claude Code hooks — SessionStart/Stop/PreCompact resume and save the working context, PreToolUse requires successful recall before an opted-in repository edit, and PostToolUse both records that recall and compiles an oversized tool result before it enters the transcript. 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 ~674 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 toremember_extractedand 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 |
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 52 · 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
MemoryServicedefaults to the offlinehashembedder: deterministic, but lexical rather than semantic, so unrelated wording can score0.000. Opening it now says so once on stderr. For meaning-based recall, passembedder="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_compilationgives 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_sourcebrings 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 (cl100k) input-token savings on a committed 12-turn agent-session corpus | 82.5 %, compiled in ~0.5 ms mean stateless (~27 ms with source persistence on) | |
Vector search latency on the full production path (VelesQL → HNSW → WAL ON → payload hydration) | 450 us p50 (10K/384D, recall ≥ 96 %) |
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) · SIMD dot product 21.7 ns (768D, AVX2) · Recall@10 balanced 98.8 % · quantization PQ (8–32x), RaBitQ (32x), SQ8 (4x), Binary (32x) — 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 accurate mode 100% (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 | 64 | 92.2% | Real-time suggestions, typeahead |
Balanced (default) | 128 | 98.8% | Production search, RAG pipelines |
Accurate | 512 | 100% | Evaluation, ground truth comparison |
Distance metrics — 5 with SIMD acceleration (AVX-512, AVX2, NEON), at 768D/AVX2 on hot cache: Cosine 33 ns · Euclidean 20 ns · Dot Product 22 ns · Hamming 36 ns · Jaccard 35 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 |
| Fastest onboarding path |
Embed the engine |
| The engine itself |
Give my agent memory | MCP server + context compiler, any MCP client; | |
Call it from Node | Memory wedge (full engine via server + TS SDK) | |
Run it in a browser | WASM, ~674 KB gzipped, fully client-side | |
Serve it over HTTP | 54 REST endpoints — API reference · OpenAPI · server security | |
Ship on mobile/desktop | 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 |
|
Points |
|
Search |
|
Graph |
|
Indexes |
|
VelesQL |
|
Admin |
|
Full API reference: docs/reference/api-reference.md | OpenAPI spec: docs/openapi.yaml | Server security: docs/guides/SERVER_SECURITY.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 ( | 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 | ~10 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 | Core ships the hook, not the policy engine. | Premium feature. |
4 | WASM MATCH limited to 2 hops — 3+ hop | 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 toolsforgetA
Delete a memory by id.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Id of the memory to forget. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | Id of the forgotten memory. |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Basic action is clear but no details about side effects (e.g., permanence, permissions) or consequences beyond deletion; no annotations to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple deletion tool with an output schema; could include whether deletion is irreversible or requires confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is already well-described in the schema; the description adds no further semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a memory by id.' uses a specific verb and resource, clearly distinguishing it from sibling tools like recall, remember, or relate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied as a deletion operation but no explicit guidance on when to use it vs. alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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"}.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of memories to return (default 10). | |
| query | Yes | Natural-language query to match semantically. | |
| filter | No | Optional exact-match metadata filter (e.g. `{"project": "veles", "status": "resolved"}`). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| memories | Yes | Recalled memories, most similar first. |
TDQS
B3.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions ordering and optional filter but lacks disclosure of idempotency, side effects, performance, or behavior on no results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given schema coverage is full and output schema exists, description is largely complete. Minor missing detail (e.g., no results handling) but acceptable for a simple recall tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds 'most similar first' and explains filter is exact-match metadata, adding minimal value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Recall' and resource 'memories semantically similar to a query (vector)' with ordering. It's specific but does not explicitly differentiate from sibling tools like recall_fused or recall_where.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for semantic similarity recall with optional metadata filter, but no explicit guidance on when to use this vs alternatives, nor exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hops | No | Graph hops walked from the top vector hit (default 2). Higher reaches further but adds noise; capped at the `why` hop ceiling. | |
| limit | No | Maximum number of memories to return (default 10). Multi-hop reasoning benefits from a larger budget (~32-64); simple and temporal recall saturate early, where a larger budget only adds tokens. | |
| query | Yes | Natural-language query to match semantically. | |
| filter | No | Optional exact-match metadata filter (e.g. `{"project": "veles", "status": "resolved"}`). | |
| date_field | No | Name of the metadata field holding each fact's date as a `YYYYMMDD` integer (e.g. `"ts"`, `"occurred_at"`). When set, the result adds a `dated_context` timeline (facts date-prefixed and ordered oldest-first) plus a `now` anchor — the representation that lifts temporal reasoning. Omit for plain results. | |
| graph_boost | No | Weight added to a graph-reached fact's normalised vector score (default 0.15). Raise to trust the graph more, lower to trust vector similarity more. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| now | No | The most recent date across `memories` (`YYYY-MM-DD`), the "now" anchor. Present only when `date_field` was set and at least one fact is dated. |
| memories | Yes | Recalled memories, most relevant first. |
| dated_context | No | Chronological, date-prefixed rendering of `memories` (`- [YYYY-MM-DD] content` per line, oldest first, undated facts last). Present only when `date_field` was set. |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Discloses non-destructive behavior, effect of graph walking, tuning parameters, and temporal timeline addition. Mentions noise from higher hops.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact but informative; front-loaded with key concept. Every sentence adds value, though slightly dense. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (multi-hop, temporal, filtering, tuning) and presence of output schema, description covers all essential aspects. Could mention default limit more explicitly, but still complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100%, baseline 3. Description adds significant value: explains defaults, interaction between hops and graph_boost, why larger limit benefits multi-hop, and how date_field enables timeline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it's a fused vector+graph recall, distinguishes from siblings like `recall` and `recall_where`, and explains the tri-engine ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (multi-hop reasoning, temporal chains) and when to omit parameters for defaults. Does not mention when not to use, but provides enough context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of memories to return (default 10). | |
| query | Yes | Natural-language query to match semantically. | |
| filters | No | Structured `ColumnStore` predicates (ranges/comparisons) combined with AND, e.g. a date window `[{"field":"ts","op":"ge","value":20230101}, {"field":"ts","op":"le","value":20231231}]`. Each `op` is one of `eq`/`ne`/`lt`/`le`/`gt`/`ge`. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| memories | Yes | Recalled memories, most similar first. |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral traits. It explains the fused nature (vector + ColumnStore predicates), the filter format, and result ordering ('Most similar first'). It does not explicitly state it is a read-only operation or mention pagination, but the core behavior is transparent enough for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences that front-load the key concept ('Fused recall'), immediately followed by filter format and usage example. Every sentence is informative with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (vector + structured constraints) and that an output schema exists, the description is reasonably complete. It explains the AND combining logic, gives a concrete example, and mentions ordering. It does not detail response format (covered by output schema) or edge cases, but covers the essential context for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining the filter structure as {field, op, value} with supported ops and an example date window, which is more intuitive than the formal schema definition. This enriches the agent's understanding beyond the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs 'fused recall' combining vector semantic search with structured metadata predicates, explicitly mentioning support for ranges and comparisons beyond equality. It distinguishes from sibling 'recall' by specifying the structured filter capability, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Use for time-windowed or numeric-scoped recall' with an example (facts about a topic with `ts` in a date range). It implies that for equality-only filters, a simpler tool like 'recall' might be appropriate, but does not explicitly exclude other scenarios or compare to all siblings like 'recall_fused'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
relateB
Create a typed link from one memory to another. Returns the edge id.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Target memory id. | |
| from | Yes | Source memory id. | |
| relation | Yes | Relationship label. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| edge_id | Yes | Id of the created edge. |
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It does not disclose whether the operation is destructive, if duplicate links are allowed, or if permissions are needed. The only behavioral hint is that it returns an edge ID.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences with no superfluous content. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks context about the nature of typed links, constraints, or the response format. It is insufficient for a tool with three fully required parameters and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds no extra meaning beyond 'typed link', and does not explain the 'relation' parameter or the expected format of links.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a typed link between two memories and returns the edge ID, which is a specific verb-resource pair. It distinguishes from siblings like recall, forget, and remember, which are unrelated operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, or when not to use it. The description only says what it does, but provides no context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fact | Yes | The fact to store in memory. | |
| links | No | Optional typed links from this fact to existing memories. | |
| metadata | No | Optional structured metadata for later filtering (e.g. `{"project": "veles", "author": "julien", "status": "open"}`). | |
| ttl_seconds | No | Optional time-to-live in seconds. When set, the fact expires (and stops being recalled) after this many seconds — a durable TTL that survives a restart. Omit for a permanent memory. Falls back to the server's `VELESDB_MEMORY_DEFAULT_TTL` when unset. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | Stable id assigned to the remembered fact. |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that storage is durable, TTL survives restarts, and returns a stable id. However, it does not mention behavior on duplicates or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and every sentence adds value. It is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, full schema coverage, and an output schema (not shown), the description covers purpose, all parameter behaviors, and the return value (stable id). It is complete for a store operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning: explains TTL_seconds' durable nature and default fallback, links as typed relations, and metadata for filtering. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the primary action: 'Store a fact in durable local memory.' It distinguishes from siblings by mentioning optional linking and metadata tagging, which are unique features of this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use optional parameters like links and metadata for later filtering, and explains TTL behavior. It does not explicitly mention when not to use this tool, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Raw text to extract atomic facts from and store as a connected graph. | |
| metadata | No | Optional structured metadata applied to every extracted fact. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| ids | Yes | Stable ids of the stored facts, in extraction order. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the extraction process, graph building, and return of fact IDs. It mentions prerequisites but does not detail potential side effects like overwriting or merging.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundant words, front-loaded with purpose and benefit. The prerequisite and return values are efficiently stated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and presence of an output schema, the description covers inputs, process, prerequisites, and output. It could mention idempotency or duplicate handling, but is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond schema descriptions; for 'text' it is nearly identical, and for 'metadata' it adds no extra context. No meaningful enhancement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool stores raw text by extracting atomic facts and building a fact-to-topic graph, differentiating it from sibling tools like `remember` and linking to `why`. The verb 'store' and resource 'passage of raw text' are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit prerequisites (server started with extraction backend) and implies the tool is for automatic fact extraction and linking. It does not explicitly state when not to use or list alternatives, but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Optional exact-match metadata filter to scope the seed (e.g. `{"project": "veles"}`). | |
| decision | Yes | The decision (or fact) to explain. | |
| max_hops | No | How many hops of typed links to follow (default 2). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| edges | Yes | Typed edges connecting the nodes. |
| nodes | Yes | Memories in the subgraph, seed first. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently describes the tool's behavior: finding the best-matching memory optionally scoped by a filter, and returning a connected subgraph through typed links with configurable max_hops. It does not disclose potential side effects or permissions, but for a read-like tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and efficiently conveys the tool's unique value proposition without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (graph traversal, fusing search methods) and the presence of an output schema, the description is fairly complete. It explains the process and result, though it could elaborate on the nature of 'typed links' or the subgraph structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description mentions optional filter scoping and max_hops implicitly via 'reachable through typed links', but does not add significant new meaning beyond what the schema already provides for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it explains a decision by finding a best-matching memory and returning a connected subgraph of related memories via typed links. It distinguishes itself from siblings like 'recall' by highlighting the fusion of vector, ColumnStore, and graph search to surface context beyond plain similarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a plain similarity search is insufficient, providing context for when the tool is most valuable. However, it does not explicitly state when not to use it or directly compare with sibling tools like 'recall_where' or 'recall_fused'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
A3.9/5.0
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
ResponsivenessWithin a week
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA local-first compiled knowledge graph MCP server that provides structured memory for AI agents with full-text search, vector embeddings, and timeline tracking.4158MIT
- AlicenseAqualityAmaintenanceLocal-first, source-traceable memory for AI agents — no LLM at ingest, $0 per message, zero data egress. Gives Claude Code, Cursor, and any MCP client one shared persistent memory with semantic recall, belief revision, selective forgetting, and a provenance guard that blocks acting on stale or unconfirmed memories.2314MIT
- AlicenseNot gradedqualityCmaintenanceLocal-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.MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/cyberlife-coder/VelesDB'
If you have feedback or need assistance with the MCP directory API, please join our Discord server