Struct WorkingMemory 

pub struct WorkingMemory { /* private fields */ }

A bounded, key-value working memory for transient agent state.

When capacity is exceeded, the oldest entry (by insertion order) is evicted.

Guarantees

• Thread-safe via Arc<Mutex<_>>
• Bounded: never exceeds capacity entries
• Deterministic eviction: LRU (oldest insertion first)

Implementations

impl WorkingMemory

pub fn new(capacity: usize) -> Result<Self, AgentRuntimeError>

Create a new WorkingMemory with the given capacity.

Returns

• Ok(WorkingMemory) — on success
• Err(AgentRuntimeError::Memory) — if capacity == 0

pub fn set( &self, key: impl Into<String> + Debug, value: impl Into<String> + Debug, ) -> Result<(), AgentRuntimeError>

Insert or update a key-value pair, evicting the oldest entry if over capacity.

pub fn get(&self, key: &str) -> Result<Option<String>, AgentRuntimeError>

Retrieve a value by key.

Returns

• Some(value) — if the key exists
• None — if not found

pub fn set_many( &self, pairs: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>, ) -> Result<(), AgentRuntimeError>

Insert multiple key-value pairs with a single lock acquisition.

Each entry follows the same eviction semantics as set: if the key already exists it is updated in-place; if inserting a new key would exceed capacity, the oldest key is evicted first.

pub fn set_if_absent( &self, key: impl Into<String> + Debug, value: impl Into<String> + Debug, ) -> Result<bool, AgentRuntimeError>

Update the value of an existing key without inserting if absent.

Insert key → value only if key is not already present.

Returns Ok(true) if the entry was inserted, Ok(false) if the key was already present (the existing value is left unchanged). Capacity limits and LRU eviction apply as with set.

pub fn update_if_exists( &self, key: &str, value: impl Into<String>, ) -> Result<bool, AgentRuntimeError>

Returns Ok(true) if the key existed and was updated, Ok(false) if not present.

pub fn update_many( &self, pairs: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>, ) -> Result<usize, AgentRuntimeError>

Update multiple existing keys in a single lock acquisition.

Each (key, value) pair is applied only if the key is already present (same semantics as update_if_exists). Returns the number of keys that were found and updated.

pub fn keys_starting_with( &self, prefix: &str, ) -> Result<Vec<String>, AgentRuntimeError>

Return all keys whose names start with prefix, in insertion order.

Useful for namespace-prefixed keys such as "user:name", "user:email" where all user-related keys share the "user:" prefix.

pub fn values_matching( &self, pattern: &str, ) -> Result<Vec<(String, String)>, AgentRuntimeError>

Return all (key, value) pairs whose value contains pattern as a substring. Comparison is case-sensitive.

Useful for scanning working memory for values that match a keyword without iterating the full map externally.

pub fn value_length( &self, key: &str, ) -> Result<Option<usize>, AgentRuntimeError>

Return the byte length of the value stored at key, or None if the key is not present.

Useful for estimating memory usage without cloning the value string.

pub fn contains_all<'a>( &self, keys: impl IntoIterator<Item = &'a str>, ) -> Result<bool, AgentRuntimeError>

Rename a key without changing its value or insertion order.

Return true if all of the given keys are currently stored.

An empty iterator returns true vacuously.

pub fn has_any_key<'a>( &self, keys: impl IntoIterator<Item = &'a str>, ) -> Result<bool, AgentRuntimeError>

Return true if any of the given keys is currently stored.

An empty iterator returns false.

pub fn rename( &self, old_key: &str, new_key: impl Into<String>, ) -> Result<bool, AgentRuntimeError>

Returns true if old_key existed and was renamed. Returns false if old_key is not present. If new_key already exists it is overwritten and its old value is lost.

pub fn get_many( &self, keys: &[&str], ) -> Result<Vec<Option<String>>, AgentRuntimeError>

Retrieve multiple values in a single lock acquisition.

Returns a Vec of the same length as keys. Each entry is Some(value) if the key is present, None if not.

pub fn contains(&self, key: &str) -> Result<bool, AgentRuntimeError>

Return true if a value is stored under key.

pub fn get_or_default( &self, key: &str, default: impl Into<String>, ) -> Result<String, AgentRuntimeError>

Return the value associated with key, or default if not set.

pub fn remove(&self, key: &str) -> Result<bool, AgentRuntimeError>

Remove a single entry by key. Returns true if the key existed.

pub fn keys(&self) -> Result<Vec<String>, AgentRuntimeError>

Return all keys in insertion order.

pub fn values(&self) -> Result<Vec<String>, AgentRuntimeError>

Return all values in insertion order (parallel to keys).

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

Remove all entries from working memory.

pub fn iter_sorted(&self) -> Result<Vec<(String, String)>, AgentRuntimeError>

Remove all entries and return them as a Vec<(key, value)> in insertion order.

Return all entries as (key, value) pairs sorted alphabetically by key.

Unlike iter/entries which return entries in insertion order, this always returns a deterministically ordered snapshot.

pub fn drain(&self) -> Result<Vec<(String, String)>, AgentRuntimeError>

After this call the memory is empty. Useful for atomically moving the contents to another data structure.

