calute.memory.long_term_memory

calute.memory.long_term_memory#

Long-term memory implementation with persistence and semantic search.

class calute.memory.long_term_memory.LongTermMemory(storage: Any | None = None, enable_embeddings: bool = True, db_path: str | None = None, max_items: int = 10000, retention_days: int = 365)[source]#

Bases: Memory

Long-term memory with persistence and semantic search.

Designed for storing important information over extended periods. Supports both keyword-based and semantic (vector similarity) search depending on the storage backend. Automatically cleans up expired or low-importance memories when the item limit is reached.

retention_days#

Number of days a memory item is retained before it becomes eligible for automatic cleanup.

storage#

The underlying MemoryStorage backend used for persistence. May be a SQLiteStorage, RAGStorage, or any compatible implementation.

Example

>>> from calute.memory import LongTermMemory
>>> ltm = LongTermMemory(retention_days=90, max_items=500)
>>> item = ltm.save("Project deadline is March 15", importance=0.9)
>>> results = ltm.search("deadline")
clear() → None[source]#

Clear all long-term memories.

Removes all items from memory and storage backend. This operation permanently deletes all stored memories.

consolidate(merge_similar: bool = True, similarity_threshold: float = 0.8) → str[source]#

Consolidate memories by merging similar entries and producing a summary.

Groups memories by conversation or agent, merges similar entries to reduce redundancy, removes low-value items, and produces a human-readable summary. When merge_similar is True, entries with high word overlap are combined into single entries.

Parameters

  • merge_similar – Whether to merge entries with similar content

  • similarity_threshold – Word overlap ratio to consider entries similar (0-1)

Returns

Formatted string summary of consolidated long-term memory contents

delete(memory_id: str | None = None, filters: dict[str, Any] | None = None) → int[source]#

Delete memory items by ID or filter criteria.

Removes items from both memory and storage backend if configured.

Parameters

  • memory_id – Specific memory ID to delete

  • filters – Filter criteria to match items for deletion

Returns

Number of items deleted

retrieve(memory_id: str | None = None, filters: dict[str, Any] | None = None, limit: int = 10) → calute.memory.base.MemoryItem | list[calute.memory.base.MemoryItem] | None[source]#

Retrieve specific memories by ID or filter criteria.

When memory_id is provided, returns the specific item and updates its access count. Otherwise, filters through memories and returns matches.

Parameters

  • memory_id – Specific memory ID to retrieve

  • filters – Filter criteria to match against memory attributes and metadata

  • limit – Maximum number of items to return when using filters

Returns

Single MemoryItem if memory_id provided, list of MemoryItem if filters used, or None if memory_id not found

save(content: str, metadata: dict[str, Any] | None = None, agent_id: str | None = None, user_id: str | None = None, conversation_id: str | None = None, importance: float = 0.5, **kwargs) → MemoryItem[source]#

Save a new item to long-term memory with importance scoring.

Creates a MemoryItem with memory_type="long_term", stores it in both the in-memory index and the persistent storage backend (if configured). If the item limit has been reached, _cleanup_old_memories() is called first to free space.

Parameters

  • content – Text content to store.

  • metadata – Optional key-value metadata. An "importance" key is added automatically from the importance parameter.

  • agent_id – Identifier of the agent that created this memory.

  • user_id – Identifier of the user associated with this memory.

  • conversation_id – Identifier of the conversation context.

  • importance – Importance weight (0.0–1.0) used for ranking and cleanup decisions.

  • **kwargs – Extra key-value pairs merged into metadata.

Returns

The newly created MemoryItem.

search(query: str, limit: int = 10, filters: dict[str, Any] | None = None, use_semantic: bool = True, **kwargs) → list[calute.memory.base.MemoryItem][source]#

Search long-term memory using semantic similarity or keyword matching.

When the storage backend is a RAGStorage instance and use_semantic is True, performs vector-similarity search. Otherwise, falls back to keyword matching with a composite scoring formula that blends text relevance (50 %), recency (30 %), and importance (20 %).

Matching items have their access_count incremented and last_accessed timestamp updated as a side-effect.

Parameters

  • query – Natural-language or keyword search query string.

  • limit – Maximum number of results to return.

  • filters – Optional key-value criteria for narrowing results. Checked against both item attributes and metadata.

  • use_semantic – When True and a RAGStorage backend is available, performs vector-based semantic search.

  • **kwargs – Additional keyword arguments (currently unused).

Returns

List of MemoryItem instances sorted by descending relevance score, with at most limit entries.

update(memory_id: str, updates: dict[str, Any]) → bool[source]#

Update a memory item with new values.

Persists changes to storage backend if configured.

Parameters

  • memory_id – ID of the memory item to update

  • updates – Dictionary of field names and new values to apply

Returns

True if the update was successful, False if memory_id not found

Contents