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

Callable Write-Back (return_as_dict mode)

When return_as_dict: true is set in the VariableMemoryModule config, the SDK wraps env_variable in a TrackedDict before passing it to the callable. TrackedDict is a transparent dict subclass — the callable interacts with it exactly like a regular Python dict — but it records any writes and syncs them back to memory automatically after the callable returns.

No explicit API call is needed inside the callable. The three tracked operations are:

• Item assignment: env_variable["key"] = value
• .update(): env_variable.update({"key": value})
• .setdefault(): env_variable.setdefault("key", value) — only triggers tracking for new keys; existing keys are not re-written

Note: add_memory() (the external API) remains the mechanism for writes made outside a callable. Auto write-back via TrackedDict and add_memory() are complementary, not mutually exclusive.

Example

async def my_agent(query: str, env_variable: dict | None = None) -> str:
    if env_variable is None:
        env_variable = {}

    # This mutation is auto-synced back to memory — no add_memory() needed
    env_variable["last_query"] = query
    env_variable.update({"session_active": "true"})

    return "Query recorded."


async def custom_demo():
    distiller_client = DistillerClient(api_key=api_key)
    distiller_client.create_project(config_path="config.yaml", project="dict_mode_demo")

    async with distiller_client(
        project="dict_mode_demo",
        uuid="test_user",
        executor_dict={"My Agent": my_agent},
    ) as dc:
        responses = await dc.query(query="What is the capital of France?")
        async for response in responses:
            print(response["content"])

        # Confirm the write-back persisted
        env_memory = await dc.retrieve_memory(source="env_variable")
        print(f"Updated env variables:\n{env_memory}")

After the query completes, retrieve_memory will show last_query and session_active as persisted entries.

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.