calute.memory.user_memory

calute.memory.user_memory#

User-specific memory for personalization.

class calute.memory.user_memory.UserMemory(storage: Any | None = None)[source]#

Bases: object

User-specific memory manager with per-user isolation.

Maintains separate ContextualMemory and EntityMemory instances for each user, along with per-user preference dictionaries. This allows agents to personalise responses and retain context across sessions on a per-user basis.

storage#

Optional MemoryStorage backend used for persisting user preferences and passed to per-user memory instances.

user_memories#

Dictionary mapping user IDs to their ContextualMemory instances.

user_entities#

Dictionary mapping user IDs to their EntityMemory instances.

user_preferences#

Dictionary mapping user IDs to preference dictionaries (response style, verbosity, language, etc.).

Example

>>> from calute.memory import UserMemory
>>> um = UserMemory()
>>> um.save_memory("user-1", "Prefers dark mode")
>>> um.update_user_preferences("user-1", {"theme": "dark"})
>>> ctx = um.get_user_context("user-1")
clear_user_memory(user_id: str) → None[source]#

Clear all data for a user and remove them from the manager.

Clears and deletes the user’s ContextualMemory, EntityMemory, and preference dictionary. After this call the user is treated as if they never existed; a subsequent call to get_or_create_user_memory() will re-initialise them with fresh defaults.

Parameters

user_id – Unique identifier for the user to clear.

get_or_create_user_memory(user_id: str) → ContextualMemory[source]#

Get or lazily create the memory subsystem for a user.

On first call for a given user_id, creates:

  • A ContextualMemory (using storage for long-term).

  • An EntityMemory (using storage for persistence).

  • A default preferences dictionary (see _get_default_preferences()).

Subsequent calls return the existing ContextualMemory.

Parameters

user_id – Unique identifier for the user.

Returns

The ContextualMemory instance associated with the user.

get_user_context(user_id: str) → str[source]#

Build a formatted context string for a user.

Combines three sections into a single string separated by blank lines:

  1. User preferences – the current preference dictionary.

  2. Context summary – from the user’s ContextualMemory.

  3. Known entities – up to 10 entity names from the user’s EntityMemory.

Parameters

user_id – Unique identifier for the user.

Returns

Multi-line context string suitable for inclusion in an agent’s system prompt or context window.

get_user_preferences(user_id: str) → dict[str, Any][source]#

Retrieve the preferences for a user.

Parameters

user_id – Unique identifier for the user.

Returns

Dictionary of user preferences. Returns a fresh set of default preferences if the user has not been registered yet.

get_user_statistics(user_id: str) → dict[str, Any][source]#

Compute aggregate statistics for a user’s memory subsystem.

Parameters

user_id – Unique identifier for the user.

Returns

  • "user_id": the queried user ID.

  • "total_memories": combined short-term and long-term count.

  • "short_term_memories": short-term item count (if available).

  • "long_term_memories": long-term item count (if available).

  • "entities_known": number of tracked entities.

  • "relationships": total relationship pair count.

  • "preferences": the user’s current preference dictionary.

Return type

Dictionary with keys

save_memory(user_id: str, content: str, metadata: dict[str, Any] | None = None, **kwargs)[source]#

Save a memory item for a specific user.

Stores the content in both the user’s ContextualMemory (for context-aware retrieval and promotion) and EntityMemory (for entity tracking).

Parameters

  • user_id – Unique identifier for the user. If the user does not yet exist, their memory subsystem is created automatically.

  • content – Text content to store.

  • metadata – Optional key-value metadata. A "user_id" key is added automatically.

  • **kwargs – Additional keyword arguments forwarded to the underlying save methods (e.g. importance, agent_id).

Returns

The MemoryItem created by the contextual memory store.

search_user_memory(user_id: str, query: str, limit: int = 10, **kwargs) → list[source]#

Search memories for a specific user.

Delegates to the user’s ContextualMemory search, which queries both short-term and long-term stores.

Parameters

  • user_id – Unique identifier for the user. If the user does not yet exist, their memory subsystem is created automatically.

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

  • limit – Maximum number of results to return.

  • **kwargs – Additional keyword arguments forwarded to ContextualMemory.search().

Returns

List of matching MemoryItem instances sorted by relevance.

update_user_preferences(user_id: str, preferences: dict[str, Any]) → None[source]#

Update user preferences by merging new values.

Existing keys are overwritten, new keys are added, and the full preference dictionary is persisted to the storage backend.

Parameters

  • user_id – Unique identifier for the user. If no preferences exist yet, defaults are initialised first.

  • preferences – Dictionary of preference keys and their new values to merge into the existing preferences.

Contents