> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/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.

```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,
)

agent.start("Remember that I prefer concise answers.")
```

The user enables memory and hits a provider error; this guide maps common failures to fixes.

```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/dakera| 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>

***

## Why is `memory="mem0"` returning empty search results? (MongoDB vector store)

Search results come back empty because mem0's MongoDB vector store has an upstream signature-mismatch bug.

**Symptom:** Searches return `[]`, and the logs contain `Detected mem0 MongoDB vector store compatibility issue.` (before this was surfaced, the adapter path returned empty results with no log at all).

**Cause:** mem0's MongoDB vector store raises `TypeError: unexpected keyword argument 'vectors'` on `.search()` ([mem0ai/mem0#3185](https://github.com/mem0ai/mem0/issues/3185)); PraisonAI catches that specific `TypeError`, logs a warning, and returns `[]` so the agent keeps running. PraisonAI does not fix the upstream bug — the fix lives in mem0.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Mem0 as mem0.search()

    User->>Agent: search query
    Agent->>Mem0: search(**params)
    alt MongoDB vector store bug
        Mem0-->>Agent: TypeError (unexpected keyword 'vectors')
        Note over Agent: warning logged, [] returned
        Agent-->>User: empty results (agent keeps running)
    else Qdrant / Chroma backend
        Mem0-->>Agent: matching memories
        Agent-->>User: results
    end
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[👤 Agent] --> M[🧠 mem0 search]
    M -->|TypeError caught| W[⚠️ Warning logged → returns empty]
    M -->|Qdrant / Chroma backend| S[✅ Results returned]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef mem0 fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff

    class A agent
    class M mem0
    class W warn
    class S ok
```

### Fix: switch mem0's vector store to Qdrant or Chroma

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

    agent = Agent(
        name="Assistant",
        memory={
            "provider": "mem0",
            "config": {
                "vector_store": {
                    "provider": "qdrant",
                    "config": {"host": "localhost", "port": 6333},
                },
            },
        },
    )
    ```
  </Tab>

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

    agent = Agent(
        name="Assistant",
        memory={
            "provider": "mem0",
            "config": {
                "vector_store": {
                    "provider": "chroma",
                    "config": {"collection_name": "praisonai", "path": "./chroma_db"},
                },
            },
        },
    )
    ```
  </Tab>
</Tabs>

### Alternative: use PraisonAI's built-in MongoDB adapter

If you need MongoDB itself, use PraisonAI's first-party [MongoDB Memory](/docs/features/mongodb-memory) adapter — it is a separate implementation, unrelated to mem0, and unaffected by this bug.

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

agent = Agent(
    name="Assistant",
    memory={
        "provider": "mongodb",
        "config": {
            "connection_string": "mongodb://localhost:27017/",
            "database": "praisonai",
        },
    },
)
```

See also the [Mem0 integration guide](/docs/tools/mem0).

***

## 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

***

## Dakera adapter not loading

<AccordionGroup>
  <Accordion title="Dakera adapter not loading">
    **Symptom:** `ImportError` when using `memory="dakera"` or `memory={"provider": "dakera", ...}`.

    **Install the extra:**

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

    Or equivalently:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install dakera
    ```

    The exact error message when the package is missing:

    ```
    dakera is required for the dakera adapter. Install with: pip install 'praisonaiagents[dakera]' (or: pip install dakera)
    ```

    **Explicit provider now raises immediately:** Using `provider="dakera"` raises this `ImportError` with the install hint instead of silently falling back to SQLite.

    **If the server is unreachable:** Ensure Dakera is running at the configured URL (default `http://localhost:3000`). See [`dakera-ai/dakera-deploy`](https://github.com/dakera-ai/dakera-deploy) for Docker Compose setup.
  </Accordion>
</AccordionGroup>

***

## SQLite memory: errors after upgrade

### ValueError: Invalid table name

<Warning>
  **Symptom:** `ValueError: Invalid table name: … Allowed tables: long_term, short_term`

  **Cause:** Custom code called an internal SQLite helper with a table name other than `short_term` or `long_term`.

  **Fix:** Use the public API — `search_short_term()` and `search_long_term()` — instead of private `_search_sqlite*` methods.
</Warning>

### AttributeError: missing connection helper

<Warning>
  **Symptom:** `AttributeError: … has no attribute '_get_stm_conn'` (or `_get_ltm_conn'`)

  **Cause:** Previously this returned an empty list silently; it now surfaces. The memory object lacks the SQLite connection mixin.

  **Fix:** Use `Memory(provider="sqlite", …)` rather than instantiating mixins directly. Subclasses must implement `_get_stm_conn` and `_get_ltm_conn`.
</Warning>

***

## Dakera Adapter Not Loading

<AccordionGroup>
  <Accordion title="Dakera adapter not loading: ImportError">
    **Symptom:** Running with `provider="dakera"` raises:

    ```
    ImportError: dakera is required for the dakera adapter. Install with: pip install 'praisonaiagents[dakera]' (or: pip install dakera)
    ```

    **Fix:** Install the Dakera extra:

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

    This error surfaces because explicit `provider="dakera"` now raises a helpful hint instead of silently falling back to SQLite (fix landed in [PR #2591 follow-up commit `bbddfe3e`](https://github.com/MervinPraison/PraisonAI/commit/bbddfe3e6cdfd52be304379e03bfdfd974d63d2d)).
  </Accordion>
</AccordionGroup>

***

## 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="/docs/features/advanced-memory">
    Understanding different types of memory and storage options
  </Card>

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

  <Card title="Dakera Memory" icon="database" href="/docs/features/dakera-memory">
    Self-hosted, decay-weighted vector recall via the Dakera server.
  </Card>
</CardGroup>