Crate velesdb_memory 

VelesDB-memory

Local-first memory layer for AI agents, exposed through a single MCP server. This crate is the domain core: it maps nine memory operations onto VelesDB’s in-core Agent Memory SDK.

Operation	Meaning
remember	store a fact (+ optional links to other memories)
recall	semantic retrieval of similar facts
recall_where	semantic retrieval filtered by metadata
recall_fused	vector + graph fused retrieval
relate	create a typed edge between two memories
forget	delete a memory
why	recall + multi-hop graph traversal
feedback	reinforce or penalize a memory after use
remember_extracted	extract facts from raw text and auto-wire the graph

License boundary (non-negotiable)

This crate exposes memory semantics only (results), never raw database capabilities (query(velesql), create_collection, upsert(vectors), traverse(graph)). Exposing the raw engine would constitute a “Substantial Set” of the Software’s features and breach the VelesDB Core License 1.0 (§1, No Hosted or Managed Service). See VISION.md §5 and PLAN.md Phase 4A.

Re-exports

pub use context::ContextCompiler;

pub use dated_context::format_dated_context;

pub use dated_context::DatedContext;

pub use embedder::DynEmbedder;

pub use embedder::EmbedError;

pub use embedder::Embedder;

pub use embedder::HashEmbedder;

pub use error::ErrorCategory;

pub use error::MemoryError;

pub use extract::DynExtractor;

pub use extract::ExtractError;

pub use extract::ExtractedFact;

pub use extract::Extractor;

pub use mcp::McpServer;

pub use model::ColumnFilter;

pub use model::ColumnOp;

pub use model::Explanation;

pub use model::FusionOptions;

pub use model::Link;

pub use model::MemoryEdge;

pub use model::MemoryNode;

pub use model::Recollection;

pub use rerank::DynReranker;

pub use rerank::RerankError;

pub use rerank::Reranker;

pub use service::MemoryService;

pub use service::Metadata;

pub use storage::NativeStore;

pub use storage::MemoryStore;

pub use storage::AUTO_DATE_FIELD;

Modules

context

The deterministic context compiler (EPIC-P-070): classify, dedup, and pack caller-supplied context fragments under a token budget — no LLM, no cloud, every decision auditable. Gated behind the default context feature. The deterministic context compiler (EPIC-P-070).

dated_context

Format recalled facts as a chronological, date-prefixed timeline with a “now” anchor — the dated-context representation measured to lift temporal question answering, shipped as product behavior rather than a harness prompt. Dated context: turn recalled facts into a chronological, date-prefixed timeline with a “now” anchor — the representation measured to lift temporal question answering (the examples/locomo temporal ablation: +33.6pp, McNemar p=1.8e-28). This ships that representation as product behavior so a caller reproduces it through the installed API instead of re-implementing the formatting in a prompt.

embedder

Pluggable text → vector embedding.

error

Error type for the memory layer.

extract

Optional text → facts + entities extraction, the layer that makes the graph self-build.

limits

Resource caps (DoS limits) shared by every adapter — the single source of truth for fact size, recall limit, and why hop depth. Resource caps shared by every adapter (the MCP server and the language bindings).

mcp

The MCP server transport. Gated behind the default mcp feature so library consumers (e.g. the language bindings) can depend on the memory core without pulling the rmcp/tokio server stack. MCP transport: exposes the memory service as MCP tools over stdio.

model

The domain data model — the value types the memory layer exchanges (Link, Recollection, ColumnFilter, Explanation, …), separate from the service that computes them. Domain data model: the request/response value types of the memory layer.

rerank

Optional second-stage re-scoring of a fused recall pool (bring your own cross-encoder/LLM). Never wired in by default — see rerank::Reranker. Optional second-stage re-scoring of a MemoryService::recall_fused candidate pool, the layer that lifts a ranking miss (a relevant fact deep in the pool, below the fusion cutoff) into the final k — the lever validated on the LoCoMo ceiling diagnostic (multi-hop recall@8 = 50%, recall@64 = 89%: the gold fact is IN the pool, just outranked).

service

The memory service: five operations over the in-core Agent Memory SDK.

storage

The storage backend abstraction — storage::MemoryStore and the default, file-backed storage::NativeStore. Implement MemoryStore to run the wedge over a different backend (e.g. an in-memory one for WASM). Storage backend abstraction for crate::service::MemoryService.

Constants

DEFAULT_DIMENSION

Default embedding dimension — the single source of truth, taken from the SDK’s own default so the server, library, and tests never restate the value. velesdb_core::agent (where the canonical constant lives) is itself persistence-gated, so a persistence-free build (e.g. velesdb-wasm) falls back to FALLBACK_DIMENSION.