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_dated( &self, query: &str, k: usize, filter: Option<&Metadata>, opts: FusionOptions, date_field: &str, ) -> Result<(Vec<Recollection>, DatedContext), MemoryError>

Self::recall_fused paired with the dated-context rendering of its results: returns the recalled facts and the DatedContext built from their date_field metadata (see format_dated_context). Every binding that exposes a “dated recall” (the MCP recall_fused tool’s date_field, Node/WASM recallFusedDated) calls this, so the “recall then format” pairing lives in exactly one place and can’t drift between surfaces.

date_field can name any caller metadata key, but passing crate::storage::AUTO_DATE_FIELD needs zero setup: remember auto-stamps that key on every fact already, so a caller gets a correct dated_context without ever having managed a date field itself.

Errors

Returns MemoryError if the underlying Self::recall_fused 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, S: MemoryStore> MemoryService<E, S>

pub fn feedback(&self, id: u64, success: bool) -> Result<f32, MemoryError>

Record an outcome for a recalled fact and return its new confidence.

success = true reinforces the fact (it was useful), false weakens it (it was noise). The update is applied by a ReinforcementStrategy (FixedRate by default) over the fact’s current confidence and its success/failure history, then persisted durably. Over repeated feedback the fact drifts up or down the Self::recall ranking — the agent’s memory learns which facts are worth surfacing.

Concurrency

The update is a read-modify-write that is not atomic across the get_metadata/update_metadata pair. Two feedback calls racing on the same id are last-writer-wins: one increment can be lost. This is acceptable for a soft, approximate ranking signal — feedback still moves confidence in the right direction — but callers needing exact tallies must serialize their own calls per id.

Errors

Returns MemoryError::UnknownMemory if id is not a live fact, or a storage error if the read-back or persist fails.

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

pub fn compile_context( &self, compiler: &ContextCompiler, request: &CompileRequest, ) -> Result<CompiledContext, MemoryError>

ContextCompiler::compile with this service’s memory folded in: when the request carries a MemoryScope, relevant memories are pulled through the fused vector+graph recall and compiled alongside the caller’s fragments, each with its memory_id and a normalised fused-ranking relevance recorded in provenance. Afterwards (policy permitting) the distinct originals are stored so every ctx://source/<hash> handle round-trips, and a metadata-only compilation event is recorded for Self::context_savings.

Errors

Returns MemoryError if compilation itself fails (budget, caps), or if recall, embedding, or storage fails.

pub fn compile_context_reranked<R: Reranker>( &self, compiler: &ContextCompiler, request: &CompileRequest, reranker: &R, ) -> Result<CompiledContext, MemoryError>

Self::compile_context with a caller-supplied crate::Reranker driving memory selection: the reranker receives the FULL fused candidate pool (vector + graph, before the k cutoff) and its ordering decides which k memories are compiled in — the seam for a semantic cross-encoder or LLM judge a Rust embedder brings along. Not exposed on the wire (a reranker is code, not JSON), and never a default: the shipped crate::context::DeterministicReranker is lexical, and a lexical second stage demotes exactly the zero-vocabulary-overlap evidence the graph walk rescues (measured in the BDD suite) — bring a semantic one.

Errors

Returns MemoryError if compilation, recall, the reranker itself, or storage fails.

pub fn retrieve_context_source( &self, handle: &str, ) -> Result<ContextSource, MemoryError>

The original content — and media, when the fragment carried one — behind a ctx://source/<hash> handle.

Errors

Returns MemoryError::UnknownHandle when the handle is malformed or nothing is stored under it (never stored, expired, or forgotten).

pub fn explain_compilation( &self, request: &CompileRequest, fragment_id: u64, fragment_index: Option<usize>, ) -> Result<ContextDecision, MemoryError>

Explain why one fragment of request was preserved, abstracted, externalized, dropped, or cached — the selection primitive the MCP explain_compilation tool delegates to, extracted here so every adapter (MCP, Node, Python) shares one implementation instead of reimplementing it. Compilation is deterministic, so request is simply re-compiled — with event/source recording forced off, since an explanation must not have side effects — and the matching decision is returned.

fragment_index (0-based position in request.fragments), when given, TAKES PRIORITY over fragment_id for locating the decision: compile_context records exactly one decision per input fragment, in order, so decisions[fragment_index] is unambiguous even when several fragments are byte-identical and therefore share the same content-addressed fragment_id — a plain fragment_id lookup always resolves to the FIRST such decision (the deduplication survivor’s), never a dropped twin’s.

Caveat inherited from re-compiling rather than replaying stored state: with a memory_scope the re-compile recalls from CURRENT memory, so the decision reflects memory as it is now, not as it was at the original compile_context call; a caller that already resolved a path fragment to content is unaffected (this method does no I/O of its own).

Errors

Returns MemoryError::FragmentIndexOutOfBounds when fragment_index is beyond request.fragments, MemoryError::FragmentNotFound when no decision matches the selector, or any error Self::compile_context itself can return (budget, caps, recall, embedding, storage).

pub fn context_savings( &self, project: Option<&str>, ) -> Result<ContextSavings, MemoryError>

Aggregate the recorded compilation events, optionally per project. Sweeps at most crate::limits::MAX_RECALL_LIMIT events (newest need not be first — the sweep is similarity-ordered over a constant anchor, i.e. effectively the whole family until the cap); ContextSavings::truncated reports when the cap was hit.

Errors

Returns MemoryError if the underlying filtered recall fails.

pub fn save_working_context( &self, project: &str, session: &str, working: &WorkingContext, ) -> Result<u64, MemoryError>

Persist working under project + session (idempotent upsert: saving again replaces the previous state). Returns the system fact id.

