Struct SemanticMemory 

pub struct SemanticMemory { /* private fields */ }

Long-term semantic memory for storing knowledge facts with vector similarity search.

Each fact is stored as an embedding vector with associated text content. Supports TTL-based expiration and snapshot serialization.

Implementations

impl SemanticMemory

pub fn new_from_db( db: Arc<Database>, dimension: usize, ) -> Result<Self, AgentMemoryError>

Creates or opens semantic memory with an independent in-memory TTL.

Standalone limitation

The MemoryTtl allocated here is not shared with any snapshot mechanism. TTLs assigned at store time (Self::store_with_ttl) are durable: the expiry is persisted as a _veles_expires_at payload field and the in-memory map is rebuilt from payloads at construction, so they survive a restart. TTLs set only in the map (e.g. via AgentMemory::set_semantic_ttl) remain in-memory, and Self::serialize / Self::deserialize carry stored points but intentionally omit the TTL map (see Self::serialize for the full contract). For full TTL and snapshot support, create an AgentMemory instead — it owns the shared MemoryTtl, snapshot manager, and all three subsystems.

Errors

Returns an error when collection creation/opening fails or dimensions mismatch.

pub fn collection_name(&self) -> &str

Returns the name of the underlying VelesDB collection.

pub fn dimension(&self) -> usize

Returns the embedding dimension for this collection.

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

Stores a semantic memory point.

Errors

Returns an error when embedding dimension is invalid, collection access fails, or persistence fails.

pub fn store_with_metadata( &self, id: u64, content: &str, embedding: &[f32], metadata: &Map<String, Value>, ) -> Result<(), AgentMemoryError>

Stores a semantic memory point with additional metadata fields.

content always wins: if metadata contains a "content" key, it is overwritten by the content parameter. The reserved system key _veles_expires_at (durable TTL, see Self::store_with_ttl) is likewise stripped from metadata; a plain expires_at key is ordinary business metadata and is stored verbatim.

Errors

Returns the same errors as Self::store.

pub fn update_metadata( &self, id: u64, updates: &Map<String, Value>, ) -> Result<(), AgentMemoryError>

Updates payload fields of an existing fact without changing its embedding.

Only facts that are tracked and not expired are updated. Any key in updates is merged into the existing payload; content may be updated through this method, but the vector is left untouched. The reserved system key _veles_expires_at (durable TTL) is ignored in updates and preserved from the existing payload.

Errors

Returns AgentMemoryError::NotFound when the id is unknown or expired. Returns other errors when collection access or persistence fails.

pub fn store_unique( &self, preferred_id: u64, content: &str, embedding: &[f32], ) -> Result<u64, AgentMemoryError>

Stores a fact under preferred_id, or under a freshly allocated id when preferred_id is already taken, and returns the id actually used.

Self::store upserts, so reusing an id silently overwrites the existing fact. Consolidation (which reuses the episodic id as the semantic id) must never clobber an unrelated semantic fact, so it relies on this collision-avoiding path instead.

Errors

Returns the same errors as Self::store.

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

Stores a semantic memory point and assigns a TTL.

A ttl_seconds of 0 means “expire immediately”: rather than persisting a live point that then occupies an index slot until the next auto_expire, the point is eagerly removed (and any pre-existing point for id deleted). The embedding is still dimension-validated so callers get the same error contract as a real store.

The expiry is persisted as a reserved _veles_expires_at (epoch seconds) payload field, so the TTL survives a process restart: the in-memory map is rebuilt from payloads when the collection is reopened.

Errors

Returns the same errors as Self::store.

pub fn set_ttl_durable( &self, id: u64, ttl_seconds: u64, ) -> Result<(), AgentMemoryError>

Durably sets (or refreshes) the TTL of an existing fact.

Unlike AgentMemory::set_semantic_ttl (in-memory map only, lost on restart), this persists the expiry to the reserved _veles_expires_at payload field, so it survives a restart. A ttl_seconds of 0 expires the fact immediately.

Errors

Returns NotFound when no fact with id exists, or CollectionError when persistence fails.

