Environment Variable Memory Module (`VariableMemoryModule`)¶

The Environment Variable Memory Module stores key-value pairs that can be used to personalize your AI assistant's responses based on user preferences, context, or application state.

Purpose¶

Store environment variables (key-value pairs) that can be used to personalize responses and maintain application-specific context across conversations.

Parameters¶

variables: A dictionary of key-value pairs representing environment variables.
max_context: Max total character count for retrieved env variables. Must be a positive integer.
return_as_dict: bool, default False. When True, delivers env_variable to custom agent callables as a plain Python dict instead of the legacy character-limited formatted string. Cannot be set together with max_context — the validator raises a ValueError if both are present.

Example¶

Environment variables are typically included in agent prompts to provide context and personalization. For example:

# To customize VariableMemoryModule, define memory_config and include it in the memory_modules. 
# Otherwise, omit this block to use defaults.
memory_config:
  memory_modules:
    - memory_name: env_variable            # Required. Unique identifier for this memory module.
      memory_class: VariableMemoryModule   # Required. Memory module class.
      config:                              # Optional. Specified per-module configuration.
        max_context: 5000                  # Optional. Max total character count for retrieved env variables. Must be a positive integer. Defaults to 10,000.
        variables:                         # Optional. Dictionary of environment variables
          event_title: "FIFA World Cup"    # Optional. Key-value pairs.
          event_year: "2022"
          supporting_team: "Brazil"

These variables can then be retrieved and included in your agent's prompt to provide personalized context.

Dictionary Mode (`return_as_dict: true`)¶

By default (return_as_dict not set or false), env_variable is delivered to custom agent callables as a formatted string, subject to the max_context character limit. This is the legacy string mode — existing examples continue to work unchanged.

When return_as_dict: true is set, the env_variable kwarg is delivered as a plain Python dict with no character limit or formatting. This allows direct key access and mutation inside the callable.

Note: return_as_dict: true and max_context are mutually exclusive. Setting both raises a ValueError at project creation time.

YAML Configuration¶

memory_config:
  memory_modules:
    - memory_name: env_variable
      memory_class: VariableMemoryModule
      config:
        # return_as_dict and max_context cannot both be set
        return_as_dict: true
        variables:
          user_name: "Alice"
          preferred_language: "English"
          session_goal: "Learn about World Cup 2022"

Python Callable Example¶

When return_as_dict: true, the callable receives env_variable as a regular dict and can read or mutate it directly:

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

    # Read values directly — no string parsing needed
    user_name = env_variable.get("user_name", "there")

    # Mutate to write back to memory (any of these forms work)
    env_variable["last_query"] = query            # item assignment
    env_variable.update({"session_active": "true"})  # .update()
    env_variable.setdefault("visit_count", "1")   # .setdefault() for new keys only

    return f"Hello {user_name}, I've noted your query."

The SDK transparently wraps env_variable in a TrackedDict — a dict subclass — before passing it to the callable. Any writes made via item assignment, .update(), or .setdefault() (for new keys only) are automatically captured and synced back to memory after the callable returns. The callable does not need to return anything special; mutations take effect automatically.

Adding or Overriding Variables at Runtime¶

You can dynamically add or update environment variables during runtime using the add_memory() method.

Environment Variable Memory Module (VariableMemoryModule)¶