Serialized size is capped at crate::limits::MAX_FACT_BYTES (1 MiB) — the same ceiling every other stored fact honors — checked BEFORE anything is written, so an oversized working context is never partially stored.

Errors

Returns MemoryError::WorkingContextCodec if serialization fails, MemoryError::ContextOverLimit if the serialized working exceeds crate::limits::MAX_FACT_BYTES, or a storage/embedding error.

pub fn load_working_context( &self, project: &str, session: &str, ) -> Result<Option<WorkingContext>, MemoryError>

The working context previously saved under project + session, None when there is none.

Symmetric to Self::context_source_metadata’s squatter guard: the slot is only ever served back when its metadata carries the reserved [CTX_WORKING_FIELD] marker (set exclusively by Self::save_working_context). A slot occupied by an unmarked caller fact — one that happened to land on this salted id, or a forged probe — is indistinguishable from “nothing saved” on purpose: None, never the forged content, and never an error (the caller cannot tell a squatted slot from a genuinely empty one, which is the point — it must never learn that something occupies this id).

A pure read: it never writes, never prunes, never heals. Index convergence happens on the WRITE path (Self::update_working_index) — a lookup that rewrites shared state turns every transient miss into permanent data loss and cannot safely be retried.

Errors

Returns MemoryError::WorkingContextCodec if the stored payload does not parse, or if the slot is marked but its body is gone (a torn fact is corruption — reporting it as “nothing saved” would tell the caller the one thing that is certainly false), or a storage error.

pub fn list_working_contexts( &self, project: &str, ) -> Result<Vec<WorkingContextSession>, MemoryError>

Every session still resumable under project’s working-context index (V2a-1 quick win), most-recently-saved first. Empty when the project never saved anything — that, and only that, is the empty case.

Cost: one O(1) index read plus ONE batched metadata lookup of the listed ids — never a store scan, but no longer a single read either. The lookup is what drops sessions whose fact was forgotten since; unlike the previous read-path prune it persists nothing, so a listing can be retried and a transient miss costs nothing durable.

Errors

Returns a storage error if the index fact cannot be read, or MemoryError::WorkingContextCodec if it does not parse or is corrupt (marked, but with no body).

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 with_autograph(self, extractor: DynExtractor) -> Self

Turn on autograph: every Self::remember additionally reads the stored fact for entities, entity→entity edges and entity attributes, and wires them — so the knowledge graph builds itself from ordinary remember calls, with no separate Self::remember_extracted.

Opt-in, and off unless this is called. It costs one generation per remember, which is a real latency and availability change: a memory write that silently depends on a local model being up is not a default anyone should inherit.

The caller’s fact is stored verbatim and first. Autograph only adds structure around it; it never rewrites or replaces what the caller asked to remember.

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

The stored metadata is auto-stamped with today’s date under crate::storage::AUTO_DATE_FIELD unless metadata already carries that key — see Self::remember_with_ttl (this method’s only caller) for the full contract.

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, crate::storage::AUTO_DATE_FIELD excepted), MemoryError::MetadataTooLarge if metadata exceeds crate::limits::MAX_METADATA_BYTES, 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.

The stored metadata is auto-stamped with today’s date under crate::storage::AUTO_DATE_FIELD (_veles_date, a YYYYMMDD integer read from the system clock at write time — see [crate::clock::today_ymd]) whenever metadata doesn’t already carry that key; an explicit value in metadata (e.g. to date a fact retroactively) is never overwritten. No clock is available on wasm32-unknown-unknown, so that target stamps nothing and metadata passes through unchanged. This is the ONE place in the crate that reads wall-clock time on the write path — the context compiler (compile_context and friends) stays clock-free and deterministic, unaffected by this stamp (it never re-derives a date from now(), only ever reads whatever a fact already carries).

Because Self::remember_extracted stores each extracted fact via Self::remember (which delegates here), it gets the same auto-stamp for free — entity hubs it also creates go through Self::store_fact directly and are never stamped, since they are internal graph scaffolding, not caller facts.

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, MemoryError::MetadataTooLarge if metadata exceeds crate::limits::MAX_METADATA_BYTES, or a storage error if persistence fails.

pub fn entity_profile( &self, name: &str, ) -> Result<Option<EntityProfile>, MemoryError>

Look up everything known about a named entity: the attributes merged onto its hub, and the typed edges leaving it.

This is the read side of the auto-built graph, and it exists because entity hubs are deliberately invisible to Self::recall and Self::recall_where — a hub ranking for its own topic would evict a real fact from the caller’s results. Without this accessor an attribute merged onto a hub would be stored correctly and yet be unreachable through every public read path: the worst kind of feature, one that looks done and silently returns nothing.

name is canonicalized exactly like an extracted entity (trimmed, lowercased), so the caller may pass "Axel Lange" and reach the node built from "axel lange". Returns None when no hub exists for the name — nothing has ever mentioned that entity.

Errors

Returns MemoryError if the store lookup 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<bool, MemoryError>

Forget (delete) the memory with fact_id. Returns whether a memory actually existed under that id — the underlying store’s delete is a silent no-op on an unknown id (matching most backends’ idempotent delete semantics), which is indistinguishable from a real deletion unless existence is checked first. Every surface that exposes forget (MCP, Node, WASM, Python) forwards this so a caller can tell “I removed something” from “that id was a typo”.

The delete always runs, even when get reports the id absent: get filters TTL-expired facts, and an expired-but-unpurged row must still be reclaimed (the caller is told false — the memory was already gone from its perspective). Existence check and delete are two store calls, not one atomic operation: two concurrent forgets of one id may both report true.

Errors

Returns MemoryError if the existence check or 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.