fabricatio_memory.rust

Attributes

MAX_IMPORTANCE_SCORE
MIN_IMPORTANCE_SCORE

Classes

Memory	Represents a memory object with content, importance, tags, and access statistics.
MemoryService	Service class for managing memory stores and indexes.
MemoryStats	Memory statistics structure containing aggregated metrics about stored memories.
MemoryStore	MemoryStore is a struct that provides an interface for storing, retrieving, and searching memories in a Tantivy search index.

Package Contents

fabricatio_memory.rust.MAX_IMPORTANCE_SCORE: int = 100

fabricatio_memory.rust.MIN_IMPORTANCE_SCORE: int = 0

class fabricatio_memory.rust.Memory

Represents a memory object with content, importance, tags, and access statistics.

property uuid: str

Unique identifier for the memory.

property content: str

Content of the memory.

property timestamp: int

Unix timestamp when the memory was created.

property importance: int

Importance score of the memory (0 to MAX_IMPORTANCE_SCORE).

property tags: list[str]

List of tags associated with the memory.

property access_count: int

Number of times the memory has been accessed.

property last_accessed: int

Unix timestamp when the memory was last accessed.

to_dict() → dict

Convert the memory to a Python dictionary.

class fabricatio_memory.rust.MemoryService

Service class for managing memory stores and indexes.

get_store(store_name: str) → MemoryStore

Gets a MemoryStore instance for the given store name.

This method retrieves or creates an index for the given store name, then returns a MemoryStore instance that can be used to perform operations on that index.

Parameters:

store_name (str) – The name of the store to get.

Returns:

A MemoryStore instance for the given store name.

Return type:

MemoryStore

Raises:

Exception – If the store name is invalid, if there’s an error creating or opening the index, or if there’s an error creating the MemoryStore instance.

list_stores(cached_only: bool = False) → list[str]

Lists all stores in the system.

This method returns a list of all store names. It can optionally return only the stores that are currently cached in memory.

Parameters:

cached_only (bool, optional) – If True, only return stores that are currently cached in memory. If False (default), return all stores in the store directory.

Returns:

A list of store names.

Return type:

list[str]

Raises:

Exception – If there’s an error reading the store directory.

class fabricatio_memory.rust.MemoryStats

Memory statistics structure containing aggregated metrics about stored memories.

property total_memories: int

Total number of memories stored.

property avg_importance: float

Average importance score across all memories.

property avg_access_count: float

Average number of times memories have been accessed.

property avg_age_days: float

Average age of memories in days.

display() → str

Display memory statistics in a formatted string.

class fabricatio_memory.rust.MemoryStore

MemoryStore is a struct that provides an interface for storing, retrieving, and searching memories in a Tantivy search index.

It supports operations such as adding, updating, deleting, and searching memories based on various criteria like content, tags, importance, recency, and access frequency.

The store handles memory access tracking by updating access counts and timestamps automatically during retrieval and search operations. It also supports batch updates and optional immediate disk writes for consistency.

The implementation uses a Tantivy index with fields for content, tags, importance, timestamps, and access counts. It includes PyO3 bindings to allow Python usage.

add_memory(content: str, importance: int, tags: Sequence[str], write: bool = False) → str

Adds a new memory to the system and returns its unique ID.

Parameters:

• content (str) – The text content of the memory.

• importance (int) – The importance score of the memory.

• tags (list[str]) – A list of tags associated with the memory.

• write (bool, optional) – If True, commits the changes to disk immediately. Defaults to False.

Returns:

The UUID of the newly added memory.

Return type:

str

Raises:

Exception – If there is an error adding the memory or writing to the index.

write() → None

Writes all pending changes to disk.

Returns:

None

Raises:

Exception – If there is an error committing the changes.

get_memory(uuid: str, write: bool = False) → Memory | None

Retrieves a memory by its ID and updates its access count.

Parameters:

• uuid (str) – The unique identifier of the memory.

• write (bool, optional) – If True, commits the access update to disk immediately. Defaults to False.

Returns:

The retrieved Memory object, or None if not found.

Return type:

Memory | None

