Trait MemoryStore 

pub trait MemoryStore {
    // Required methods
    fn store(
        &self,
        id: u64,
        content: &str,
        embedding: &[f32],
    ) -> Result<(), MemoryError>;
    fn store_with_metadata(
        &self,
        id: u64,
        content: &str,
        embedding: &[f32],
        metadata: &Metadata,
    ) -> Result<(), MemoryError>;
    fn store_with_ttl(
        &self,
        id: u64,
        content: &str,
        embedding: &[f32],
        ttl_seconds: u64,
    ) -> Result<(), MemoryError>;
    fn update_metadata(
        &self,
        id: u64,
        metadata: &Metadata,
    ) -> Result<(), MemoryError>;
    fn get(&self, id: u64) -> Result<Option<(String, Vec<f32>)>, MemoryError>;
    fn get_metadata(&self, id: u64) -> Result<Option<Metadata>, MemoryError>;
    fn get_metadata_batch(
        &self,
        ids: &[u64],
    ) -> Result<Vec<Option<Metadata>>, MemoryError>;
    fn delete(&self, id: u64) -> Result<(), MemoryError>;
    fn query_filtered(
        &self,
        embedding: &[f32],
        k: usize,
        filter: &Metadata,
        offset: usize,
    ) -> Result<Vec<(u64, f32, String)>, MemoryError>;
    fn query_excluding(
        &self,
        embedding: &[f32],
        k: usize,
        exclude: &Metadata,
    ) -> Result<Vec<(u64, f32, String)>, MemoryError>;
    fn query_columnar(
        &self,
        embedding: &[f32],
        k: usize,
        filters: &[ColumnFilter],
    ) -> Result<Vec<Recollection>, MemoryError>;
    fn relate(
        &self,
        from: u64,
        to: u64,
        relation: &str,
    ) -> Result<u64, MemoryError>;
    fn relations(&self, id: u64) -> Result<Vec<MemoryEdge>, MemoryError>;
    fn count(&self) -> usize;

    // Provided method
    fn store_with_metadata_and_ttl(
        &self,
        id: u64,
        content: &str,
        embedding: &[f32],
        metadata: &Metadata,
        ttl_seconds: u64,
    ) -> Result<(), MemoryError> { ... }
}

The storage primitives crate::service::MemoryService needs: write, vector search, graph edges, and by-id lookup. A backend that implements this trait can run the full wedge (remember/recall/recall_fused/ relate/forget/why/remember_extracted) with no orchestration code duplicated.

Required Methods

fn store( &self, id: u64, content: &str, embedding: &[f32], ) -> Result<(), MemoryError>

Store a fact with no metadata or expiry.

Errors

Returns MemoryError if persistence fails.

fn store_with_metadata( &self, id: u64, content: &str, embedding: &[f32], metadata: &Metadata, ) -> Result<(), MemoryError>

Store a fact tagged with metadata, no expiry.

Errors

Returns MemoryError if persistence fails.

fn store_with_ttl( &self, id: u64, content: &str, embedding: &[f32], ttl_seconds: u64, ) -> Result<(), MemoryError>

Store a fact that expires after ttl_seconds, no metadata.

Errors

Returns MemoryError if persistence fails.

fn update_metadata( &self, id: u64, metadata: &Metadata, ) -> Result<(), MemoryError>

Merge metadata into an already-stored fact’s payload, preserving any durable TTL. Used to combine metadata with an expiry (store both in two calls rather than needing every metadata×TTL combination as a separate primitive).

Errors

Returns MemoryError if id is unknown or persistence fails.

fn get(&self, id: u64) -> Result<Option<(String, Vec<f32>)>, MemoryError>

A fact’s content and embedding, or None if unknown/expired.

Errors

Returns MemoryError if storage access fails.

fn get_metadata(&self, id: u64) -> Result<Option<Metadata>, MemoryError>

A fact’s raw stored payload — reserved system keys (_veles_*) included, so the service layer can check the hub flag before stripping them for the caller — or None when the fact is unknown/expired.

Errors

Returns MemoryError if storage access fails.

fn get_metadata_batch( &self, ids: &[u64], ) -> Result<Vec<Option<Metadata>>, MemoryError>

Batched Self::get_metadata: one storage round trip for every id in ids, results in the same order and length (an unknown or expired id maps to None). Same raw-payload semantics as the single-id form.

Errors

Returns MemoryError if storage access fails.

fn delete(&self, id: u64) -> Result<(), MemoryError>

Delete a fact.

Errors

Returns MemoryError if deletion fails.

fn query_filtered( &self, embedding: &[f32], k: usize, filter: &Metadata, offset: usize, ) -> Result<Vec<(u64, f32, String)>, MemoryError>

Vector search for up to k ids, narrowed to facts whose metadata exactly matches every key in filter.

Errors

Returns MemoryError if the query fails.

fn query_excluding( &self, embedding: &[f32], k: usize, exclude: &Metadata, ) -> Result<Vec<(u64, f32, String)>, MemoryError>

Vector search for up to k ids, dropping facts whose metadata matches every key in exclude.

Errors

Returns MemoryError if the query fails.

fn query_columnar( &self, embedding: &[f32], k: usize, filters: &[ColumnFilter], ) -> Result<Vec<Recollection>, MemoryError>

Vector search fused with structured ColumnStore predicates (ranges and comparisons, not just equality) — the engine behind crate::service::MemoryService::recall_where.

Errors

Returns MemoryError::InvalidFilter if a filter field is not a plain identifier or a filter value is non-scalar, or MemoryError if the query fails.

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

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

Errors

Returns MemoryError if either endpoint is missing or persistence fails.

fn relations(&self, id: u64) -> Result<Vec<MemoryEdge>, MemoryError>

The outgoing edges of id.

Errors

Returns MemoryError if storage access fails.

fn count(&self) -> usize

The total number of live (non-expired) tracked facts, including internal entity hubs — used as a corpus-size proxy for idf weighting.

Provided Methods

fn store_with_metadata_and_ttl( &self, id: u64, content: &str, embedding: &[f32], metadata: &Metadata, ttl_seconds: u64, ) -> Result<(), MemoryError>

Store a fact with BOTH metadata and a durable TTL, in ONE write.

Default: the historical two-call sequence, so a backend written before this method keeps compiling and behaving as it did. Backends that can write both at once should override it — the two-call form leaves the fact live and expiring between the calls, so a short TTL can lapse in the gap and the metadata write then fails on a fact that was perfectly valid when the caller asked for it.

Errors

Returns MemoryError if persistence fails.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl MemoryStore for NativeStore

Available on crate feature persistence only.