calute.tools.memory_tool

calute.tools.memory_tool#

Memory management tools for agents to read and write memories autonomously.

This module provides a complete memory management toolkit for Calute agents, enabling them to store, retrieve, search, and manage memories. It includes: - Save and retrieve memory entries with categorization and tagging - Search memories by query, type, tags, and time range - Consolidate and summarize agent memories - Delete memories by various criteria - Get memory statistics and tag information - Helper functions to add memory tools to existing agents

The memory tools integrate with the Calute memory store system and support multiple memory types: short_term, long_term, working, episodic, semantic, and procedural.

Example

>>> from calute.tools.memory_tool import save_memory, search_memory
>>> result = save_memory(
...     content="User prefers dark mode",
...     tags=["preference", "ui"],
...     context_variables={"memory_store": store}
... )
>>> memories = search_memory(
...     query="preferences",
...     context_variables={"memory_store": store}
... )
class calute.tools.memory_tool.MemoryOperation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Types of memory operations agents can perform.

Enumeration of available memory operations for tracking and categorizing memory-related actions.

SAVE#

Store a new memory entry.

SEARCH#

Search for memories by query and filters.

RETRIEVE#

Retrieve specific memories.

DELETE#

Remove memories from the store.

SUMMARIZE#

Generate summaries of memories.

CONSOLIDATE#

Consolidate related memories.

CONSOLIDATE = 'consolidate'#
DELETE = 'delete'#
RETRIEVE = 'retrieve'#
SAVE = 'save'#
SEARCH = 'search'#
SUMMARIZE = 'summarize'#
class calute.tools.memory_tool.MemoryToolContext(memory_store)[source]#

Bases: object

Context manager for memory tools in function execution.

Automatically provides memory_store in context_variables for memory tool functions. Use this to wrap function calls and ensure the memory store is always available.

memory_store#

The memory store instance to inject into context.

Example

>>> context = MemoryToolContext(memory_store)
>>> result = context.wrap_function_call(save_memory, content="test")
wrap_function_call(func, *args, **kwargs)[source]#

Wrap a function call to inject memory_store into context_variables.

Parameters

  • func – The memory tool function to call.

  • *args – Positional arguments to pass to the function.

  • **kwargs – Keyword arguments to pass to the function.

Returns

The result of calling the wrapped function.

calute.tools.memory_tool.add_memory_tools_to_agent(agent: Agent, memory_store=None, include_tools: list[str] | None = None) → Agent[source]#

Add memory management tools to an agent’s function list.

Appends the selected memory tool functions to the agent’s functions list, avoiding duplicates. Optionally sets the memory store on the agent instance if the agent has a _memory_store attribute.

Parameters

  • agent – The Agent instance to add memory tools to. Its functions list will be modified in-place.

  • memory_store – The memory store instance to associate with the agent. If the agent has a _memory_store attribute, it will be set to this value.

  • include_tools – List of specific tool function names to include. If None, all tools from MEMORY_TOOLS are added. Valid names: “save_memory”, “search_memory”, “consolidate_agent_memories”, “delete_memory”, “get_memory_statistics”, “get_memory_tags_and_terms”.

Returns

The same Agent instance with memory tools appended to its functions list.

Example

>>> from calute import Agent
>>> agent = Agent(id="assistant", instructions="You help users", functions=[])
>>> agent = add_memory_tools_to_agent(agent, memory_store=my_store)
>>> agent = add_memory_tools_to_agent(
...     agent, include_tools=["save_memory", "search_memory"]
... )
calute.tools.memory_tool.consolidate_agent_memories(agent_id: str, max_items: int = 20, context_variables: dict[str, Any] | None = None) → dict[str, Any][source]#

Get a consolidated summary of memories for a specific agent.

Retrieves up to max_items memories for the given agent and groups them by tag into a human-readable summary. Also returns overall memory store statistics.

Parameters

  • agent_id – Identifier of the agent whose memories to consolidate.

  • max_items – Maximum number of memories to include in the consolidation. Defaults to 20.

  • context_variables – Runtime context dictionary from the agent. Must contain a “memory_store” key with an initialized memory store instance.

Returns

  • status (str): “success” or “error”.

  • summary (str): Human-readable summary of memories organized by tag category. Shows up to 3 items per tag with overflow counts.

  • statistics (dict): Overall memory store statistics from the underlying store’s get_statistics() method.

  • message (str): Error message (on failure).

