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.

Warning

When recall is RecallPolicy::Hybrid, decay is applied before scoring, producing a double time penalty. See RecallPolicy docs for details. Consider using the builder to configure only one of these time-based mechanisms.

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 try_with_per_agent_capacity( capacity: usize, ) -> Result<Self, AgentRuntimeError>

Create a new episodic store with a per-agent capacity limit, without panicking.

Returns Err if capacity == 0. Prefer this over with_per_agent_capacity in user-facing code where a zero capacity should be a recoverable error rather than a panic.

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_with_tags( &self, agent_id: AgentId, content: impl Into<String> + Debug, importance: f32, tags: Vec<String>, ) -> Result<MemoryId, AgentRuntimeError>

Add an episode with associated tags.

Convenience wrapper around add_episode that accepts a tag list in the same call. Episode capacity eviction follows the same rules as add_episode.

pub fn remove_by_id( &self, agent_id: &AgentId, id: &MemoryId, ) -> Result<bool, AgentRuntimeError>

Remove a specific episode by its MemoryId.

Returns Ok(true) if the episode was found and removed, Ok(false) if no episode with that id exists for agent_id.

pub fn update_tags_by_id( &self, agent_id: &AgentId, id: &MemoryId, new_tags: Vec<String>, ) -> Result<bool, AgentRuntimeError>

Update the tags of an episode identified by its MemoryId.

Returns Ok(true) if found and updated, Ok(false) otherwise.

pub fn max_importance_for( &self, agent_id: &AgentId, ) -> Result<Option<f32>, AgentRuntimeError>

Return the highest importance score across all episodes for agent_id.

Returns None if the agent has no stored episodes.

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

Return the number of episodes stored for agent_id.

Cheaper than recall(agent, usize::MAX)?.len() because it does not sort, clone, or increment recall counts.

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

Return true if the store contains at least one episode for agent_id.

Cheaper than count_for(agent_id)? > 0 because no heap allocation occurs.

pub fn agents_with_min_episodes( &self, min: usize, ) -> Result<Vec<AgentId>, AgentRuntimeError>

Return the IDs of agents that have at least min episodes.

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

Return the total number of episodes stored across all agents.

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

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

The returned Vec is sorted for deterministic output.

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

Return the average importance score of all episodes for agent_id.

Returns 0.0 when the agent has no episodes or is unknown.

pub fn agent_episode_counts( &self, ) -> Result<HashMap<AgentId, usize>, AgentRuntimeError>

Return a map from each agent ID to their episode count.

Returns an empty map for an empty store.

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

Return all episodes for agent_id sorted by importance descending (most important first).

Returns an empty Vec for an unknown agent.

