Memory Management in CrewAI

CrewAI’s memory system lets agents remember past interactions, results, and entities so they stop “starting from zero” every time. You can use a built‑in basic memory (recommended) or plug in external memory for advanced, cross‑app scenarios.

NOTE: you can also review my CrewAI Lightning Lesson on this topic here

1. Memory Components: What Gets Remembered?

CrewAI’s memory has four main components:

Short‑Term Memory

Stores recent interactions for the current run.
Implemented with ChromaDB + RAG (retrieval‑augmented generation).

Long‑Term Memory

Stores important task results across sessions in SQLite (long_term_memory_storage.db).
Lets agents gradually build a knowledge base over time.

Entity Memory

Tracks structured facts about entities (people, places, concepts) via RAG.
Helps with things like “Who is John?” or “What did we decide last meeting?”

Contextual Memory

Combines short‑term, long‑term, external, and entity memory.
Feeds coherent context into agents for multi‑step conversations/workflows.

You can think of it as:

short‑term = “what just happened”,
long‑term = “what we learned”,
entity = “who/what we know”,
contextual = “what’s relevant right now”.

2. Basic Memory System (Recommended)

For most use cases, you only need to flip one switch on the crew.

2.1 Enabling basic memory

# python
from crewai import Crew, Agent, Task, Process

crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,   # 🔑 enables short-term, long-term, entity memory
    verbose=True,
)

Once memory=True is set:

Short‑term, long‑term, and entity memory are wired automatically.
Memory is transparently read/written on each kickoff.

2.2 Where memory is stored

By default, memory and knowledge live in a platform‑specific folder:

macOS

~/Library/Application Support/CrewAI/{project_name}/
├── knowledge/
├── short_term_memory/
├── long_term_memory/
├── entities/
└── long_term_memory_storage.db

Linux

~/.local/share/CrewAI/{project_name}/
├── knowledge/
├── short_term_memory/
├── long_term_memory/
├── entities/
└── long_term_memory_storage.db

Windows

C:\Users\{username}\AppData\Local\CrewAI\{project_name}\
├── knowledge\
├── short_term_memory\
├── long_term_memory\
├── entities\
└── long_term_memory_storage.db

You can inspect the base path with:

from crewai.utilities.paths import db_storage_path
import os

storage_path = db_storage_path()
print("CrewAI storage location:", storage_path)

2.3 Custom storage directory

Use CREWAI_STORAGE_DIR to move all memory/knowledge into a project or mounted folder.

import os
from crewai import Crew

os.environ["CREWAI_STORAGE_DIR"] = "./my_project_storage"

crew = Crew(
    agents=[...],
    tasks=[...],
    memory=True,
)

Now everything will live under ./my_project_storage/ instead of the OS default.

3. Embedding Providers for Memory

Memory uses embeddings behind the scenes (vector representations of text).

Default: OpenAI (e.g., text-embedding-3-small).
You can switch to other providers for cost, privacy, or compatibility reasons.

3.1 Basic OpenAI config (default)

from crewai import Crew

crew = Crew(
    agents=[...],
    tasks=[...],
    memory=True,
    embedder={
        "provider": "openai",
        "config": {"model_name": "text-embedding-3-small"},
    },
)

3.2 Other providers (examples)

Ollama (local):

crew = Crew(
    memory=True,
    embedder={
        "provider": "ollama",
        "config": {"model": "mxbai-embed-large"},
    },
)

Google AI:

crew = Crew(
    memory=True,
    embedder={
        "provider": "google-generativeai",
        "config": {
            "api_key": "your-google-api-key",
            "model_name": "gemini-embedding-001",
        },
    },
)

Azure OpenAI:

crew = Crew(
    memory=True,
    embedder={
        "provider": "openai",
        "config": {
            "api_key": "your-azure-api-key",
            "api_base": "https://your-resource.openai.azure.com/",
            "api_version": "2023-05-15",
            "model_name": "text-embedding-3-small",
        },
    },
)