Return type

A dictionary containing

Example

>>> result = consolidate_agent_memories(
...     agent_id="research_agent",
...     context_variables={"memory_store": store}
... )
>>> print(result["summary"])
calute.tools.memory_tool.create_memory_enabled_agent(agent_id: str, instructions: str, memory_store=None, memory_tools: list[str] | None = None, **agent_kwargs) → Agent[source]#

Create a new agent with memory tools pre-configured.

Convenience factory that creates an Agent instance and immediately adds memory management tools to it via add_memory_tools_to_agent.

Parameters

  • agent_id – Unique identifier for the new agent.

  • instructions – System prompt / instructions for the agent.

  • memory_store – Memory store instance to associate with the agent. Passed through to add_memory_tools_to_agent.

  • memory_tools – List of memory tool function names to include. If None, all memory tools are added. See add_memory_tools_to_agent for valid names.

  • **agent_kwargs – Additional keyword arguments forwarded to the Agent constructor (e.g., model, temperature).

Returns

A new Agent instance with the specified memory tools already added to its functions list.

Example

>>> agent = create_memory_enabled_agent(
...     agent_id="assistant",
...     instructions="You remember past conversations",
...     memory_store=my_store,
...     memory_tools=["save_memory", "search_memory"]
... )
calute.tools.memory_tool.delete_memory(memory_id: str | None = None, tags: list[str] | None = None, agent_id: str | None = None, older_than: str | None = None, context_variables: dict[str, Any] | None = None) → dict[str, Any][source]#

Delete memories based on one or more criteria.

Removes memories from the store matching the specified criteria. At least one criterion (memory_id, tags, agent_id, or older_than) must be provided. When memory_id is given, it takes precedence and deletes that specific memory. Otherwise, the remaining criteria are combined as filters.

Parameters

  • memory_id – Specific memory ID to delete. If provided, deletes exactly this memory regardless of other criteria.

  • tags – Delete all memories that have any of these tags.

  • agent_id – Delete all memories created by this agent.

  • older_than – Delete memories created before this ISO 8601 timestamp string (e.g., “2024-01-01T00:00:00”).

  • context_variables – Runtime context dictionary from the agent. Must contain a “memory_store” key with an initialized memory store instance.

Returns

  • status (str): “success” or “error”.

  • deleted_count (int): Number of memories deleted (on success).

  • message (str): Human-readable status or error message.

Return type

A dictionary containing

Example

>>> result = delete_memory(
...     tags=["temporary"],
...     context_variables={"memory_store": store}
... )
>>> print(result["deleted_count"])
3
calute.tools.memory_tool.get_memory_statistics(agent_id: str | None = None, context_variables: dict[str, Any] | None = None) → dict[str, Any][source]#

Get statistics about memory usage.

Retrieves overall memory store statistics and optionally adds agent-specific memory counts.

Parameters

  • agent_id – If provided, includes the count of memories belonging to this specific agent in the returned statistics.

  • context_variables – Runtime context dictionary from the agent. Must contain a “memory_store” key with an initialized memory store instance.

Returns

  • status (str): “success” or “error”.

  • statistics (dict): Memory store statistics from the underlying store’s get_statistics() method. When agent_id is provided, also includes: - agent_memory_count (int): Number of memories for that agent. - agent_id (str): The agent ID queried.

  • message (str): Error message (on failure).

Return type

A dictionary containing

Example

>>> result = get_memory_statistics(
...     agent_id="main_agent",
...     context_variables={"memory_store": store}
... )
>>> print(result["statistics"]["agent_memory_count"])
42
calute.tools.memory_tool.get_memory_tags_and_terms(agent_id: str | None = None, context_variables: dict[str, Any] | None = None) → dict[str, Any][source]#

Get all available memory tags organized by memory type.

Retrieves all tags from the memory store, grouped by memory type (short_term, long_term, working, episodic, semantic, procedural). Also provides tag frequency counts and overall statistics.

Parameters

  • agent_id – Filter tags to those associated with a specific agent. If not provided, falls back to context_variables[“agent_id”] or “default”.

  • context_variables – Runtime context dictionary from the agent. Must contain a “memory_store” key with an initialized memory store instance. May also contain “agent_id”.