pub fn relate( &self, from_id: u64, to_id: u64, rel_type: &str, properties: Option<&Map<String, Value>>, ) -> Result<u64, AgentMemoryError>

Relates two live facts with a typed, durable graph edge (MATCH (a)-[:REL_TYPE]->(b) becomes executable over this memory).

Returns the allocated edge id. Edges are WAL-persisted and cascade away when either endpoint memory is deleted.

Errors

Returns NotFound when either endpoint is missing or expired, or CollectionError when the edge write fails.

pub fn relations(&self, id: u64) -> Result<Vec<GraphEdge>, AgentMemoryError>

Returns the outgoing relations of a fact (edges it points from).

Errors

Returns CollectionError when the collection cannot be resolved.

pub fn unrelate(&self, edge_id: u64) -> Result<bool, AgentMemoryError>

Removes a relation edge created by Self::relate.

Returns true when the edge existed and was removed.

Errors

Returns CollectionError when the collection cannot be resolved.

pub fn query( &self, query_embedding: &[f32], k: usize, ) -> Result<Vec<(u64, f32, String)>, AgentMemoryError>

Queries semantic memory by vector similarity.

Errors

Returns an error when embedding dimension is invalid, collection access fails, or vector search fails.

pub fn query_filtered( &self, query_embedding: &[f32], k: usize, filter: &Map<String, Value>, offset: usize, ) -> Result<Vec<(u64, f32, String)>, AgentMemoryError>

Queries semantic memory with a payload filter and optional offset pagination.

Results are ranked by vector similarity, filtered against filter (all key-value pairs must match), TTL-expired points are excluded, and offset leading results are skipped before taking k.

The internal fetch budget is generous to survive both TTL eviction and filter miss-rates; when the collection has very few matching entries the returned slice may be shorter than k.

Errors

Returns an error when embedding dimension is invalid or collection access fails.

pub fn store_batch( &self, facts: &[(u64, &str, &[f32])], ) -> Result<(), AgentMemoryError>

Stores multiple semantic memory points in one batch.

Each tuple is (id, content, embedding). All embeddings are dimension-validated before any write occurs.

This is best-effort, not transactional: if upsert_points fails partway the already-persisted points are kept and stored_ids is left untouched (it is only updated after a fully successful upsert), matching the single-store behaviour.

Errors

Returns an error when any embedding dimension is invalid, collection access fails, or persistence fails.

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

Retrieves a fact’s content and embedding by id.

Returns None when the id is unknown or has expired.

Errors

Returns an error when collection access fails.

pub fn list_all(&self) -> Result<Vec<(u64, String)>, AgentMemoryError>

Lists all live (non-expired) tracked facts as (id, content) pairs.

Errors

Returns an error when collection access fails.

pub fn count(&self) -> usize

Returns the number of tracked facts.

pub fn is_empty(&self) -> bool

Returns true when no facts are tracked.

pub fn clear(&self) -> Result<(), AgentMemoryError>

Removes all facts and their tracking entries.

Errors

Returns an error when collection access or deletion fails.

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

Deletes a semantic memory point by id.

Errors

Returns an error when collection access or deletion fails.

pub fn serialize(&self) -> Result<Vec<u8>, AgentMemoryError>

Serializes semantic memory points for snapshot persistence.

TTL limitation

The returned bytes contain only the stored points (id, embedding, payload — including any durable _veles_expires_at field) and intentionally omit the TTL map. TTL is tracked in a single MemoryTtl map shared across the semantic, episodic, and procedural subsystems (see AgentMemory), so it cannot be partitioned per subsystem here. TTL is persisted and restored globally by AgentMemory::snapshot / restore_state. Calling Self::deserialize in isolation therefore restores facts but refreshes the in-memory expiry map only at the next construction (payload _veles_expires_at rebuild); use the snapshot manager for an immediate full round-trip including TTL.

Errors

Returns an error when collection access or JSON encoding fails.

pub fn deserialize(&self, data: &[u8]) -> Result<(), AgentMemoryError>

Replaces semantic memory state from snapshot bytes.

Errors

Returns an error when JSON decoding fails, collection access fails, or persistence operations fail.