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

# Memory Troubleshooting

> Common errors when configuring memory providers and how to fix them

Memory troubleshooting helps resolve common errors when configuring memory providers and debugging memory-related issues in PraisonAI agents.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Memory Provider Decision Tree"
        START[👤 User Request]
        EXPLICIT{Explicit Provider?}
        INSTALLED{Package Installed?}
        APIKEY{API Key Set?}
        WORKS[✅ Works]
        IMPORT[❌ ImportError]
        VALUE[❌ ValueError]
        FALLBACK[🔄 Fallback to Default]
    end
    
    START --> EXPLICIT
    EXPLICIT -->|Yes mem0/chroma| INSTALLED
    EXPLICIT -->|No/default| FALLBACK
    INSTALLED -->|No| IMPORT
    INSTALLED -->|Yes| APIKEY
    APIKEY -->|No| VALUE
    APIKEY -->|Yes| WORKS
    
    classDef start fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef decision fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef error fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef fallback fill:#6366F1,stroke:#7C90A0,color:#fff
    
    class START start
    class EXPLICIT,INSTALLED,APIKEY decision
    class WORKS success
    class IMPORT,VALUE error
    class FALLBACK fallback
```

## Quick Start

<Steps>
  <Step title="Default (No Extras) — Works Out of the Box">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Assistant",
        instructions="Help the user remember things",
        memory=True  # Uses built-in file storage
    )
    ```
  </Step>

  <Step title="Switch to Real Provider — Install Extras First">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install "praisonaiagents[memory]"
    ```

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Assistant",
        instructions="Help the user remember things",
        memory="mem0"  # Now uses Mem0 cloud service
    )
    ```
  </Step>
</Steps>

***

## Why am I seeing `ImportError: mem0ai is not installed...`?

This error occurs when you explicitly request a memory provider that requires optional dependencies. The new behavior ensures you get clear feedback instead of silent fallbacks.

### The Problem

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# This will fail if mem0ai package is not installed
agent = Agent(memory="mem0")
```

### The Solution

Install the required extras package:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonaiagents[memory]"
```

### Explicit vs Default Behavior

| Configuration           | mem0ai installed? | Result                                                                               |
| ----------------------- | ----------------- | ------------------------------------------------------------------------------------ |
| `memory=True` (default) | ❌                 | ✅ Falls back to file storage                                                         |
| `memory="mem0"`         | ❌                 | ❌ `ImportError: mem0ai is not installed. Run: pip install 'praisonaiagents[memory]'` |
| `memory="mem0"`         | ✅                 | ✅ Uses Mem0 (if API key set)                                                         |

***

## Why am I seeing `ValueError: Mem0 API Key not provided`?

This occurs when the mem0ai package is installed but the API key is missing.

### Set the API Key

<Tabs>
  <Tab title="Environment Variable">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export MEM0_API_KEY="your-mem0-api-key"
    ```
  </Tab>

  <Tab title="Direct Configuration">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Assistant", 
        memory={
            "provider": "mem0",
            "config": {
                "api_key": "your-mem0-api-key"
            }
        }
    )
    ```
  </Tab>
</Tabs>

***

## Common Error Scenarios

### User Interaction Flow

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant PraisonAI
    participant Mem0
    
    User->>Agent: Agent(memory="mem0")
    Agent->>PraisonAI: Initialize memory
    
    alt Package Missing
        PraisonAI-->>Agent: ImportError: mem0ai is not installed...
        Agent-->>User: Error with install command
    else Package Installed
        alt API Key Missing
            PraisonAI->>Mem0: Connect
            Mem0-->>PraisonAI: ValueError: API Key not provided
            PraisonAI-->>Agent: ValueError
            Agent-->>User: Set MEM0_API_KEY
        else API Key Set
            PraisonAI->>Mem0: ✅ Connect successfully
            Mem0-->>PraisonAI: Connected
            PraisonAI-->>Agent: Memory ready
            Agent-->>User: ✅ Works
        end
    end
```

### Step-by-Step Resolution

1. **User runs** `Agent(memory="mem0")` without extras
2. **PraisonAI raises** `ImportError: mem0ai is not installed. Run: pip install 'praisonaiagents[memory]'`
3. **User runs** the suggested install command
4. **User re-runs** the agent code — either works or shows next error (missing API key)
5. **User sets** `MEM0_API_KEY` environment variable
6. **Agent works** successfully

***

## Best Practices

<AccordionGroup>
  <Accordion title="Start with the default, upgrade later">
    Begin with `memory=True` for prototyping, then switch to `memory="mem0"` for production when you need advanced features.
  </Accordion>

  <Accordion title="Pin extras in your project">
    Add `"praisonaiagents[memory]"` to your requirements.txt or pyproject.toml to ensure consistent environments.
  </Accordion>

  <Accordion title="Set keys via environment variables in production">
    Use `MEM0_API_KEY` environment variables rather than hardcoding API keys in your source code.
  </Accordion>

  <Accordion title="Use memory=True for prototypes">
    The default file-based memory works great for development and doesn't require any external dependencies or API keys.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Memory Concepts" icon="brain" href="/concepts/memory">
    Understanding different types of memory and storage options
  </Card>

  <Card title="Advanced Memory" icon="gear" href="/features/advanced-memory">
    Multi-tiered memory with quality scoring and graph support
  </Card>
</CardGroup>