Returns

  • status (str): “success” or “error”.

  • tags_by_type (dict[str, list[str]]): Tags grouped by memory type. Only types with tags are included.

  • all_tags (list[str]): Sorted list of all unique tags.

  • tag_frequency (dict[str, int]): Tag-to-count mapping sorted by frequency (descending).

  • total_unique_tags (int): Total count of unique tags.

  • agent_id (str): The agent ID used for filtering.

  • message (str): Error message (on failure).

Return type

A dictionary containing

Example

>>> result = get_memory_tags_and_terms(
...     context_variables={"memory_store": store}
... )
>>> print(result["all_tags"])
['preference', 'ui', 'workflow']
calute.tools.memory_tool.get_memory_tool_descriptions() → list[dict[str, str]][source]#

Get descriptions of all memory tools for agent documentation.

Iterates over the MEMORY_TOOLS list and extracts the name, first-line description, and category for each tool function.

Returns

  • name (str): The function name of the tool.

  • description (str): First line of the tool’s docstring.

  • category (str): Always “Memory Management”.

Return type

A list of dictionaries, each containing

calute.tools.memory_tool.save_memory(content: str, memory_type: str = 'short_term', tags: list[str] | None = None, metadata: dict[str, Any] | None = None, agent_id: str | None = None, context_variables: dict[str, Any] | None = None) → dict[str, Any][source]#

Save a memory entry to the memory store.

Stores a piece of content as a memory entry with optional type classification, tagging, and metadata. Automatically timestamps the entry and associates it with the creating agent.

Parameters

  • content – The text content to remember. This is the primary payload of the memory entry.

  • memory_type – Classification of the memory. Determines how the memory is stored and retrieved. Options: - “short_term”: Temporary, session-scoped memories. - “long_term”: Persistent, cross-session memories. - “working”: Active task-related memories. - “episodic”: Event or experience memories. - “semantic”: Factual knowledge memories. - “procedural”: How-to and process memories.

  • tags – List of string tags for categorization and filtering. Used for organizing and searching memories.

  • metadata – Additional key-value metadata to store alongside the memory content. A timestamp and creator agent ID are automatically added.

  • agent_id – Identifier of the agent creating this memory. If not provided, falls back to context_variables[“agent_id”] or “default”.

  • context_variables – Runtime context dictionary from the agent. Must contain a “memory_store” key with an initialized memory store instance. May also contain “agent_id”.

Returns

  • status (str): “success” or “error”.

  • memory_id (str): Unique identifier of the saved memory (on success).

  • message (str): Human-readable status message.

Return type

A dictionary containing

Example

>>> result = save_memory(
...     content="User prefers dark mode",
...     tags=["preference", "ui"],
...     context_variables={"memory_store": store}
... )
>>> print(result["status"])
'success'
calute.tools.memory_tool.search_memory(query: str, memory_types: list[str] | None = None, tags: list[str] | None = None, limit: int = 10, agent_id: str | None = None, time_range: dict[str, str] | None = None, context_variables: dict[str, Any] | None = None) → dict[str, Any][source]#

Search for memories based on query and filters.

Retrieves memories from the store that match the given query string and optional filters. Performs keyword-based matching against memory content and tags, with support for type filtering, tag filtering, and time range constraints.

Parameters

  • query – Search query string. Words in the query are matched against memory content and tags using case-insensitive substring matching.

  • memory_types – List of memory type names to restrict the search to. Options: “short_term”, “long_term”, “working”, “episodic”, “semantic”, “procedural”. If None, searches all types.

  • tags – Filter results to only include memories that have at least one of the specified tags.

  • limit – Maximum number of results to return. Defaults to 10.

  • agent_id – Filter results to memories created by a specific agent. If not provided, falls back to context_variables[“agent_id”] or “default”.

  • time_range – Optional time range filter as a dictionary with “start” and/or “end” keys containing ISO 8601 timestamp strings. Only memories within the range are returned.

  • context_variables – Runtime context dictionary from the agent. Must contain a “memory_store” key with an initialized memory store instance. May also contain “agent_id”.

Returns

  • status (str): “success” or “error”.

  • count (int): Number of matching memories found.

  • memories (list[dict]): List of memory dicts, each with content, tags, timestamp, and metadata.

  • query (str): The original search query.

  • message (str): Error message (on failure).

Return type

A dictionary containing

Example

>>> result = search_memory(
...     query="preferences",
...     tags=["ui"],
...     limit=5,
...     context_variables={"memory_store": store}
... )
>>> print(result["count"])
2
Contents