Struct MemoryService 

pub struct MemoryService<E: Embedder, S: MemoryStore = NativeStore> { /* private fields */ }

Local-first agent memory backed by a single VelesDB instance.

Generic over the Embedder so production can use an on-device model while tests use a deterministic, network-free one, and over the MemoryStore backend S so the same orchestration runs over the native, file-backed engine (the default — nothing changes for existing callers) or any other backend that implements the trait (e.g. an in-memory one for WASM).

Two definitions, persistence-gated: the default type parameter itself references NativeStore, which doesn’t exist as a type at all without the feature, so a persistence-free build (e.g. velesdb-wasm) drops the default and every caller names its own MemoryStore backend explicitly.

Implementations

impl<E: Embedder, S: MemoryStore> MemoryService<E, S>

pub fn recall_fused( &self, query: &str, k: usize, filter: Option<&Metadata>, opts: FusionOptions, ) -> Result<Vec<Recollection>, MemoryError>

Fused recall: like Self::recall, but also walks the graph from the query’s top vector hit and folds any fact it reaches (hop ≥ 1) into the ranking, scored by opts.graph_boost · graph_weight on top of its normalised vector similarity. A fact the graph reaches never displaces a strong vector hit unless the boosted score genuinely outranks it; a fact the vector pool ranked low (or missed) can still surface if the graph connects it. This is the tri-engine ranking measured on HotpotQA/TimeQA/LoCoMo (examples/multihop, examples/timeqa, examples/locomo) — Self::recall stays pure-vector and unchanged, so existing callers see no behavior shift.

The graph reach requires a wired graph to find anything: it walks edges from Self::relate or the entity hubs Self::remember_extracted auto-wires. Entity hubs themselves are never returned, exactly like Self::recall.

Errors

Returns MemoryError if embedding, vector search, or graph traversal fails.

pub fn recall_fused_reranked<R: Reranker>( &self, query: &str, k: usize, filter: Option<&Metadata>, opts: FusionOptions, reranker: &R, ) -> Result<Vec<Recollection>, MemoryError>

Like Self::recall_fused, but hands the FULL fused-ranked candidate pool (before the final k cutoff) to reranker for a second-stage re-score, then truncates to k. Closes the ranking-miss gap the LoCoMo ceiling diagnostic found: a relevant fact can be IN the pool (recall@64 ≈ 89% on multi-hop) yet outranked out of a tight k (recall@8 ≈ 50%) — a reranker recovers it without widening k itself.

No built-in reranker ships: bring your own (cross-encoder, LLM judge, …) via Reranker. Never call this as a default — a reranker can also hurt out-of-distribution conversational queries (measured on LoCoMo), so it is opt-in, one call at a time.

Errors

Returns MemoryError if embedding, vector search, graph traversal, or reranker itself fails.

impl<E: Embedder> MemoryService<E, NativeStore>

pub fn open<P: AsRef<Path>>(path: P, embedder: E) -> Result<Self, MemoryError>

Open (or create) a native, file-backed memory store at path, using embedder for text vectorization. The store never leaves this directory.

Errors

Returns MemoryError if the store cannot be opened or the agent memory cannot be initialized for the embedder’s dimension.

impl<E: Embedder, S: MemoryStore> MemoryService<E, S>

pub fn with_store(store: S, embedder: E) -> Self

Build a service directly over a store backend, bypassing Self::open’s filesystem-specific setup — the constructor a non-native backend (e.g. velesdb-wasm’s in-memory store) uses.

pub fn remember( &self, fact: &str, links: &[Link], metadata: Option<&Metadata>, ) -> Result<u64, MemoryError>

Remember a fact, optionally tagging it with structured metadata (ColumnStore facet) and linking it to existing memories (graph facet). Returns the stable id of the fact (idempotent on identical content).

Every link is validated — target existence AND relation label — before the fact is stored, so bad link input never leaves the fact half-written. If an edge write itself fails afterwards (e.g. a target expiring concurrently), a freshly-created fact is rolled back; a re-remembered fact keeps its updated payload (re-remembering updates metadata by design, and deleting it would destroy prior state). Concurrent remembers of identical content are last-writer-wins, not transactional.

Errors

Returns MemoryError::EmptyFact for empty/whitespace facts, MemoryError::ReservedKey if metadata names a reserved key (content or any _veles_-prefixed system key), MemoryError::UnknownMemory if a link points at a missing memory, MemoryError::InvalidRelation for a bad relation label, MemoryError::RollbackFailed if an edge write failed and the compensating delete also failed (the fact remains stored), or a storage error if persistence fails.