pub fn episodes_after_timestamp( &self, agent_id: &AgentId, after: DateTime<Utc>, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Return all episodes for agent_id whose timestamp is strictly after after.

Returns an empty Vec for an unknown agent or when no episode qualifies.

pub fn agent_with_min_importance_avg( &self, ) -> Result<Option<AgentId>, AgentRuntimeError>

Return the agent ID with the lowest average episode importance, or None for an empty store.

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

Return all episodes for agent_id whose content contains substr.

Returns an empty Vec for an unknown agent or when no episode matches.

pub fn top_agent_by_importance( &self, ) -> Result<Option<AgentId>, AgentRuntimeError>

Return the agent ID whose episodes have the highest total importance score, or None if the store is empty.

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

Return the episode with the highest importance score for agent_id, or None when the agent has no episodes.

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

Return the average number of whitespace-delimited words per episode content string for agent_id.

Returns 0.0 when the agent has no episodes.

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

Return true if two or more episodes for agent_id share identical content strings.

Returns false for an unknown agent or one with fewer than 2 episodes.

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

Return the number of episodes stored for the given agent.

Returns 0 if the agent has no recorded episodes.

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

Return all episodes for agent_id whose importance is strictly above min_importance, cloned into a new Vec.

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

Return the sum of importance values for all episodes belonging to agent_id.

Returns 0.0 when the agent has no recorded episodes.

pub fn episodes_in_range( &self, agent_id: &AgentId, min_importance: f32, max_importance: f32, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Return all episodes for agent_id whose importance is in the closed interval [min_importance, max_importance].

pub fn agent_importance_range( &self, agent_id: &AgentId, ) -> Result<Option<(f32, f32)>, AgentRuntimeError>

Return (min_importance, max_importance) for all episodes of agent_id, or None if the agent has no recorded episodes.

pub fn episodes_min_importance( &self, agent_id: &AgentId, ) -> Result<Option<f32>, AgentRuntimeError>

Return the minimum importance across all episodes for agent_id, or None when the agent has no recorded episodes.

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

Return the minimum word count among all episode content strings for agent_id.

Returns 0 when the agent has no recorded episodes.

pub fn agent_with_most_episodes( &self, ) -> Result<Option<AgentId>, AgentRuntimeError>

Return the AgentId of the agent with the most stored episodes, or None if the store is empty.

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

Return the maximum word count among all episode content strings for agent_id.

Returns 0 when the agent has no recorded episodes.

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

Return the total number of episodes stored across all agents.

pub fn all_episodes(&self) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Return a cloned Vec of all MemoryItems across all agents, in an unspecified order.

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

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

pub fn min_episode_count( &self, ) -> Result<Option<(AgentId, usize)>, AgentRuntimeError>

Return the agent with the fewest (non-zero) stored episodes, or None if the store is empty.

pub fn max_importance_overall(&self) -> Result<Option<f32>, AgentRuntimeError>

Return the highest importance value across all stored episodes, or None if the store is empty.

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

Return the variance of importance scores for the given agent’s episodes.

Returns 0.0 when the agent has fewer than two episodes.

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

Return up to n episodes for agent_id sorted by descending importance without incrementing recall counts or applying decay.

Use this for read-only importance-ranked snapshots.

pub fn filter_by_importance( &self, agent_id: &AgentId, min: f32, max: f32, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Return all episodes for agent_id whose importance is within [min_inclusive, max_inclusive], sorted by descending importance.

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

Keep only the n most-important episodes for agent_id, removing the rest. Returns the number of episodes that were removed.

If the agent has n or fewer episodes already, nothing is removed.

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

Return the most recently stored episode for agent_id, or None if the agent has no episodes.

“Most recent” is defined as the last element in the stored list, which matches insertion order.

pub fn max_importance( &self, agent_id: &AgentId, ) -> Result<Option<f32>, AgentRuntimeError>

Return the highest importance score for agent_id, or None if the agent has no episodes.

pub fn min_importance( &self, agent_id: &AgentId, ) -> Result<Option<f32>, AgentRuntimeError>

Return the lowest importance score for agent_id, or None if the agent has no episodes.

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

Count episodes for agent_id whose importance is strictly greater than threshold.

Returns 0 if the agent has no episodes.

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

Return the episode with the highest recall_count for agent_id.

Returns None if the agent has no stored episodes. When multiple episodes tie for the maximum recall count, any one of them may be returned.

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

Return the arithmetic mean importance for agent_id, or 0.0 if the agent has no stored episodes.

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

Remove duplicate episodes (same content) for agent_id, keeping only the episode with the highest importance for each distinct content string.

Returns the number of episodes removed.

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

Return all AgentIds that have at least one stored episode.

pub fn agents_with_episodes_above_count( &self, min_count: usize, ) -> Result<Vec<AgentId>, AgentRuntimeError>

Return agent IDs that have more than min_count episodes stored.

Useful for identifying high-activity agents in a shared store.

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

Return all episodes for agent_id whose content contains pattern (case-sensitive substring match), sorted by descending importance.

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

Remove all episodes stored for agent_id.

Returns the number of episodes that were removed.

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

Return the number of episodes for agent_id that carry the given tag.

pub fn episodes_with_content( &self, agent_id: &AgentId, substring: &str, ) -> Result<Vec<String>, AgentRuntimeError>

Return the content strings of all episodes for agent_id whose content contains substring.

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

Return the byte length of the longest episode content for agent_id.

Returns 0 if the agent has no episodes.

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

Return the byte length of the shortest episode content for agent_id.

Returns 0 if the agent has no episodes.

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

Return the content strings of all episodes for agent_id, sorted by descending importance (most important first).

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

Return the count of episodes for agent_id whose content contains substring.

The match is case-sensitive. Returns 0 if the agent has no episodes.

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

Return a sorted list of all AgentIds that have at least one episode.

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

Return the total number of episodes stored across all agents.

Equivalent to summing episode_count_for over every agent, but in a single lock acquisition.

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

Return the count of episodes whose importance is strictly greater than threshold.

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

Return a list of content byte lengths for all episodes belonging to agent_id, in storage order.

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

Return the total byte length of all episode content strings for agent_id.

Returns 0 if the agent has no stored episodes.

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

Return the average byte length of episode content strings for agent_id.

Returns 0.0 if the agent has no stored episodes.

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

Return the sum of all importance scores for agent_id.

Returns 0.0 if the agent has no stored episodes.

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

Recall up to limit episodes for agent_id that carry tag, sorted by descending importance. limit = 0 returns all matches.

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 add_episodes_batch( &self, agent_id: AgentId, episodes: impl IntoIterator<Item = (impl Into<String>, f32)>, ) -> Result<Vec<MemoryId>, AgentRuntimeError>

Add multiple episodes for the same agent in a single lock acquisition.

More efficient than calling add_episode in a loop when inserting many items at once. Returns the generated MemoryIds in the same order as episodes.

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 recall_tagged( &self, agent_id: &AgentId, tags: &[&str], limit: usize, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Recall episodes for agent_id that contain all of the specified tags.

Returns at most limit items ordered by descending importance, consistent with recall. Pass an empty tags slice to match all episodes.

pub fn recall_by_id( &self, agent_id: &AgentId, id: &MemoryId, ) -> Result<Option<MemoryItem>, AgentRuntimeError>

Retrieve a single episode by its MemoryId.

Returns Ok(Some(item)) if found, Ok(None) if no episode with that ID exists for agent_id.

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

Import all episodes from other for agent_id into this store.

Episodes are appended without deduplication. Capacity eviction is applied per-episode exactly as in add_episode.

pub fn update_importance( &self, agent_id: &AgentId, id: &MemoryId, new_importance: f32, ) -> Result<bool, AgentRuntimeError>

Update the importance score of a specific episode in-place.

Returns Ok(true) if the episode was found and updated, Ok(false) if no episode with that id exists for agent_id.

new_importance is clamped to [0.0, 1.0].

pub fn recall_since( &self, agent_id: &AgentId, cutoff: DateTime<Utc>, limit: usize, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Recall episodes for agent_id inserted at or after cutoff.

Returns items ordered by descending importance (same as recall). Pass limit = 0 to return all matching items.

pub fn update_content( &self, agent_id: &AgentId, id: &MemoryId, new_content: impl Into<String>, ) -> Result<bool, AgentRuntimeError>

Update the content of an episode identified by its MemoryId.

Returns Ok(true) if found and updated, Ok(false) if no episode with that id exists for agent_id.

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

Recall the most recently added episodes for agent_id in reverse insertion order.

Unlike recall (which ranks by importance), this returns the limit most recently inserted items with no re-ordering. Useful when recency matters more than importance, e.g. retrieving the latest context window entries.

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

Retrieve all stored episodes for agent_id without any limit.

Returns items in descending importance order, consistent with recall. For large stores, prefer recall with an explicit limit.

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

Return the top n episodes for agent_id ordered by descending importance.

When n == 0 all episodes are returned. Does not increment recall_count.

pub fn search_by_importance_range( &self, agent_id: &AgentId, min: f32, max: f32, limit: usize, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Return episodes for agent_id whose importance is in [min, max], most important first. Passing limit == 0 returns all matching episodes.

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

Return the sum of recall_count across all episodes for agent_id.

Useful for tracking aggregate access frequency per agent.

pub fn recall_count_for( &self, agent_id: &AgentId, id: &MemoryId, ) -> Result<Option<u64>, AgentRuntimeError>

Return the recall_count of the episode identified by id for agent_id.

Returns None if no episode with that id exists for the agent.

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

Return summary statistics (count, min, max, mean importance) for agent_id.

Returns (0, 0.0, 0.0, 0.0) if the agent has no stored episodes.

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

Return the oldest (first-inserted) episode for agent_id, or None if the agent has no stored episodes.

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

Remove all stored episodes for agent_id.

Returns the number of episodes that were removed.

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

Return the episode with the earliest timestamp for agent_id, or None if the agent has no stored episodes.

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

Return the most recently stored episode for agent_id by timestamp, or None if the agent has no episodes.

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

Return the n most recently stored episodes for agent_id, sorted by timestamp descending (newest first).

Returns fewer than n items when the agent has fewer stored episodes. Returns an empty Vec for an unknown agent.

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

Return the most recently stored episode for agent_id (largest timestamp), or None if the agent has no stored episodes.

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

Return the episode with the highest recall_count for agent_id, or None if the agent has no stored episodes. Ties are broken in favour of the episode with the higher importance score.

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

Return the episode with the highest importance score for agent_id, or None if the agent has no stored episodes. Ties are broken in favour of the later-inserted episode.

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

Return the episode with the lowest importance score for agent_id, or None if the agent has no stored episodes. Ties are broken in favour of the later-inserted episode.

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

Return all episodes for agent_id sorted by importance descending (highest first).

Returns an empty Vec for an unknown agent.

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

Return the most recently inserted episode for agent_id, or None if the agent has no stored episodes.

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_count(&self) -> Result<usize, AgentRuntimeError>

Return the number of distinct agents that have at least one stored episode.

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 has_episodes( &self, agent_id: &AgentId, ) -> Result<bool, AgentRuntimeError>

Return true if agent_id has at least one stored episode.

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

Return the most recently inserted episode for agent_id, or None if the agent has no stored episodes.

“Most recent” is determined by timestamp.

pub fn max_recall_count_for( &self, agent_id: &AgentId, ) -> Result<Option<u64>, AgentRuntimeError>

Return the maximum single recall_count value across all episodes for agent_id, or None if the agent has no stored episodes.

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

Return the mean importance score across all episodes for agent_id.

Returns 0.0 when the agent has no stored episodes.

pub fn importance_range( &self, agent_id: &AgentId, ) -> Result<Option<(f32, f32)>, AgentRuntimeError>

Return the (min, max) importance pair across all episodes for agent_id, or None when the agent has no stored episodes.

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

Return the total recall_count across all episodes for agent_id.

Returns 0 if the agent has no stored episodes.

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 clear_all(&self) -> Result<(), AgentRuntimeError>

Remove all episodes for all agents.

After this call len() returns 0 and list_agents() returns an empty slice.

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.

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

Search episodes for a given agent_id whose content contains query as a substring.

The comparison is case-sensitive. Returns at most limit matching items, ordered by descending importance (same as recall).

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

Return the count of episodes for agent_id whose importance is strictly above threshold.

Returns 0 for unknown agents or when no episodes exceed the threshold.

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

Return the mean importance score of all episodes for agent_id.

Returns 0.0 for unknown agents or agents with no episodes.

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

Return the total byte count of all episode content strings for agent_id.

Returns 0 for unknown agents.

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

Return the total number of whitespace-separated words across all episode content strings for agent_id.

Returns 0 for unknown agents or agents with no episodes.

pub fn min_episode_importance( &self, agent_id: &AgentId, ) -> Result<Option<f32>, AgentRuntimeError>

Return the minimum importance score across all episodes for agent_id.

Returns None when the agent has no episodes. Complements avg_episode_importance.

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

Return the count of episodes for agent_id whose importance is strictly greater than threshold.

Returns 0 for unknown agents.

pub fn tag_union( &self, agent_id: &AgentId, ) -> Result<HashSet<String>, AgentRuntimeError>

Return the union of all tags across all episodes for agent_id.

Returns an empty set for unknown agents or when all episodes have no tags.

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

Return the most recently stored episode for agent_id.

Uses MemoryItem::timestamp to determine recency. Returns None for unknown agents.

pub fn episodes_by_importance_range( &self, agent_id: &AgentId, lo: f32, hi: f32, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Return all episodes for agent_id whose importance is in [lo, hi] (inclusive), sorted by importance ascending.

Returns an empty Vec for unknown agents.

pub fn count_episodes_in_window( &self, agent_id: &AgentId, start: DateTime<Utc>, end: DateTime<Utc>, ) -> Result<usize, AgentRuntimeError>

Return the number of episodes for agent_id whose timestamp falls within [start, end] (inclusive on both ends).

Returns 0 for unknown agents or when no episode falls in the window.

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

Return the total number of tags across all episodes for agent_id.

Episodes with no tags contribute 0 to the sum. Returns 0 for unknown agents.

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

Return the average number of tags per episode for agent_id.

Returns 0.0 for unknown agents or when there are no episodes.

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

Return all episodes for agent_id whose importance is strictly below threshold, sorted by importance ascending (least important first).

Returns an empty Vec for unknown agents or when all episodes meet the threshold.

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

Return all episodes for agent_id sorted by timestamp ascending (oldest first).

Returns an empty Vec for unknown agents.

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

Return a sorted, deduplicated list of all tags used by any episode belonging to agent_id.

Returns an empty Vec for unknown agents.

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

Return all episodes for agent_id that contain tag in their tag list.

Returns an empty Vec for unknown agents or when no episode has the tag.

pub fn episode_count_before( &self, agent_id: &AgentId, before: DateTime<Utc>, ) -> Result<usize, AgentRuntimeError>

Return the count of episodes for agent_id whose timestamp is strictly before before.

Returns 0 for unknown agents or when no episode qualifies.

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

Return the IDs of all episodes stored for agent_id.

The order of the returned IDs is unspecified. Returns an empty Vec for unknown agents.

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

Return all episodes for agent_id whose importance score is strictly greater than threshold.

Returns an empty Vec for unknown agents or when no episode qualifies.

pub fn episodes_between( &self, agent_id: &AgentId, from: DateTime<Utc>, to: DateTime<Utc>, ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Return all episodes for agent_id whose timestamp falls in the range [from, to) (inclusive start, exclusive end).

Returns an empty Vec for unknown agents or when no episode qualifies.

pub fn episodes_tagged_with_all( &self, agent_id: &AgentId, tags: &[&str], ) -> Result<Vec<MemoryItem>, AgentRuntimeError>

Return all episodes for agent_id that carry every tag in tags.

Returns an empty Vec when tags is empty, the agent is unknown, or no episode satisfies all of the given tags.

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

Return the total whitespace-delimited word count across all episodes for agent_id.

Returns 0 for unknown agents or agents with no episodes.

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

Return the sum of importance scores for all episodes belonging to agent_id.

Returns 0.0 for unknown agents or agents with no episodes.

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

Return a Vec of content byte lengths for all episodes of agent_id.

The order matches the internal storage order (insertion order). Returns an empty Vec for unknown agents.

pub fn episode_count_by_agent( &self, ) -> Result<HashMap<AgentId, usize>, AgentRuntimeError>

Return the number of distinct agents that have at least one episode.

Provides a quick count of how many agents have recorded any episodic memory. Returns 0 for an empty store.

pub fn all_episode_ids(&self) -> Result<Vec<MemoryId>, AgentRuntimeError>

Return all episode IDs across every agent in the store.

The returned Vec is unsorted. Returns an empty Vec for an empty store.

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

Return all episodes for agent_id whose content byte length exceeds min_bytes.

Returns an empty Vec when the agent has no episodes or none exceed the threshold.

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

Return all agent IDs sorted by episode count in descending order.

Agents with more episodes appear first. When two agents have the same count the tie is broken alphabetically by agent ID.

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

Return the number of distinct agents that have at least one episode.

Returns 0 for an empty store.

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

Return the number of episodes for agent_id that have at least one tag.

Returns 0 for an unknown agent or an empty store.

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

Return all episodes for agent_id whose content has at least min_words whitespace-delimited words.

Returns an empty Vec for unknown agents or when no episode qualifies.

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

Return the episode with the most tags for agent_id, or None when the agent has no episodes. Ties are broken by insertion order.

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

Return a map of tag → episode count for all episodes of agent_id.

Each entry reports how many episodes carry that particular tag. Returns an empty map for unknown agents or agents with no tagged episodes.

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

Return the episode with the highest importance score for agent_id.

When multiple episodes share the maximum importance score the first one encountered is returned. Returns None for unknown agents or an empty store.

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

Return the number of episodes for agent_id that carry tag.

Returns 0 for unknown agents or if no episode carries tag.

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

Return all episodes for agent_id whose importance is strictly below threshold.

Returns an empty Vec for unknown agents or when no episode qualifies.

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

Return true if at least one episode has been stored for agent_id.

This is a cheaper alternative to calling EpisodicStore::recall and checking whether the result is empty.

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

Return all episodes for agent_id whose content contains substr (case-sensitive substring match).

Returns an empty Vec for unknown agents or when no episode matches.

pub fn max_episode_importance( &self, agent_id: &AgentId, ) -> Result<Option<f32>, AgentRuntimeError>

Return the maximum importance score across all episodes for agent_id, or None when the agent has no recorded episodes.

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.