Raises:

Exception – If there is an error retrieving the memory or updating the index.

update_memory(uuid: str, content: str | None = None, importance: int | None = None, tags: Sequence[str] | None = None, write: bool = False) → bool

Updates an existing memory’s content, importance, or tags.

Parameters:

• uuid (str) – The unique identifier of the memory to update.

• content (str | None, optional) – The new content. Defaults to None.

• importance (int | None, optional) – The new importance score. Defaults to None.

• tags (list[str] | None, optional) – The new list of tags. Defaults to None.

• write (bool, optional) – If True, commits the changes to disk immediately. Defaults to False.

Returns:

True if the memory was found and updated, False otherwise.

Return type:

bool

Raises:

Exception – If there is an error updating the memory or writing to the index.

delete_memory(uuid: str, write: bool = False) → bool

Deletes a memory by its ID.

Parameters:

• uuid (str) – The unique identifier of the memory to delete.

• write (bool, optional) – If True, commits the deletion to disk immediately. Defaults to False.

Returns:

True if the deletion operation was processed (returns True even if memory didn’t exist).

Return type:

bool

Raises:

Exception – If there is an error deleting the memory or writing to the index.

search_memories(query_str: str, top_k: int = 20, boost_recent: bool = False, write: bool = False) → list[Memory]

Searches memories by query string with optional recency boosting.

Parameters:

• query_str (str) – The search query string.

• top_k (int, optional) – The maximum number of results to return. Defaults to 20.

• boost_recent (bool, optional) – If True, boosts the score of more recent memories. Defaults to False.

• write (bool, optional) – If True, commits access updates to disk immediately. Defaults to False.

Returns:

A list of matching Memory objects, sorted by relevance.

Return type:

list[Memory]

Raises:

Exception – If there is an error parsing the query or searching the index.

search_by_tags(tags: Sequence[str], top_k: int = 20, write: bool = False) → list[Memory]

Searches memories by specific tags.

Parameters:

• tags (list[str]) – A list of tags to search for. Memories matching any of these tags will be returned.

• top_k (int, optional) – The maximum number of results to return. Defaults to 20.

• write (bool, optional) – If True, commits access updates to disk immediately. Defaults to False.

Returns:

A list of matching Memory objects.

Return type:

list[Memory]

Raises:

Exception – If there is an error searching the index.

get_memories_by_importance(min_importance: int, top_k: int = 20, write: bool = False) → list[Memory]

Gets memories filtered by a minimum importance level.

Parameters:

• min_importance (int) – The minimum importance score.

• top_k (int, optional) – The maximum number of results to return. Defaults to 20.

• write (bool, optional) – If True, commits access updates to disk immediately. Defaults to False.

Returns:

A list of Memory objects with importance >= min_importance.

Return type:

list[Memory]

Raises:

Exception – If there is an error searching the index.

get_recent_memories(days: int, top_k: int = 20, write: bool = False) → list[Memory]

Gets memories from the last N days.

Parameters:

• days (int) – The number of days to look back.

• top_k (int, optional) – The maximum number of results to return. Defaults to 20.

• write (bool, optional) – If True, commits access updates to disk immediately. Defaults to False.

Returns:

A list of Memory objects created within the last N days.

Return type:

list[Memory]

Raises:

Exception – If there is an error searching the index.

get_frequently_accessed(top_k: int = 20, write: bool = False) → list[Memory]

Gets memories sorted by access frequency (most accessed first).

Parameters:

• top_k (int, optional) – The maximum number of results to return. Defaults to 20.

• write (bool, optional) – If True, commits access updates to disk immediately. Defaults to False.

Returns:

A list of Memory objects sorted by access count in descending order.

Return type:

list[Memory]

Raises:

Exception – If there is an error searching the index.

count_memories() → int

Counts the total number of memories in the system.

Returns:

The total number of documents in the index.

Return type:

int

stats() → MemoryStats

Gets aggregated statistics about all memories.

Returns:

An object containing total memories, average importance,

average access count, and average age in days.

Return type:

MemoryStats

Raises:

Exception – If there is an error calculating aggregations.