Struct EpisodicMemory 

pub struct EpisodicMemory { /* private fields */ }

Episodic memory for storing event timelines with temporal context.

Records events with timestamps, descriptions, and embeddings. Supports similarity-based retrieval and time-range queries.

Implementations

impl EpisodicMemory

pub fn dimension(&self) -> usize

Returns the embedding dimension for this collection.

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

Creates or opens the episodic memory collection.

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 record( &self, event_id: u64, description: &str, timestamp: i64, embedding: Option<&[f32]>, ) -> Result<(), AgentMemoryError>

Stores an event in episodic memory.

Errors

Returns an error when the embedding dimension is invalid, when the collection is unavailable, or when storage upsert fails.

pub fn record_with_ttl( &self, event_id: u64, description: &str, timestamp: i64, embedding: Option<&[f32]>, ttl_seconds: u64, ) -> Result<(), AgentMemoryError>

Stores an event and assigns a TTL for automatic expiration.

A ttl_seconds of 0 means “expire immediately”: rather than persisting a live point that lingers until the next auto_expire, the event is eagerly removed (and any pre-existing point for event_id deleted), harmonising the behaviour with SemanticMemory::store_with_ttl. The embedding is still dimension-validated so callers get the same error contract as a real record.

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::record.

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

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

Unlike AgentMemory::set_episodic_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 event immediately.

Errors

Returns NotFound when no event with event_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 events with a typed, durable graph edge (e.g. CAUSED, FOLLOWED); see SemanticMemory::relate for semantics.

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 an event.

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.

Errors

Returns CollectionError when the collection cannot be resolved.

pub fn recent( &self, limit: usize, since_timestamp: Option<i64>, ) -> Result<Vec<(u64, String, i64)>, AgentMemoryError>

Returns recent events, optionally filtered by a lower timestamp bound.

Errors

Returns an error when the collection is unavailable.

pub fn older_than( &self, timestamp: i64, limit: usize, ) -> Result<Vec<(u64, String, i64)>, AgentMemoryError>

Returns events older than timestamp.

Errors

Returns an error when the collection is unavailable.

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

Retrieves the k most similar episodic events to a query embedding.

Errors

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

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

Retrieves an event with its embedding payload.

Errors

Returns an error when the collection is unavailable.

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

Deletes an episodic event by id.

Errors

Returns an error when the collection is unavailable or delete fails.

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

Serializes episodic points in temporal-order id set.

Errors

Returns an error when the collection is unavailable or JSON encoding fails.

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

Replaces episodic storage with previously serialized points.

Errors

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