pub fn snapshot(&self) -> Result<HashMap<String, String>, AgentRuntimeError>

Clone all current entries into a HashMap<String, String>.

Unlike drain, this leaves the working memory unchanged.

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

Return the current number of entries.

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

Return true if no entries are stored.

pub fn iter(&self) -> Result<Vec<(String, String)>, AgentRuntimeError>

Iterate over all key-value pairs in insertion order.

Equivalent to entries; provided as a more idiomatic name for for-loop patterns.

pub fn entries(&self) -> Result<Vec<(String, String)>, AgentRuntimeError>

Return all key-value pairs in insertion order.

pub fn pop_oldest(&self) -> Result<Option<(String, String)>, AgentRuntimeError>

Remove and return the oldest entry (first inserted that is still present).

Returns None if the memory is empty.

pub fn peek_oldest(&self) -> Result<Option<(String, String)>, AgentRuntimeError>

Peek at the oldest entry without removing it.

Returns None if the memory is empty. Unlike pop_oldest this method does not modify the store.

pub fn capacity(&self) -> usize

Return the maximum number of entries this store can hold.

When len reaches this value, the oldest entry is evicted on the next set call for a new key.

pub fn fill_ratio(&self) -> Result<f64, AgentRuntimeError>

Return the current fill ratio as len / capacity.

Returns a value in [0.0, 1.0]. 1.0 means the memory is full and the next insert will evict the oldest entry.

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

Return true when the number of stored entries equals the configured capacity.

When true, the next set call for a new key will evict the oldest entry.

pub fn remove_keys_starting_with( &self, prefix: &str, ) -> Result<usize, AgentRuntimeError>

Remove all entries whose key begins with prefix.

Returns the number of entries removed. Removal preserves insertion order for the surviving entries.

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

Return the total number of bytes used by all stored values.

Useful for estimating memory pressure without allocating a full snapshot.

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

Return the byte length of the longest key currently stored.

Returns 0 when the memory is empty.

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

Return the byte length of the longest stored value.

Returns 0 when the memory is empty.

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

Return the byte length of the shortest stored value.

Returns 0 when the memory is empty.

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

Return the number of keys whose text contains substring.

The search is case-sensitive. Returns 0 when the store is empty or no key matches.

pub fn avg_value_length(&self) -> Result<f64, AgentRuntimeError>

Return the mean byte length of all stored values.

Returns 0.0 when the store is empty.

pub fn count_above_value_length( &self, min_bytes: usize, ) -> Result<usize, AgentRuntimeError>

Return the number of entries whose value exceeds min_bytes bytes in length.

pub fn longest_key(&self) -> Result<Option<String>, AgentRuntimeError>

Return the key with the most bytes, or None if the store is empty.

When multiple keys share the maximum byte length, one of them is returned (unspecified which).

pub fn longest_value(&self) -> Result<Option<String>, AgentRuntimeError>

Return the value with the most bytes, or None if the store is empty.

When multiple values share the maximum byte length, one of them is returned (unspecified which).

pub fn pairs_starting_with( &self, prefix: &str, ) -> Result<Vec<(String, String)>, AgentRuntimeError>

Return all (key, value) pairs whose key starts with prefix.

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

Return the sum of byte lengths of all stored keys.

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

Return the shortest key length, or 0 if the store is empty.

pub fn count_matching_prefix( &self, prefix: &str, ) -> Result<usize, AgentRuntimeError>

Return the number of keys that start with the given prefix.

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

Return a list of (key, value_byte_length) pairs for all entries. Return the number of key-value entries currently stored.

pub fn value_lengths(&self) -> Result<Vec<(String, usize)>, AgentRuntimeError>

Return a list of (key, value_byte_length) pairs for all entries.

pub fn keys_with_value_longer_than( &self, threshold: usize, ) -> Result<Vec<String>, AgentRuntimeError>

Return the keys of all entries whose value byte length is strictly greater than threshold.

pub fn longest_value_key(&self) -> Result<Option<String>, AgentRuntimeError>

Return the key whose associated value has the most bytes, or None if empty.

pub fn retain<F>(&self, predicate: F) -> Result<usize, AgentRuntimeError>

where F: FnMut(&str, &str) -> bool,

Remove all entries for which predicate(key, value) returns false.

Preserves insertion order of the surviving entries. Returns the number of entries removed.

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

Copy all entries from other into self.

Entries from other are inserted in its insertion order. Capacity limits and eviction apply as if each entry were inserted individually via set.

pub fn entry_count_satisfying<F>( &self, predicate: F, ) -> Result<usize, AgentRuntimeError>

where F: FnMut(&str, &str) -> bool,

Return the number of entries for which predicate(key, value) returns true.

pub fn get_all_keys(&self) -> Result<Vec<String>, AgentRuntimeError>

Return all keys in insertion order.

pub fn replace_all( &self, map: HashMap<String, String>, ) -> Result<(), AgentRuntimeError>

Atomically replace all entries with map.

The new entries are stored in iteration order of map. Capacity limits apply: if map.len() > capacity, only the last capacity entries (in iteration order) are retained.

Trait Implementations

impl Clone for WorkingMemory

fn clone(&self) -> WorkingMemory

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for WorkingMemory

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

Formats the value using the given formatter.