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 key_value_pairs_sorted( &self, ) -> Result<Vec<(String, String)>, AgentRuntimeError>

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

Provides a stable, deterministic view of the store contents. Returns an empty Vec for an empty store.

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 entries_sorted_by_key_length( &self, ) -> Result<Vec<(String, String)>, AgentRuntimeError>

Return all key-value pairs sorted by key byte length ascending, then alphabetically for equal lengths.

Returns an empty Vec for an empty store.

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

Return the maximum byte length among all stored values.

Returns 0 for an empty store.

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

Return all keys whose string representation ends with suffix, sorted alphabetically.

Returns an empty Vec when no key qualifies.

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

Return the average byte length of all stored keys.

Returns 0.0 for an empty store.

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

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

Useful as a quick bound on the widest key that will be emitted.

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

Return the count of values whose byte length exceeds min_bytes.

Returns 0 for an empty store or when no value exceeds the threshold.

pub fn has_key_starting_with( &self, prefix: &str, ) -> Result<bool, AgentRuntimeError>

Return true if any key in the store starts with prefix.

Returns false for an empty store.

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

Return the number of keys whose names begin with prefix.

Returns 0 for an empty store or when no key matches.

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

Return the value with the greatest byte length in the store.

Returns None for an empty store. When multiple values share the maximum byte length, the lexicographically largest is returned.

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

Return all keys whose associated value has a byte length greater than min_bytes, sorted alphabetically.

Returns an empty Vec when no key qualifies.

pub fn has_key_with_prefix( &self, prefix: &str, ) -> Result<bool, AgentRuntimeError>

Return true if any key in the store starts with prefix.

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

Return the count of values that start with prefix.

Returns 0 for an empty store or when no value matches.

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

Return the sum of byte lengths of all values currently stored.

Returns 0 for an empty store.

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

Return all keys sorted alphabetically.

Returns an empty Vec for an empty store.

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

Return all values in the store, sorted alphabetically.

Useful for deterministic comparison in tests and diagnostics. Returns an empty Vec for an empty store.

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

Return the keys whose stored value begins with prefix.

Returns an empty Vec when no value matches.

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

Return the number of key-value pairs currently stored.

pub fn value_for_key_or_default<'a>( &self, key: &str, default: &'a str, ) -> Result<String, AgentRuntimeError>

Return the value for key, or default if the key is not present.

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

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

Returns an empty Vec for an empty store or when no key matches.

pub fn has_value_equal_to(&self, val: &str) -> Result<bool, AgentRuntimeError>

Return true if any stored value is exactly equal to val.

Returns false for an empty store.

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

Return true if the value stored under key contains substr.

Returns false when key is not present.

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

Return all keys that do NOT start with prefix, sorted alphabetically.

Returns an empty Vec for an empty store or when all keys match.

pub fn count_values_equal_to( &self, val: &str, ) -> Result<usize, AgentRuntimeError>

Return the number of stored values that are exactly equal to val.

pub fn count_keys_below_bytes( &self, max_bytes: usize, ) -> Result<usize, AgentRuntimeError>

Return the number of keys whose byte length is strictly less than max_bytes.

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

Return the number of Unicode scalar values (chars) in the value stored under key, or 0 if the key is not present.

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

Return all keys whose byte length is strictly greater than min_bytes.

Returns an empty Vec when no keys satisfy the condition.

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

Return all keys whose byte length is strictly less than max_bytes.

Returns an empty Vec when no keys satisfy the condition.

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

Return all stored values that start with prefix.

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

Return all values whose string representation ends with suffix.

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

Return true if the value stored under key starts with prefix.

Returns false when key is not present.

pub fn value_length_histogram( &self, bucket_size: usize, ) -> Result<Vec<(usize, usize)>, AgentRuntimeError>

Return a histogram of value byte lengths bucketed by bucket_size.

The returned Vec contains (bucket_start, count) pairs where bucket_start = (value_len / bucket_size) * bucket_size. Pairs are sorted by bucket_start in ascending order. Returns an empty Vec for an empty store or when bucket_size == 0.

