Skip to content

Memory API methods

This section provides a detailed reference for the API methods used to interact with memory modules, including module-specific parameters and return values. A brief overview is also available in Distiller API references.

retrieve_memory()

The retrieve_memory() method retrieves memory content as a formatted string. This method works with both chat history and environment variable memory modules.

Parameters

The method accepts the following parameters:

  • source (required): The memory module name (e.g., "chat_history")
  • n_rounds (optional): Number of most recent conversation rounds to retrieve. Must be a positive integer. Overrides the default set in configuration
  • max_context (optional): Maximum total character count for the retrieved content. Must be a positive integer. Overrides the default set in configuration
  • format (optional): Return format - either 'str' (default, human-readable) or 'json_string' (JSON array format)
  • truncation_notice (optional): Custom message to use when content is truncated (chat history only)
  • no_history_message (optional): Custom message to return when no history exists (chat history only)
  • query (optional): Query text used to retrieve relevant information (required for MemTree; optional for other memory modules).

Note: n_rounds, max_context, format, truncation_notice, and no_history_message are specific to chat history retrieval. query is specific to MemTree.

Returns

For Chat History (source="chat_history"):

The default 'str' format returns memory in the pattern <role>: <content>, where:

  • <role>: The agent or user role that generated the message
    • "user" - User messages
    • Agent names (e.g., "orchestrator", "Memory Insight Agent", "Search Agent")
  • <content>: The actual message content

Rounds are separated by blank lines for readability.

For Environment Variables (source="env_variable"):

Returns a string representation of the stored key-value pairs: 

event_title: "FIFA World Cup"
event_year: "2022"
supporting_team: "Brazil"
For MemTree (source="chat_history_memtree", query=query):

The default 'str' format returns retrieved memory as a newline-joined list of node contents, where the textual content stored at the node may be the raw inserted text, or an LLM-merged summary maintained at internal nodes as new information is added.

Retrieval is query-driven: MemTree embeds the provided query and returns the most similar content.

Note: The retrieve_memory() method returns the memory content directly as a string, not as a response object. This makes it easy to use the retrieved information in your applications.

add_memory()

The add_memory() method adds or updates environment variables in memory. This is particularly useful for dynamic personalization at runtime.

Note: This method is used for environment variables only and does not apply to chat history. Chat history is automatically managed by the system as conversations occur.

Parameters

  • source (required): The memory module name (typically "env_variable")
  • variables_dict (required): A dictionary containing the key-value pairs to add or update

Usage

# Add environment variables to memory
await dc.add_memory(
    source="env_variable",                # specify the memory module identifier
    variables_dict={                      # arbitrary key-value pairs to store
        "user_preference": "dark_mode",   # preferred interface mode
        "language": "English",            # preferred language
        "timezone": "UTC",                # preferred timezone
    },
)

Note: dc refers to a distiller. See the distiller documentation for usage details.

Key Points:

  • New variables are added to the existing memory
  • Existing variables with the same key are updated
  • Useful for maintaining dynamic application state throughout a session
  • Changes persist for the duration of the session

Parsing and Handling Retrieved Memory

When working with retrieved memory, you may need to parse the content for use in your application:

For Chat History:

  • Parse line-by-line for string format (role: content pattern)
  • Use JSON parsing for format="json_string" to get structured message objects

For Environment Variables:

  • Parse the key-value pairs as needed
  • Use the values to personalize prompts and agent behavior

See the Examples for practical code examples.