> ## 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 ```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 ) ``` ```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 ) ``` *** ## 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} export MEM0_API_KEY="your-mem0-api-key" ``` ```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" } } ) ``` *** ## Why am I seeing `TypeError: MemoryConfig.db must be a DbAdapter instance`? This error fires at agent construction when `memory={"db": ...}` (or `MemoryConfig(db=...)`) receives something that isn't a real database adapter — most commonly a bare file-path string. ### The Problem ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents import Agent # ❌ Was silently broken before PR #5679 — now raises TypeError at construct agent = Agent(memory={"db": "/tmp/sessions.db"}) # TypeError: MemoryConfig.db must be a DbAdapter instance (e.g. db(...) / # db.SQLiteDB(path=...)) implementing the on_agent_start/on_user_message/ # on_agent_message hooks, not str. For a SQLite file use # db(database_url="sqlite:///path/to.db") or # MemoryConfig(backend="sqlite", config={"short_db": "short.db", "long_db": "long.db"}). ``` Earlier releases accepted the string, warned on each hook call (`'str' object has no attribute 'on_agent_start'`), and silently dropped every message — memory looked enabled while no turns were ever stored. Fix landed in [PR #5679](https://github.com/MervinPraison/PraisonAI/pull/5679) (fixes [#5668](https://github.com/MervinPraison/PraisonAI/issues/5668)). ### Behavior change at a glance | Input | Before PR #5679 | After PR #5679 | | - | - | - | | `memory={"db": "/path/x.db"}` | Warning + silent persist loss | `TypeError` at construct | | `memory=MemoryConfig(db="/path/x.db")` | Warning + silent persist loss | `TypeError` at construct | | `memory=MemoryConfig(db="")` | Warning + silent persist loss | `TypeError` at construct | | `memory=MemoryConfig(db=123)` | Warning + silent persist loss | `TypeError` at construct | | `memory=MemoryConfig(db=db(database_url="…"))` | Works | Works (unchanged) | | `memory=MemoryConfig(db=None)` *(default)* | Works | Works (unchanged) | ### The Fix Pick one of the two supported shapes depending on how you want to point to a SQLite file (or any backing store): Use the `db` factory for URL-based stores. Works for `sqlite`, `postgresql`, and more. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents import Agent, MemoryConfig, db agent = Agent( name="Assistant", instructions="You are a helpful assistant.", memory=MemoryConfig(db=db(database_url="sqlite:///tmp/sessions.db")), ) agent.start("Remember my favourite colour is teal.") ``` Use `backend="sqlite"` and put file paths inside `config={}`. The `config` dict is the correct home for path strings — `db=` is for adapter instances only. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents import Agent, MemoryConfig agent = Agent( name="Assistant", instructions="You are a helpful assistant.", memory=MemoryConfig( backend="sqlite", config={"short_db": "./mem/short.db", "long_db": "./mem/long.db"}, ), ) agent.start("Remember my favourite colour is teal.") ``` ### Interaction flow ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} sequenceDiagram participant User participant Agent participant Cfg as MemoryConfig participant Mix as memory_mixin User->>Agent: Agent(memory={"db": "/path/x.db"}) Agent->>Cfg: resolve dict → MemoryConfig(**value) Note over Cfg: __post_init__ validates db Cfg-->>Agent: TypeError (clear message + fix hint) Agent-->>User: Fails fast at construct — no LLM turn billed, no silent data loss ``` ### Why the hook check, not just a type check? The memory bridge drives `db` through three hooks: `on_agent_start`, `on_user_message`, `on_agent_message`. A valid `db` is either a `DbAdapter` or a `db(...)` backend instance — both expose these hooks. The guard requires the hooks themselves (callable), not a weaker signal like `database_url` that a half-built object could expose while still dropping every message. See also [Database Persistence](/docs/features/database-persistence) and [Session Persistence](/docs/features/session-persistence) for custom `DbAdapter` implementations. *** ## 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. Both the memory-layer and the knowledge-layer mem0 search paths now delegate to the same `safe_mem0_search` helper in `praisonaiagents.memory.adapters.factories`, so this fallback behaviour is identical whether you configured mem0 via `memory=` or via `knowledge=`. Fix reference: [PraisonAI PR #5204](https://github.com/MervinPraison/PraisonAI/pull/5204). ```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 ```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}, }, }, }, ) ``` ```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"}, }, }, }, ) ``` ### 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). *** ## My `mem0` / `mongodb` config isn't being used — retrieval feels like keyword search On releases before 2026-07-14, `Knowledge(config=...)` could silently degrade a configured `mem0` or `mongodb` backend to SQLite because the adapter constructor rejected an internal `verbose` keyword ([PR #2982](https://github.com/MervinPraison/PraisonAI/pull/2982)). Check which adapter you actually got: ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents import Knowledge kb = Knowledge(config={ "vector_store": { "provider": "mem0", "config": {"collection_name": "my_docs"}, } }) print(type(kb.memory).__name__) # 'Mem0Adapter' on the fix; 'SQLiteKnowledgeAdapter' means you're on a buggy release. ``` If it isn't `Mem0Adapter` / `MongoDBKnowledgeAdapter`, upgrade to a release built after commit `69d7ecf`. On the fixed release, an explicit provider that fails to construct emits a `WARNING` naming the provider and the reason: ``` Knowledge provider '' failed to initialize (); falling back to a different backend. Retrieval quality may be reduced. ``` See [Knowledge Backends → Troubleshooting: silent SQLite fallback](/docs/features/knowledge-backends#troubleshooting-silent-sqlite-fallback) for the full walkthrough. *** ## Memory silently returned empty context On releases **before PR #4213**, `Agent(memory=True)` retrieved memory hits but only included them in the task prompt when the root logger was at `DEBUG`. Under normal `WARNING`/`INFO` logging the retrieved context was logged and then discarded, so nothing reached the LLM. **Old workaround (no longer needed):** enabling `verbose=5` / DEBUG logging, or calling `agent.memory.build_context_for_task(..., include_in_output=True)` by hand. **Now:** retrieval reaches the prompt by default — `build_context_for_task()` defaults `include_in_output=True`, and `agent.memory.get_context(query=...)` returns the prompt-ready string for the non-prompt-caching path. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents import Agent agent = Agent(name="Assistant", instructions="Help the user.", memory=True) agent.memory.remember("User prefers metric units.") # Reaches the prompt under normal logging — no DEBUG required print(agent.memory.get_context(query="What units do I prefer?")) ``` An empty or whitespace-only `query` to `get_context()` returns `""` on purpose — this avoids a `LIKE "%%"` scan that would leak unrelated (and possibly other users') records into the prompt. *** ## My second Agent instance doesn't recall what the first one said (auto\_memory + prefetch + user\_id) A new `Agent` with the same `user_id` and `prefetch=True` answers as if a fact stored by an earlier instance was never saved — no errors, no warnings. **Symptom:** `Agent A` stores a fact via `auto_memory=True` and a shared `user_id`; a new `Agent B` with the same `user_id` and `prefetch=True` answers as if the fact were never stored. **Cause:** Fixed by [PR #5688](https://github.com/MervinPraison/PraisonAI/pull/5688). On earlier releases, auto-memory wrote only to short-term memory with no `user_id` in record metadata, and turn-start prefetch queries long-term with a `metadata.user_id` post-filter — so every persisted row was silently dropped on recall. **Fix:** upgrade to a build containing [PR #5688](https://github.com/MervinPraison/PraisonAI/pull/5688) (merged into `main` 2026-10-07, head `9f1c205f`). On the fix, `auto_memory=True` persists each turn to long-term memory stamped with the configured `user_id` / `session_id`, so the prefetch scope filter matches. **Verify recall works end to end:** ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents import Agent, MemoryConfig shared = dict(backend="sqlite", user_id="alice", auto_memory=True) Agent( name="writer", instructions="You help the user.", memory=MemoryConfig(**shared), ).start("Remember codename ORANGE-PANDA for me.") reader = Agent( name="reader", instructions="Answer using recalled context.", memory=MemoryConfig(**shared, prefetch=True), ) answer = reader.start("What's my codename?") assert "ORANGE-PANDA" in answer # recalled block is non-empty on the fix ``` Isolation holds: a different `user_id` does **not** recall another user's turn. See [Memory Prefetch → Automatic cross-instance recall](/docs/features/memory-prefetch) and [Memory → Always set user\_id](/docs/features/memory#best-practices). *** ## My AutoMemory preview blocked a later store (`store=False` then `store=True` wrote nothing) A `process_interaction(..., store=False)` preview marked the interaction as processed, so a follow-up `store=True` for the same text returned `[]` and persisted nothing. **Symptom:** `auto.process_interaction(text, store=False)` returns extracted memories; a follow-up `auto.process_interaction(text, store=True)` returns `[]` and nothing is persisted in `FileMemory`. **Cause:** Fixed by [PR #5689](https://github.com/MervinPraison/PraisonAI/pull/5689). On earlier releases, `process_interaction` recorded the interaction hash **before** calling `_store_memories`, so a `store=False` preview marked the text as already processed and blocked the real store. The same bug left the hash consumed after a failed store, preventing retry once the backend recovered. **Fix:** upgrade to a build containing [PR #5689](https://github.com/MervinPraison/PraisonAI/pull/5689) (merged into `main` 2026-10-08, head `1cebaa0e`). On the fix, a preview never consumes dedup and the hash is recorded only after a successful write. **Verify the preview no longer blocks a real store:** ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents.memory import FileMemory, AutoMemory base = FileMemory(user_id="user123") auto = AutoMemory(base, enabled=True) auto.process_interaction("I prefer concise answers.", store=False) stored = auto.process_interaction("I prefer concise answers.", store=True) assert stored, "preview should not block a later real store on PR #5689" ``` **Related symptom:** a retry after a transient backend outage stores nothing. Same root cause, same fix — see [Previews and retry semantics](/docs/features/advanced-memory#previews-and-retry-semantics). ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} sequenceDiagram participant U as 👤 Caller participant A as 🔍 AutoMemory participant M as 💾 FileMemory U->>A: process_interaction(text, store=False) A->>A: extract (hash NOT recorded) A-->>U: memories U->>A: process_interaction(text, store=True) A->>M: store memories M-->>A: ok (hash recorded) A-->>U: memories U->>A: process_interaction(text, store=True) A->>M: ✗ backend down Note over A: hash stays un-consumed U->>A: retry process_interaction(text, store=True) A->>M: store memories (resumes) M-->>A: ok A-->>U: memories rect rgba(139,0,0,0.08) Note over A,M: Before #5689: preview/failure consumed the hash → [] forever end ``` *** ## Why did my metadata dict come back as a string? (or: my `None` values disappeared) The `chroma` / `rag` (default) memory backend only accepts primitive metadata values, so non-primitives are coerced to `str(...)` and `None` values are dropped. **Cause:** ChromaDB rejects non-primitive metadata (`str`, `int`, `float`, `bool` only). PraisonAI coerces `dict` / `list` / other types to `str(...)`, and drops `None` values, so the ChromaDB write never fails. **Fix (if you need round-trippable structured metadata):** serialise it yourself with `json.dumps(...)` into a `str` field, or switch to a metadata-native backend like `mongodb`, `mem0`, or `dakera`. ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import json from praisonaiagents import Memory memory = Memory(config={"provider": "rag"}) # Instead of a raw dict/list (which gets stringified), store JSON in a str field memory.store_long_term( text="Project atlas kicked off", metadata={"tags_json": json.dumps(["backend", "urgent"])}, # round-trips cleanly ) ``` See [Metadata types (ChromaDB / RAG backend)](/docs/features/advanced-memory#metadata-types-chromadb-rag-backend) for the full coercion table. *** ## 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 **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. *** ## SQLite memory: errors after upgrade ### ValueError: Invalid table name **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. ### AttributeError: missing connection helper **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`. *** ## Dakera Adapter Not Loading **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)). *** ## My other agent's memory disappeared when I called `reset_long_term()` Older builds reset long-term memory by wiping **every** collection in the shared Chroma persistent directory, so calling `reset_long_term()` on one agent also erased sibling agents that shared the same path. `reset_long_term()` now deletes only this instance's own collection and re-initializes it — other agents sharing the same `rag_db_path` keep their data. A failed reset also raises now instead of silently reporting success. Give each agent a distinct `collection_name` when they share a persistent path so resets stay isolated: ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} from praisonaiagents import Agent agent = Agent( name="Researcher", memory={ "provider": "rag", "rag_db_path": "./chroma_db", "collection_name": "researcher_ltm", # default is "memory_store" }, ) ``` See [Memory Configuration → Chroma Collection Name](/docs/docs/configuration/memory-config#chroma-collection-name). *** ## Best Practices Begin with `memory=True` for prototyping, then switch to `memory="mem0"` for production when you need advanced features. Add `"praisonaiagents[memory]"` to your requirements.txt or pyproject.toml to ensure consistent environments. Use `MEM0_API_KEY` environment variables rather than hardcoding API keys in your source code. The default file-based memory works great for development and doesn't require any external dependencies or API keys. *** ## Related Understanding different types of memory and storage options Multi-tiered memory with quality scoring and graph support Self-hosted, decay-weighted vector recall via the Dakera server. Merge, promote, and prune memories under a loss-bounded guard. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.