You can also use Cohere, VoyageAI, Vertex, Bedrock, Hugging Face, IBM, etc., using the same embedder pattern.

4. External Memory (Advanced)

External Memory is a separate component for using third‑party or custom memory backends (e.g., Mem0, Zep, your own DB).

Use it when you need:

User‑specific, cross‑application memory.
Centralized memory shared across multiple crews or services.
Custom storage (vector DB, graphs, or proprietary systems).

4.1 Basic external memory with Mem0

from crewai import Crew, Process
from crewai.memory.external.external_memory import ExternalMemory

external_memory = ExternalMemory(
    embedder_config={
        "provider": "mem0",
        "config": {
            "user_id": "john",
            "local_mem0_config": {
                "vector_store": {
                    "provider": "qdrant",
                    "config": {"host": "localhost", "port": 6333},
                },
                "llm": {
                    "provider": "openai",
                    "config": {"api_key": "your-api-key", "model": "gpt-4"},
                },
                "embedder": {
                    "provider": "openai",
                    "config": {
                        "api_key": "your-api-key",
                        "model": "text-embedding-3-small",
                    },
                },
            },
            "infer": True,  # optional
        },
    },
)

crew = Crew(
    agents=[...],
    tasks=[...],
    external_memory=external_memory,  # separate from basic memory
    process=Process.sequential,
    verbose=True,
)

Behavior:

CrewAI automatically retrieves context from external memory when a task starts.
It stores new outputs at the end of tasks, building persistent history.
Memory persists across runs and even across applications if you reuse the same external backend.

4.2 Custom external storage

You can implement your own storage class:

from crewai.memory.external.external_memory import ExternalMemory
from crewai.memory.storage.interface import Storage

class CustomStorage(Storage):
    def __init__(self):
        self.memories = []

    def save(self, value, metadata=None, agent=None):
        self.memories.append({"value": value, "metadata": metadata, "agent": agent})

    def search(self, query, limit=10, score_threshold=0.5):
        return [
            m for m in self.memories
            if query.lower() in str(m["value"]).lower()
        ]

    def reset(self):
        self.memories = []

external_memory = ExternalMemory(storage=CustomStorage())

crew = Crew(
    agents=[...],
    tasks=[...],
    external_memory=external_memory,
)

This is ideal when you already have a custom knowledge/notes system and just want CrewAI to plug into it.

5. Resetting and Debugging Memory

5.1 Resetting memory

Use reset_memories on the crew for targeted resets:

crew.reset_memories(command_type="short")     # short-term memory
crew.reset_memories(command_type="long")      # long-term memory
crew.reset_memories(command_type="entity")    # entity memory
crew.reset_memories(command_type="knowledge") # knowledge store

CLI equivalents:

crewai reset-memories --knowledge
# (and other flags for specific memory types)

5.2 Common storage issues and checks

Permission errors (ChromaDB permission denied): Fix with something like:

chmod -R 755 ~/.local/share/CrewAI/

Memory not persisting:
- Confirm CREWAI_STORAGE_DIR is constant across runs.
- Ensure memory=True is actually set.
Database locked:
- Make sure only one process writes to the same SQLite DB.

You can inspect storage and permissions using db_storage_path() and standard OS tools.

6. Memory vs Knowledge (Mental Model)

Here is simple way to think about memory:

Knowledge = pre‑loaded library of documents you curate (PDFs, CSVs, JSON, etc.).
Memory = experiences and outputs the system writes back over time (who said what, what worked, what failed).

Together they let agents:

Ground answers in both static reference material and past interactions.
Personalize behavior and decisions as they work on more tasks.

Guideline:

start with memory=True for most crews, then consider External Memory when they need cross‑project, user‑centric persistence or third‑party memory providers like Mem0 or Zep.

Memory Management in CrewAI

On this page