> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galadriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

## 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](/galadriel-network/get-started/quickstart) and have the development environment set up.

### Basic Usage (Short-Term Memory Only)

Short-term memory is enabled by default when using the `AgentRuntime`:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
# 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

```python theme={null}
# 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:

| Parameter                 | Description                                                   | Default |
| ------------------------- | ------------------------------------------------------------- | ------- |
| `short_term_memory_limit` | Maximum number of interactions in short-term memory           | 20      |
| `api_key`                 | OpenAI API key for embeddings (required for long-term memory) | None    |
| `embedding_model`         | OpenAI embedding model to use                                 | None    |
| `agent_name`              | Identifier 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:

```python theme={null}
# 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

* [Tools](/galadriel-network/tutorials/tools)
* [Agents](/galadriel-network/tutorials/agents)
* [Runtime](/galadriel-network/concepts/runtime)