pub fn remember_with_ttl( &self, fact: &str, links: &[Link], metadata: Option<&Metadata>, ttl_seconds: Option<u64>, ) -> Result<u64, MemoryError>

Like Self::remember, but the fact expires after ttl_seconds.

The expiry is a durable TTL — persisted with the fact (reserved _veles_expires_at payload field), so it survives a process restart, and expired facts stop being recalled. None (or Some(0)) stores the fact permanently, exactly like Self::remember. Metadata and a TTL combine: the metadata is written and the expiry preserved.

Errors

Same as Self::remember.

pub fn remember_extracted<X: Extractor>( &self, text: &str, extractor: &X, metadata: Option<&Metadata>, ) -> Result<Vec<u64>, MemoryError>

Remember a passage of raw text by running it through an Extractor and storing every fact it yields, auto-wiring the fact↔entity graph.

This is the commodity on top of Self::remember’s bring-your-own-links core: each extracted fact is stored (tagged with metadata), each salient topic becomes a deduplicated hub memory, and every fact is linked to its topics with a bidirectional about/mentions edge. Two facts sharing a topic therefore become reachable from one another, so Self::why has a real graph to traverse with no manual relate().

Entity hubs are content-addressed, so the same topic seen across many calls collapses onto one hub. Returns the ids of the stored facts (entity hubs excluded), in extraction order.

Errors

Returns MemoryError::EmptyFact for empty/whitespace text, MemoryError::Extract if extraction fails, MemoryError::ReservedKey if metadata names a reserved key, or a storage error if persistence fails.

pub fn recall( &self, query: &str, k: usize, filter: Option<&Metadata>, ) -> Result<Vec<Recollection>, MemoryError>

Recall up to k memories semantically similar to query (vector facet), optionally narrowed to an exact-match metadata filter (ColumnStore facet) — e.g. { "project": "veles", "status": "resolved" }.

A highly selective filter may return fewer than k hits even when more matches exist — raise k for fuller coverage with a narrow filter.

Entity hubs created by Self::remember_extracted are never returned: they are internal graph scaffolding, not facts the caller stored.

Each hit carries its caller metadata (Recollection::metadata, None when the fact carries none) — store a date field (e.g. occurred_at) and it round-trips here, so a caller can sort the result into a chronological, date-stamped context without recall_where’s explicit filters. One extra, single batched lookup covers every returned hit.

Errors

Returns MemoryError if the semantic query or the metadata lookup fails.

pub fn recall_where( &self, query: &str, k: usize, filters: &[ColumnFilter], ) -> Result<Vec<Recollection>, MemoryError>

Fused recall: semantic NEAR search combined with structured ColumnStore predicates over metadata columns — ranges and comparisons, not just the equality of Self::recall. One query spanning the vector and column facets (e.g. “most similar facts with timestamp in this window”), which a vector-only or equality-only recall cannot express.

Filter values are bound as query parameters (never interpolated), so they cannot inject; filter field names are validated to be plain identifiers. Results come back in similarity order.

Errors

Returns MemoryError::InvalidFilter if a filter field is not a plain identifier, MemoryError::Embed if the query cannot be embedded, or a storage error if the query fails. An empty query or k == 0 yields [].

pub fn relate( &self, from: u64, to: u64, relation: &str, ) -> Result<u64, MemoryError>

Create a typed edge from -> to. Returns the edge id.

Both endpoints are validated to exist first, so the tool reports an unknown id as client input (UnknownMemory) rather than a generic storage fault — and the graph never gains an edge dangling off a memory that was never stored.

Errors

Returns MemoryError::UnknownMemory if either endpoint is missing, or a storage error if the edge cannot be created.

pub fn forget(&self, fact_id: u64) -> Result<(), MemoryError>

Forget (delete) the memory with fact_id.

Errors

Returns MemoryError if the deletion fails.

pub fn why( &self, decision: &str, max_hops: usize, filter: Option<&Metadata>, ) -> Result<Explanation, MemoryError>

Explain a decision: find the best-matching memory (optionally scoped to a metadata filter, e.g. the current project), then walk its typed links up to max_hops away — fusing the vector, ColumnStore, and graph facets.

Returns an empty Explanation when nothing matches the decision.

Errors

Returns MemoryError if recall or graph traversal fails.