Struct EpisodicStore 

pub struct EpisodicStore { /* private fields */ }

Stores episodic (event-based) memories for agents, ordered by insertion time.

Guarantees

• Thread-safe via Arc<Mutex<_>>
• Ordered: recall returns items in descending importance order
• Bounded by optional per-agent capacity
• O(1) agent lookup via per-agent HashMap index
• Automatic expiry via optional max_age_hours

Implementations

impl EpisodicStore

pub fn new() -> Self

Create a new unbounded episodic store without decay.

pub fn builder() -> EpisodicStoreBuilder

Return a fluent builder to construct an EpisodicStore with any combination of options.

pub fn with_decay(policy: DecayPolicy) -> Self

Create a new episodic store with the given decay policy.

pub fn with_decay_and_recall_policy( decay: DecayPolicy, recall: RecallPolicy, ) -> Self

Create a new episodic store with both a decay policy and a recall policy.

pub fn with_recall_policy(policy: RecallPolicy) -> Self

Create a new episodic store with the given recall policy.

pub fn with_per_agent_capacity(capacity: usize) -> Self

Create a new episodic store with the given per-agent capacity limit.

When an agent exceeds this capacity, the lowest-importance item for that agent is evicted.

Soft-limit semantics

The capacity is a soft limit. During each add_episode call the new item is inserted first, and only then is the lowest-importance item evicted if the count exceeds capacity. This means the store momentarily holds capacity + 1 items per agent while eviction is in progress. The newly added item is never the one evicted regardless of its importance score.

Concurrent calls to add_episode may briefly exceed the cap by more than one item before each call performs its own eviction sweep.

pub fn with_max_age(max_age_hours: f64) -> Result<Self, AgentRuntimeError>

Create a new episodic store with an absolute age limit.

Items older than max_age_hours are automatically purged on the next recall or add_episode call for the owning agent.

Arguments

• max_age_hours — maximum memory age in hours; must be > 0

pub fn with_eviction_policy(policy: EvictionPolicy) -> Self

Create a new episodic store with the given eviction policy.

pub fn add_episode( &self, agent_id: AgentId, content: impl Into<String> + Debug, importance: f32, ) -> Result<MemoryId, AgentRuntimeError>

Record a new episode for the given agent.

Returns

The MemoryId of the newly created memory item.

Errors

Returns Err(AgentRuntimeError::Memory) only if the internal mutex is poisoned (extremely unlikely in normal operation; see recover_lock).

Capacity enforcement

If the store was created with with_per_agent_capacity, the item is always inserted first. If the agent’s item count then exceeds the cap, the single lowest-importance item for that agent is evicted. See with_per_agent_capacity for the full soft-limit semantics.

pub fn add_episode_at( &self, agent_id: AgentId, content: impl Into<String> + Debug, importance: f32, timestamp: DateTime<Utc>, ) -> Result<MemoryId, AgentRuntimeError>

Add an episode with an explicit timestamp.

pub fn recall( &self, agent_id: &AgentId, limit: usize, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Recall up to limit memories for the given agent.

Applies decay if configured, purges stale items if max_age is set, increments recall_count for each recalled item, then returns items sorted according to the configured RecallPolicy.

Errors

Returns Err(AgentRuntimeError::Memory) only if the internal mutex is poisoned (extremely unlikely in normal operation).

pub fn len(&self) -> Result<usize, AgentRuntimeError>

Return the total number of stored episodes across all agents.

pub fn is_empty(&self) -> Result<bool, AgentRuntimeError>

Return true if no episodes have been stored.

pub fn agent_memory_count( &self, agent_id: &AgentId, ) -> Result<usize, AgentRuntimeError>

Return the number of stored episodes for a specific agent.

Returns 0 if the agent has no episodes or has not been seen before.

pub fn list_agents(&self) -> Result<Vec<AgentId>, AgentRuntimeError>

Return all agent IDs that have at least one stored episode.

The order of agents in the returned vector is not guaranteed.

pub fn purge_agent_memories( &self, agent_id: &AgentId, ) -> Result<usize, AgentRuntimeError>

Remove all stored episodes for agent_id and return the number removed.

Returns 0 if the agent had no episodes. Does not affect other agents.

pub fn clear_agent_memory( &self, agent_id: &AgentId, ) -> Result<(), AgentRuntimeError>

Remove all memories for the given agent.

After this call, recall for this agent returns an empty list.

pub fn export_agent_memory( &self, agent_id: &AgentId, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Export all memories for the given agent as a serializable Vec.

Useful for migrating agent state across runtime instances.

pub fn import_agent_memory( &self, agent_id: &AgentId, items: Vec<MemoryItem>, ) -> Result<(), AgentRuntimeError>

Import a Vec of MemoryItems for the given agent, replacing any existing memories.

The agent’s existing memories are completely replaced by the imported items.

Trait Implementations

impl Clone for EpisodicStore

fn clone(&self) -> EpisodicStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EpisodicStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for EpisodicStore

fn default() -> Self

Returns the “default value” for a type.