pub fn semantic_key_count( &self, substr: &str, ) -> Result<usize, AgentRuntimeError>

Return the number of keys that contain substr as a substring.

Useful for quickly counting “semantic” keys that share a common token (e.g. "intent", "context", "goal"). Returns 0 for an empty store or when no key matches.

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

Return the byte length of the longest stored value, or 0 when empty.

Helpful for detecting unusually large values that might indicate a working-memory bloat. Returns 0 for an empty store.

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.

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

Return all values whose content contains substring (case-sensitive), in insertion order.

Returns an empty Vec when no values match or the store is empty.

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

Return all keys in ascending sorted (lexicographic) order.

Unlike get_all_keys which returns keys in insertion order, this method always returns them in a deterministic alphabetical order.

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

Return the value associated with the longest key, or None if the store is empty.

When multiple keys share the maximum byte length, the one that sorts first lexicographically is chosen for deterministic output.

pub fn contains_value(&self, value: &str) -> Result<bool, AgentRuntimeError>

Return true if any entry in this store has a value equal to value.

Performs a linear scan over all stored values. For exact-match semantics use get instead.

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

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

When multiple keys share the minimum byte length, the one that sorts first lexicographically is returned for deterministic output.

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

Return a Vec of (key_byte_len, value_byte_len) pairs for every entry.

The order of the returned pairs is unspecified (hash-map iteration order). Returns an empty Vec for an empty store.

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

Return the total byte usage of the store — the sum of all key and value byte lengths.

Returns 0 for an empty store.

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

Return the key whose value has the greatest byte length, or None if the store is empty.

When multiple values share the maximum byte length, the key that sorts first lexicographically is returned for deterministic output.

pub fn count_below_value_length( &self, max_bytes: usize, ) -> Result<usize, AgentRuntimeError>

Return the number of entries whose value byte length is strictly less than max_bytes.

Returns 0 for an empty store.

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

Return the value associated with the shortest key, or None if the store is empty.

When multiple keys share the minimum byte length, the one that sorts first lexicographically is selected for deterministic output.

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

Return all (key, value) pairs whose value byte length is strictly greater than min_value_bytes.

Returns an empty Vec for an empty store or when no values exceed the threshold.

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

Return the value for key if it exists, otherwise insert default and return it.

The returned String is always the value associated with key after this call completes. If the key was absent and the store has a capacity limit, the oldest entry may be evicted to make room for the new entry.

pub fn increment( &self, key: impl Into<String>, step: i64, ) -> Result<i64, AgentRuntimeError>

Parse the value for key as an i64, add step, and store the result.

If key does not exist it is treated as 0 before adding step. Returns the new value after the increment.

Errors

Returns AgentRuntimeError::Memory if the existing value cannot be parsed as i64.

pub fn swap(&self, key_a: &str, key_b: &str) -> Result<(), AgentRuntimeError>

Swap the values of key_a and key_b.

Returns Ok(()) when both keys exist and the swap succeeds. Returns Err when either key is absent — the store is left unchanged.

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

Return all values in the store that are non-empty strings.

The returned Vec is in insertion order. Returns an empty Vec for an empty store or when all values are empty strings.

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

Return all values sorted alphabetically.

The sort is lexicographic (byte order). Duplicate values are preserved.

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

Return the number of keys whose byte length is strictly greater than min_bytes.

Returns 0 for an empty store or when no key qualifies.

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

Return true if any two distinct keys share the same value.

Returns false for an empty store or a store with only one entry.

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

Return the value with the fewest bytes, or None for an empty store.

When multiple values share the minimum byte length the lexicographically smallest one is returned for deterministic output.

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

Return all keys whose stored value exactly equals value, sorted alphabetically.

Returns an empty Vec when no key has that value or the store is empty.

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

Return true if every value currently stored in working memory is non-empty.

Returns true when the store is empty (vacuously true). Callers that treat empty values as invalid can use this to validate the store contents in a single call.

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

Return the average byte length of all stored values.

Returns 0.0 when the store is empty to avoid division-by-zero.

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.