Struct SemanticStore 

pub struct SemanticStore { /* private fields */ }

Stores semantic (fact-based) knowledge as tagged key-value pairs.

Guarantees

• Thread-safe via Arc<Mutex<_>>
• Retrieval by tag intersection
• Optional vector-based similarity search via stored embeddings

Implementations

impl SemanticStore

pub fn new() -> Self

Create a new empty semantic store.

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

Store a key-value pair with associated tags.

pub fn store_with_embedding( &self, key: impl Into<String> + Debug, value: impl Into<String> + Debug, tags: Vec<String>, embedding: Vec<f32>, ) -> Result<(), AgentRuntimeError>

Store a key-value pair with an embedding vector for similarity search.

Errors

Returns Err(AgentRuntimeError::Memory) if embedding is empty or dimension mismatches.

pub fn retrieve( &self, tags: &[&str], ) -> Result<Vec<(String, String)>, AgentRuntimeError>

Retrieve all entries that contain all of the given tags.

If tags is empty, returns all entries.

pub fn retrieve_similar( &self, query_embedding: &[f32], top_k: usize, ) -> Result<Vec<(String, String, f32)>, AgentRuntimeError>

Retrieve top-k entries by cosine similarity to query_embedding.

Only entries that were stored with an embedding (via store_with_embedding) are considered. Returns (key, value, similarity) sorted by descending similarity.

Returns Err(AgentRuntimeError::Memory) if query_embedding dimension mismatches.

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

Update the value of the first entry whose key matches key.

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

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

Look up a single entry by its exact key.

Returns Ok(Some((value, tags))) if found, Ok(None) if not.

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

Return true if an entry with the given key is stored.

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

Remove all entries.

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

Count entries that contain tag (case-sensitive).

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

Return all unique tags present across all stored entries, in sorted order.

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

Remove all entries that have the given tag.

Returns the number of entries removed.

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

Return the tag that appears most often across all entries.

Returns None if there are no tagged entries.

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

Return the keys of all entries that have the given tag.

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

Return a sorted list of every distinct tag appearing across all entries.

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

Return the number of distinct tags across all stored entries.

Equivalent to list_tags()?.len() but avoids allocating the full tag list.

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

Return the number of entries that have an associated embedding vector.

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

Return the stored value for the first entry whose key matches key, or None if no such entry exists.

Simpler alternative to retrieve_by_key when only the value is needed and tags are not required.

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

Return the tags for the first entry whose key matches key.

Returns None if no entry with that key exists.

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

Return all entry keys that contain tag (case-sensitive).

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

Return the tags associated with the first entry matching key, or None if no entry with that key exists.

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

Return true if at least one entry with the given key exists.

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

Return the value string of the first entry whose key matches key, or None if no such entry exists.

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

Return the number of entries that have no tags.

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

Return the keys of all entries that have no tags. Return the key of the entry with the most tags, or None if the store is empty.

pub fn rename_tag( &self, old_tag: &str, new_tag: &str, ) -> Result<usize, AgentRuntimeError>

Return the count of entries whose value contains substring. Rename old_tag to new_tag across all entries.

Returns the number of entries that were modified.

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

Return the count of entries whose value contains substring.

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

Return the keys of all entries that have no tags.

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

Return the mean number of tags per entry.

Returns 0.0 when the store is empty.

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

Return the key of the most recently inserted entry, or None if empty.

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

Return the key of the earliest inserted entry, or None if empty.

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

Remove all entries whose key equals key.

Returns the number of entries removed.

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

Return the number of entries that include tag in their tag list.

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

Return all stored entry keys in insertion order.

Duplicate keys (if any) will appear multiple times.

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

Return all stored entry keys in insertion order.

Alias for list_keys using more idiomatic naming.

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

Return the stored value for every entry, in insertion order.

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

Return all keys that contain pattern as a substring (case-insensitive).

Useful for prefix/contains searches without loading values.

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

Update the stored value of the first entry whose key matches key.

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

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

Return all stored entries as a HashMap<key, value>.

Useful for serialization or bulk inspection. Tags and embeddings are discarded; use iter() / retrieve_by_key when those are needed.

pub fn update_tags( &self, key: &str, new_tags: Vec<String>, ) -> Result<bool, AgentRuntimeError>

Update the tags of the first entry whose key matches key.

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

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

Return the sum of byte lengths of all stored values.

Returns 0 if no entries have been stored.

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

Return the mean byte length of all stored values.

Returns 0.0 if no entries have been stored.

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

Return the byte length of the longest stored value.

Returns 0 if no entries have been stored.

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

Return the byte length of the shortest stored value.

Returns 0 if no entries have been stored.

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

Return all stored keys in ascending sorted order.

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

Return the total number of stored entries.

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

Return true if no entries have been stored.

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

Return the number of stored entries.

Alias for len using conventional naming.

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

Remove the first entry with key key.

Returns Ok(true) if an entry was found and removed, Ok(false) if no entry with that key exists.

Trait Implementations

impl Clone for SemanticStore

fn clone(&self) -> SemanticStore

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SemanticStore

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

Formats the value using the given formatter.

impl Default for SemanticStore

fn default() -> Self

Returns the “default value” for a type.