Struct MemoryService 

pub struct MemoryService<E: Embedder> { /* 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.

Implementations

impl<E: Embedder> MemoryService<E>

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

Open (or create) a 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.

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

Link targets are validated to exist before the fact is stored, so a bad link never leaves the fact half-written.

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, or a storage error if persistence fails.

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.

Errors

Returns MemoryError if the semantic query 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.