Integrate Memory Modules into Your AI Assistant¶
Overview¶
Memory modules are crucial components in building AI assistants that can retain context, personalize interactions, and provide coherent responses over time. By integrating memory modules, your assistant can remember previous conversations, utilize environment variables, and retrieve relevant information to enhance user experience. This tutorial will guide you through configuring and using memory modules.
Configuration¶
To leverage memory modules in your assistant, you need to define their configurations in a YAML file. This configuration specifies the types of memory modules and their parameters, allowing your assistant to store and access different kinds of information.
Configuration Parameters¶
memory_config: Top-level key for memory module configurations.memory_modules: A list of memory modules to integrate.memory_name: A unique identifier for the memory module.memory_class: The class name of the memory module.kwargs: Additional parameters specific to the memory module.
Here’s an example configuration (config.yaml):
memory_config:
memory_modules:
- memory_name: chat_history
memory_class: ChatMemoryModule
kwargs:
n_rounds: 5
- memory_name: env_variable
memory_class: VariableMemoryModule
kwargs:
variables:
event_title: "FIFA World Cup"
event_year: "2022"
supporting_team: "Brazil"
main_competitors: "Argentina, Germany, France"
orchestrator:
agent_list:
- agent_name: "Search Agent"
- agent_name: "Memory Insight Agent"
utility_agents:
- agent_class: SearchAgent
agent_name: "Search Agent"
agent_description: "The Search Agent retrieves information from the web."
- agent_class: CustomAgent
agent_name: "Memory Insight Agent"
agent_description: "The Memory Insight Agent can help you by utilizing stored memory to provide context-aware responses about different sports tournaments."
Memory Modules Explained¶
Chat History Memory Module (ChatMemoryModule)¶
- Purpose: Stores previous conversation rounds to maintain context.
- Parameters:
n_rounds: The number of previous conversation rounds to remember.
Environment Variable Memory Module (VariableMemoryModule)¶
- Purpose: Stores environment variables that can be used to personalize responses.
- Parameters:
variables: A dictionary of key-value pairs representing environment variables.
Example Usage¶
This section demonstrates how to use memory modules in your AI assistant through code examples.
Define Your Custom Python Agent¶
First, define a custom agent that utilizes the memory modules. For example, a simple agent that responds based on user queries, environment variables, and chat history:
import os
import asyncio
from typing import Optional
from air import AsyncAIRefinery, base_url
from air import login, DistillerClient
# Authenticate credentials
auth = login(
account=str(os.getenv("ACCOUNT")),
api_key=str(os.getenv("API_KEY")),
)
base_url = os.getenv("AIREFINERY_ADDRESS", "")
async def memory_insight_agent(query: str, env_variable: Optional[dict]=None, chat_history: Optional[str]=None):
"""
A simple agent that generates responses based on user queries,
environment variables, and chat history.
Args:
query (str): User query to be processed.
env_variables (dict): Environment variables that can be used to personalize responses.
chat_history (str): Previous conversation rounds to maintain context.
Returns:
str: Assistant's response.
"""
# Construct the prompt with environment variables and chat history
prompt = f"""
You are a helpful personal assistant focused on the FIFA World Cup 2022. Use the user's environment variables and previous conversation to provide a personalized and relevant response to the user's query. Ensure that your response is informed by their preferences and past interactions.
Environment Variables:
{env_variable}
Chat History:
{chat_history}
User Query: {query}
Assistant:
"""
# Initialize the AsyncAIRefinery client using the authenticated credentials
client = AsyncAIRefinery(**auth.openai())
#print(prompt)
# Get the response from the language model
response = await client.chat.completions.create(
messages=[{"role": "user", "content": prompt}],
model="meta-llama/Llama-3.1-70B-Instruct",
)
# Return the assistant's response
return str(response.choices[0].message.content).strip()
Initialize the Distiller Client and Add Memory Modules¶
Next, initialize the DistillerClient, create a project, define custom agent mappings, and add memory entries.
async def custom_demo():
"""
Demonstrates the use of environment variables and chat history as memory in an AI assistant focused on the FIFA World Cup 2022.
"""
# Initialize a Distiller client for managing interactions
distiller_client = DistillerClient(base_url=base_url)
# Create/register a new Distiller project
distiller_client.create_project(config_path="config.yaml", project="memory_tutorial")
# Define custom agent mappings
executor_dict = {
"Memory Insight Agent": memory_insight_agent,
}
# Use the Distiller client
async with distiller_client(
project="memory_tutorial",
uuid="test_user",
executor_dict=executor_dict,
) as dc:
# Add environment variables to the memory
await dc.add_memory(
source="env_variable",
variables_dict={
"match_location": "Qatar",
"fan_experience": "High excitement and engagement",
},
)
print("\n[INFO] Environment variables added to memory.")
# List of user queries to process
queries = [
"Who are our main competitors in this world cup?",
"Which country is hosting the tournament?",
]
print("\n\n=== Custom Demo ===")
for query in queries:
responses = await dc.query(query=query)
print("-------------------------")
print(f"\nUser Query: {query}")
async for response in responses:
print(f"Response:\n{response['content']}")
Explanation¶
DistillerClient: Manages interactions with the Distiller framework.create_project: Initializes a new project using the configuration file.executor_dict: Maps the agent name to the custom agent function.add_memory: Adds environment variables to the assistant's memory under the specified source (env_variable).- Processing Queries: The assistant processes each query, accessing memory modules to generate informed responses.
Expected Output¶
After running the custom_demo function, the assistant should provide responses that utilize both the environment variables and chat history. The output might look like:
=== Custom Demo ===
-------------------------
User Query: Who are our main competitors in this world cup?
Response:
I remember we discussed this earlier. In the FIFA World Cup 2022, Brazil's main competitors are Argentina, Germany, and France. These teams have a strong track record and are expected to give Brazil a tough competition. Are you excited to see how Brazil will perform against these teams?
-------------------------
User Query: Which country is hosting the tournament?
Response:
We've been over this before! I recall you asking about the host country earlier. The FIFA World Cup 2022 is being hosted by Qatar. Isn't it exciting to think about the thrilling matches that will take place in this beautiful country? By the way, have you checked the schedule for Brazil's matches? I can help you with that if you'd like!
Advanced Memory Retrieval with Search Demo¶
You can further explore the capabilities of memory modules with advanced querying and memory retrieval:
async def search_demo():
"""
Demonstrates advanced querying and memory retrieval capabilities of the assistant.
"""
# Initialize a Distiller client
distiller_client = DistillerClient()
# Create/register a new Distiller project
distiller_client.create_project(config_path="config.yaml", project="memory_tutorial")
# Define custom agent mappings
executor_dict = {
"Memory Insight Agent": memory_insight_agent,
}
# Use the Distiller client
async with distiller_client(
project="memory_tutorial",
uuid="test_user",
executor_dict=executor_dict,
) as dc:
# List of user queries to process
queries = [
"What were the results of the semi-finals of the tournament?",
"How have our main competitors been performing since the tournament, particularly in recent developments in 2025?",
]
print("\n\n=== Search Demo ===")
for query in queries:
responses = await dc.query(query=query)
print("-------------------------")
print(f"\nUser Query: {query}")
async for response in responses:
print(f"Response:\n{response['content']}")
print("-------------------------")
# Retrieve chat history
retrieved_chat_history = await dc.retrieve_memory(
source="chat_history", n_rounds=3
)
print(f"\n[INFO] Retrieved Chat History:\n{retrieved_chat_history}\n")
Explanation¶
- Processing Advanced Queries: The assistant handles more complex queries, utilizing memory modules for informed responses.
retrieve_memory: Fetches the lastn_roundsof chat history, demonstrating how memory can be accessed and displayed.
Expected Output¶
The assistant leverages memory modules to provide detailed responses and retrieves recent chat history:
=== Search Demo ===
-------------------------
User Query: What were the results of the semi-finals of the tournament?
Response:
I see you're eager to know the semi-finals results of the FIFA World Cup 2022! As you're supporting Brazil, I'm sure you're interested in knowing how they fared. Unfortunately, Brazil was eliminated in the quarter-finals, losing to Croatia in a penalty shootout.
However, I can still provide you with the results of the semi-finals. The two matches were:
1. Argentina vs. Croatia: Argentina won 3-0, with goals from Lionel Messi, Julián Álvarez, and Alexis Mac Allister.
2. France vs. Morocco: France won 2-0, with goals from Théo Hernandez and Randal Kolo Muani.
The stage is now set for the final match between Argentina and France. As a Brazil supporter, you might be interested in knowing that Argentina is one of Brazil's main competitors, and this match is sure to be an exciting one!
-------------------------
User Query: How have our main competitors been performing since the tournament, particularly in recent developments in 2025?
Response:
I will decompose your query into subtasks and handle them one by one.Search Agent, argentina football team recent developments 2025
Response:
Searching over Web Search
Response:
**Argentina National Football Team: Recent Developments in 2025**
Argentina's national football team has been making waves in recent developments, particularly in 2025. As the reigning world champions, having won the 2022 FIFA World Cup, they continue to solidify their position as a force to be reckoned with in the football world.
**Rankings and Titles**
As of April 2025, Argentina ranks 1st in the FIFA Men's World Ranking, a testament to their consistent performance and dominance in the sport. They have also won a record 23 official titles, including the 2022 FIFA World Cup, and hold the record for the most senior official titles won.
**Notable Players and Rivalries**
Lionel Messi, the team's captain, is the all-time most-capped player with 191 matches and the highest goalscorer with 112 goals. Argentina is known for its intense rivalries with Brazil, England, Germany, Netherlands, Uruguay, Chile, and France, among others.
**Recent Matches and Performances**
In a recent World Cup qualifier match against Brazil, Argentina thrashed their arch-rivals 4-1, with Enzo Fernández scoring the second goal. This win was a significant milestone for the team, showcasing their strength and determination.
**Coaching Staff and Sponsorships**
Inter Miami CF announced Javier Mascherano's coaching staff for the 2025 season, which includes assistant coaches Lucas Rodríguez Pagano and Leandro Stillitano, among others. The team has also partnered with XBO.com, a crypto exchange, as their official global sponsor, marking a significant milestone in their global expansion strategy.
**Upcoming Matches and Events**
Argentina is set to visit India in October 2025 to play an exhibition match, which is expected to be a thrilling encounter. The team will also participate in the 2026 FIFA World Cup, where they will face stiff competition from other top teams.
Overall, Argentina's national football team continues to be a dominant force in the sport, with a strong team, notable players, and a rich history of success.
Response:
Search Agent, france football team recent developments 2025
Response:
Searching over Web Search
Response:
France's national football team has been making headlines in recent developments, particularly in 2025. As one of the main competitors, France has been working hard to maintain their position as a top team in the football world.
**Recent Performance and Rankings**
As of April 2025, France ranks 2nd in the FIFA Men's World Ranking, just behind Argentina. They have been performing well in recent matches, with a few notable wins and draws. However, they did face a setback in the UEFA Euro 2024 semi-finals, where they lost to Spain.
**Notable Players and Transfers**
Olivier Giroud, France's all-time leading scorer, has been making waves with his recent transfer to LAFC. He has been in top form, scoring crucial goals for his new team. Other notable players like Ousmane Dembele and Kylian Mbappé have also been performing well, with Dembele being PSG's top scorer with 33 goals in the current season.
**Coaching Staff and Contract Extensions**
Didier Deschamps, France's head coach, has confirmed that he will leave his contract after the 2026 World Cup. This news has sparked speculation about who will take over as the new head coach. Meanwhile, the team has been focusing on their upcoming matches, with a few key players extending their contracts with their respective clubs.
**Upcoming Matches and Events**
France is set to participate in the 2026 FIFA World Cup, where they will face stiff competition from other top teams. They will also be playing in the UEFA Nations League, where they will face teams like Spain and Portugal.
Overall, France's national football team continues to be a force to be reckoned with in the football world, with a strong team, notable players, and a rich history of success.
-------------------------
[INFO] Retrieved Chat History:
user: What were the results of the semi-finals of the tournament?
Memory Insight Agent: I see you're eager to know the semi-finals results of the FIFA World Cup 2022! As you're supporting Brazil, I'm sure you're interested in knowing how they fared. Unfortunately, Brazil was eliminated in the quarter-finals, losing to Croatia in a penalty shootout.
However, I can still provide you with the results of the semi-finals. The two matches were:
1. Argentina vs. Croatia: Argentina won 3-0, with goals from Lionel Messi, Julián Álvarez, and Alexis Mac Allister.
2. France vs. Morocco: France won 2-0, with goals from Théo Hernandez and Randal Kolo Muani.
The stage is now set for the final match between Argentina and France. As a Brazil supporter, you might be interested in knowing that Argentina is one of Brazil's main competitors, and this match is sure to be an exciting one!
user: How have our main competitors been performing since the tournament, particularly in recent developments in 2025?
orchestrator: Argentina football team recent developments 2025
Search Agent: **Argentina National Football Team: Recent Developments in 2025**
Argentina's national football team has been making waves in recent developments, particularly in 2025. As the reigning world champions, having won the 2022 FIFA World Cup, they continue to solidify their position as a force to be reckoned with in the football world.
**Rankings and Titles**
As of April 2025, Argentina ranks 1st in the FIFA Men's World Ranking, a testament to their consistent performance and dominance in the sport. They have also won a record 23 official titles, including the 2022 FIFA World Cup, and hold the record for the most senior official titles won.
**Notable Players and Rivalries**
Lionel Messi, the team's captain, is the all-time most-capped player with 191 matches and the highest goalscorer with 112 goals. Argentina is known for its intense rivalries with Brazil, England, Germany, Netherlands, Uruguay, Chile, and France, among others.
**Recent Matches and Performances**
In a recent World Cup qualifier match against Brazil, Argentina thrashed their arch-rivals 4-1, with Enzo Fernández scoring the second goal. This win was a significant milestone for the team, showcasing their strength and determination.
**Coaching Staff and Sponsorships**
Inter Miami CF announced Javier Mascherano's coaching staff for the 2025 season, which includes assistant coaches Lucas Rodríguez Pagano and Leandro Stillitano, among others. The team has also partnered with XBO.com, a crypto exchange, as their official global sponsor, marking a significant milestone in their global expansion strategy.
**Upcoming Matches and Events**
Argentina is set to visit India in October 2025 to play an exhibition match, which is expected to be a thrilling encounter. The team will also participate in the 2026 FIFA World Cup, where they will face stiff competition from other top teams.
Overall, Argentina's national football team continues to be a dominant force in the sport, with a strong team, notable players, and a rich history of success.
orchestrator: France football team recent developments 2025
Search Agent: France's national football team has been making headlines in recent developments, particularly in 2025. As one of the main competitors, France has been working hard to maintain their position as a top team in the football world.
**Recent Performance and Rankings**
As of April 2025, France ranks 2nd in the FIFA Men's World Ranking, just behind Argentina. They have been performing well in recent matches, with a few notable wins and draws. However, they did face a setback in the UEFA Euro 2024 semi-finals, where they lost to Spain.
**Notable Players and Transfers**
Olivier Giroud, France's all-time leading scorer, has been making waves with his recent transfer to LAFC. He has been in top form, scoring crucial goals for his new team. Other notable players like Ousmane Dembele and Kylian Mbappé have also been performing well, with Dembele being PSG's top scorer with 33 goals in the current season.
**Coaching Staff and Contract Extensions**
Didier Deschamps, France's head coach, has confirmed that he will leave his contract after the 2026 World Cup. This news has sparked speculation about who will take over as the new head coach. Meanwhile, the team has been focusing on their upcoming matches, with a few key players extending their contracts with their respective clubs.
**Upcoming Matches and Events**
France is set to participate in the 2026 FIFA World Cup, where they will face stiff competition from other top teams. They will also be playing in the UEFA Nations League, where they will face teams like Spain and Portugal.
Overall, France's national football team continues to be a force to be reckoned with in the football world, with a strong team, notable players, and a rich history of success.
Next Steps¶
- Expand Memory Modules: Explore other memory modules or create custom ones to fit specific use cases.
- Integrate Additional Agents: Incorporate more utility agents to handle diverse tasks and queries.
- Enhance Personalization: Collect and utilize more user-specific data (with appropriate consent) to further personalize interactions.