docs: document memory backend fallback behavior (PR #2190 in PraisonAI)

[MervinPraison]

Trigger

Upstream PR merged: MervinPraison/PraisonAI#2190 — "fix: memory search/store schema mismatch after backend fallback to SQLite" (fixes #2189).

Decision

Content update — no new page needed. Update docs/features/advanced-memory.mdx to document the memory backend fallback behavior that this PR makes reliable. The existing docs/concepts/memory.mdx is HUMAN-ONLY per AGENTS.md rule 1.8 and must NOT be edited by AI agents.

Why this needs documentation

The PR is technically a bug fix, but it stabilizes a user-visible behavior that is currently undocumented:

• When users configure MemoryConfig(backend="redis") (or any non-default backend) and the dependency is unavailable, PraisonAI silently falls back to SqliteMemoryAdapter.
• Before this fix, that fallback path raised sqlite3.OperationalError: no such table: short_mem on the first search/store, because the adapter creates short_term_memory/long_term_memory tables while the legacy code paths queried short_mem/long_mem.
• After this fix, search_short_term(), search_long_term(), and store_long_term() correctly delegate to the active adapter when provider in ("sqlite", "in_memory").

Users hitting this scenario today (Redis not installed, MongoDB unreachable, etc.) had no documented explanation for either the original error or the fallback that resolves it. The advanced-memory page already lists backend: "redis" as an option without describing what happens when it can't connect.

What to change

Target file

docs/features/advanced-memory.mdx

Section to add

Insert a new top-level section titled "Backend Fallback" between "Configuration Options" and "Quality Scoring System".

Content requirements (follow AGENTS.md style rules)

1. One-sentence intro. Example:

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

2. Hero Mermaid diagram using the standard color scheme. Suggested flow:

   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
   

   Loading

3. Behavior table. Document which providers go through the adapter and which keep dedicated write paths (extracted from PR diff):

   Configured backend	Fallback when unavailable	Search/store path
   redis	SQLite (adapter)	memory_adapter.search_* / store_*
   sqlite	n/a (native)	memory_adapter.* (delegates)
   in_memory	n/a (native)	memory_adapter.* (delegates)
   chromadb	dedicated write path retained	direct Chroma calls
   mem0	dedicated write path retained	direct Mem0 client
   mongodb	dedicated write path retained	direct Mongo client

4. Agent-centric quick example (top of the section per AGENTS.md principle 9):

   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")

5. What changed in v(release containing #2190) callout using <Note>:

   Before this release, configuring backend="redis" without redis-py installed produced sqlite3.OperationalError: no such table: short_mem on the first memory call. The adapter now owns the schema for sqlite and in_memory providers, so fallback is transparent.

6. Add a Troubleshooting accordion (or extend the existing Best Practices block) covering:

   • Symptom: no such table: short_mem or no such table: long_mem
   • Cause: pre-fix version with non-default backend that silently fell back to SQLite
   • Fix: upgrade to the release containing PR #2190 (or install the configured backend's dependency)

What NOT to do

• ❌ Do not modify docs/concepts/memory.mdx — AGENTS.md rule 1.8 marks docs/concepts/ as HUMAN-ONLY.
• ❌ Do not create a new top-level page — the fallback is a sub-behavior of advanced memory, not a standalone feature.
• ❌ Do not document internals like _get_stm_conn, short_mem table, or the legacy fallback path that the adapter call now bypasses. User-facing only.
• ❌ Do not invent backends. The PR only touches sqlite/in_memory adapter delegation; other providers (chroma, mem0, mongodb) keep their existing dedicated write paths.

SDK ground truth (read before writing)

Per AGENTS.md rule 1.2 ("SDK-First Documentation Cycle"), read these files before writing the docs:

• src/praisonai-agents/praisonaiagents/memory/memory.py — search_short_term, search_long_term, store_long_term (the methods modified in PR #2190).
• src/praisonai-agents/praisonaiagents/memory/adapters/ — adapter base class and SqliteMemoryAdapter for table names and method signatures.
• src/praisonai-agents/praisonaiagents/config/feature_configs.py — MemoryConfig for the canonical backend enum.

Verify every parameter, type, and default against the source. Do not guess.

PR-level details for reference

• PR: fix: memory search/store schema mismatch after backend fallback to SQLite PraisonAI#2190
• Issue fixed: Memory search fails after backend fallback: short_mem vs short_term_memory schema mismatch PraisonAI#2189
• File changed: src/praisonai-agents/praisonaiagents/memory/memory.py (+94, -18)
• Methods modified:
  • Memory.search_short_term() — adapter delegation for sqlite/in_memory
  • Memory.search_long_term() — adapter delegation for sqlite/in_memory
  • Memory.store_long_term() — adapter-first storage path mirroring store_short_term()
• Tests: tests/unit/test_memory_system_fixes.py, tests/unit/test_memory_history_separation.py (41 passing).

Quality checklist for the implementing agent

Per AGENTS.md §9:

• All examples runnable with shown imports
• Mermaid diagram uses standard color scheme (#6366F1 config, #F59E0B decision, #10B981 storage, white text)
• No edits to docs/concepts/
• Branch is a feature branch, PR is draft, links back to this issue and to PraisonAI#2190
• One-sentence section intros, active voice, no forbidden phrases ("In this section…", "As you can see…", etc.)

[MervinPraison]

🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...

Claude will:

1. Classify this issue
2. Search codebase for root cause
3. Implement a minimal fix following AGENTS.md
4. Create a PR with the changes

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-820-20260623-1201 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-820-20260623-1201?quick_pull=1&title=Issue%20%23820%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23820%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Documentation Update: Memory Backend Fallback

• Set up git identity
• Read AGENTS.md for style guidelines
• Read SDK source files (memory.py, adapters/, feature_configs.py)
• Read existing docs/features/advanced-memory.mdx
• Insert "Backend Fallback" section between "Configuration Options" and "Quality Scoring System"
• Commit and push changes
• Create PR

Done. Added a Backend Fallback section to docs/features/advanced-memory.mdx with:

• Runnable code example showing Redis fallback to SQLite
• Mermaid flow diagram (standard color scheme)
• Behavior table for all MemoryBackend values (sourced from feature_configs.py and memory.py)
• <Note> callout referencing the fix in PR #2190
• Troubleshooting accordion for sqlite3.OperationalError: no such table: short_mem

PR: #822

--- | Branch: claude/issue-820-20260623-1201