Skip to content

docs: document memory backend fallback behavior #822

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MervinPraison merged 1 commit into from
Jun 23, 2026
+58 −0
Merged

docs: document memory backend fallback behavior #822

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions docs/features/advanced-memory.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,64 @@ memory_config = {
}
```

## Backend Fallback

PraisonAI automatically falls back to SQLite when a configured backend (Redis, Valkey, Postgres) is unavailable, so your agent keeps working without crashing.

```python
from praisonaiagents import Agent, MemoryConfig

# Configure Redis — if redis-py isn't installed,
# PraisonAI falls back to SQLite automatically.
agent = Agent(
name="Assistant",
instructions="You remember user preferences.",
memory=MemoryConfig(backend="redis", user_id="user_123")
)

agent.start("Remember I prefer dark mode")
```

```mermaid
graph LR
Config[📋 MemoryConfig backend=redis] --> Try{🔍 Redis available?}
Try -->|Yes| Redis[(🗃️ Redis)]
Try -->|No| Adapter[💾 SqliteMemoryAdapter]
Adapter --> Tables[(short_term_memory<br/>long_term_memory)]

classDef config fill:#6366F1,stroke:#7C90A0,color:#fff
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef storage fill:#10B981,stroke:#7C90A0,color:#fff

class Config config
class Try decision
class Redis,Adapter,Tables storage
```

| Configured backend | Fallback when unavailable | Search/store path |
|---|---|---|
| `redis` | SQLite (adapter) | `memory_adapter.search_*` / `store_*` |
| `valkey` | SQLite (adapter) | `memory_adapter.search_*` / `store_*` |
| `postgres` | SQLite (adapter) | `memory_adapter.search_*` / `store_*` |
| `sqlite` | n/a (native) | `memory_adapter.*` (direct) |
| `file` | n/a (native) | FileMemory (direct) |
| `mem0` | raises `ImportError` | direct Mem0 client |
| `mongodb` | raises error | direct Mongo client |

@gemini-code-assist gemini-code-assist Bot Jun 23, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For consistency with the mem0 row, specify that mongodb also raises an ImportError when its dependencies are missing and it is unavailable.

Suggested change:

| `mongodb` | raises `ImportError` | direct Mongo client |


<Note>
Before the fix in PraisonAI PR #2190, configuring `backend="redis"` without `redis-py` installed produced `sqlite3.OperationalError: no such table: short_mem` on the first memory call. The SQLite adapter now owns the correct schema (`short_term_memory` / `long_term_memory`), so fallback is transparent.
</Note>

<AccordionGroup>
<Accordion title="Symptom: sqlite3.OperationalError: no such table: short_mem">
**Cause:** You are running a version of PraisonAI before PR #2190. A non-default backend (e.g. `redis`) was configured but its dependency was not installed, causing a silent fallback to SQLite — which then queried the legacy `short_mem` table that no longer exists.

**Fix:** Upgrade PraisonAI to the release that includes PR #2190, or install the dependency for your configured backend (e.g. `pip install redis` for Redis).
</Accordion>
</AccordionGroup>

---

## Quality Scoring System

### Quality Metrics
Expand Down