​
What is Memory?

Memory enables your agent to recall past interactions and use them to inform future responses. In Galadriel, memory is implemented through the MemoryStore class, which provides both short-term and long-term memory capabilities.
  • Short-term memory: Stores recent conversations in a simple list structure (enabled by default).
  • Long-term memory: Uses vector embeddings to store and retrieve relevant past interactions based on semantic similarity (optional).

​
How Memory Works

When a user interacts with an agent:
  1. The conversation is stored in short-term memory.
  2. If short-term memory exceeds its limit (default: 20 interactions), the oldest memory is moved to long-term storage (if enabled).
  3. When responding to a new query, the agent can access:
    • All recent conversations from short-term memory
    • Semantically relevant past interactions from long-term memory
This approach ensures your agent maintains context in ongoing conversations while also being able to recall relevant information from past interactions.

​
Adding Memory to Your Agent

​
Prerequisites

Make sure you’ve gone through the quick start guide and have the development environment set up.

​
Basic Usage (Short-Term Memory Only)

Short-term memory is enabled by default when using the AgentRuntime: 
from galadriel import AgentRuntime, CodeAgent
from galadriel.core_agent import LiteLLMModel

model = LiteLLMModel(model_id="gpt-4o", api_key="<YOUR_OPENAI_API_KEY>")
agent = CodeAgent(model=model)

# Memory is automatically enabled with short-term capabilities
runtime = AgentRuntime(
    agent=agent,
    inputs=[client],
    outputs=[client],
)

​
Enabling Long-Term Memory

To enable long-term memory, explicitly create a MemoryStore with OpenAI API credentials and an embedding model: 
import os
from galadriel import AgentRuntime, CodeAgent, MemoryStore
from galadriel.core_agent import LiteLLMModel

model = LiteLLMModel(model_id="gpt-4o", api_key="<YOUR_OPENAI_API_KEY>")
agent = CodeAgent(model=model)

# Create memory store with long-term capabilities
memory_store = MemoryStore(
    api_key=os.getenv("OPENAI_API_KEY"),
    embedding_model="text-embedding-3-large",
    agent_name="customer_support_agent",
)

runtime = AgentRuntime(
    agent=agent,
    inputs=[client],
    outputs=[client],
    memory_store=memory_store,
)

​
How Memory Appears in Prompts

When your agent receives a query, memory is automatically integrated into its prompt. Here’s an example: 
You are a helpful chatbot assistant.
Here is the chat history:

recent messages:
[2025-03-12 09:20]
 User: hello
 Assistant: Hello! How can I help you today?
[2025-03-12 09:20]
 User: how's the weather like in Porto, Portugal
 Assistant: Currently, the weather in Porto, Portugal is around 22.71°C (72.88°F) with a southwest wind at 14.51 km/h and 76% humidity. There is a 0% chance of rain.
[2025-03-12 09:21]
 User: that sounds great for March, could you verify again?
 Assistant: I apologize for the confusion earlier. Upon verifying, the typical weather in Porto for March 2025 shows temperatures ranging from 9°C to 17°C, and there might be several rainy days. It seems the previous information might not have been accurate. Thank you for your patience!

Answer the following question:

 thank you

Please remember the chat history and use it to answer the question, if relevant to the question.
If long-term memory is enabled, semantically relevant past interactions will also be included under a “long term memories that might be relevant” section.

​
Advanced Memory Features

​
Saving and Loading Memory

For persistent agents, you can save memory to disk and load it later: 
# Save memory to disk
memory_store.save_data_locally("./agent_memory")

# Load memory from disk
memory_store = MemoryStore(
    api_key=os.getenv("OPENAI_API_KEY"),
    embedding_model="text-embedding-3-large",
)
memory_store.load_memory_from_folder("./agent_memory")

​
Customizing Memory Retrieval (Long-Term Memory Only)

When retrieving memories for a specific query, you can customize:
  1. The number of relevant memories to retrieve (top_k)
  2. Filter criteria for memory retrieval
# In a custom agent implementation
memories = await self.memory_store.get_memories(
    prompt="Tell me about crypto",
    top_k=5,  # Retrieve 5 most relevant memories
    filter={"conversation_id": "abc123"}  # Only from a specific conversation
)

​
Memory Configuration Options

The MemoryStore class accepts several parameters:
ParameterDescriptionDefault
short_term_memory_limitMaximum number of interactions in short-term memory20
api_keyOpenAI API key for embeddings (required for long-term memory)None
embedding_modelOpenAI embedding model to useNone
agent_nameIdentifier for the agent using this memory store”agent”

​
Adjusting Short-Term Memory Capacity

The short_term_memory_limit parameter controls how many recent interactions your agent remembers before moving older memories to long-term storage. You can adjust this based on your use case: 
# For agents that need more immediate context (e.g., complex conversations)
memory_store = MemoryStore(short_term_memory_limit=20)

# For agents that need less immediate context (e.g., simple Q&A)
memory_store = MemoryStore(short_term_memory_limit=10)
Increasing this limit allows your agent to maintain more context in active memory, which can be beneficial for complex, multi-turn conversations. However, it may also increase token usage in your LLM prompts. When short-term memory reaches its limit, the oldest memory is automatically moved to long-term storage (if long-term memory is enabled). If long-term memory is not enabled, the oldest memory is simply discarded.

​
Conclusion

Memory is a crucial component for building agents that maintain context and learn from past interactions. Galadriel’s memory system provides a flexible approach that balances recent context with long-term recall, enabling more natural and helpful agent responses.

​
See Next