Troubleshooting

Common issues and their resolutions.

Installation Issues

SQLite Version Too Old

# Check version
sqlite3 --version

# Upgrade (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install sqlite3

# Or use conda
conda install -c conda-forge sqlite

FTS5 Not Available

# Verify FTS5
python -c "import sqlite3; conn = sqlite3.connect(':memory:'); conn.execute('CREATE VIRTUAL TABLE test USING fts5(content)')"

# If error, rebuild SQLite with FTS5

Runtime Issues

Database Locked

# Enable WAL mode for better concurrency
sqlite3 mnemosyne.db "PRAGMA journal_mode=WAL;"

# Or in Python
mem = Memory(wal_mode=True)

Slow Queries

Enable WAL mode (see above)
Reduce Working Memory size
Verify SSD storage
Run consolidation to evict stale entries: mem.sleep()

Memory Leaks

# Check memory stats
import psutil
process = psutil.Process()
print(f"RSS: {process.memory_info().rss / 1024 / 1024:.1f} MB")

Data Issues

Corrupted Database

# Check integrity
sqlite3 mnemosyne.db "PRAGMA integrity_check"

# If corrupted, restore from backup
cp mnemosyne-backup.db mnemosyne.db

# Or use disaster recovery
from mnemosyne.dr.recovery import restore_backup, verify_integrity
verify_integrity("mnemosyne.db")
restore_backup("mnemosyne-backup.db", "mnemosyne.db")

Missing Embeddings

# Rebuild vector index
mem.rebuild_vector_index()

# Check embedding provider status
print(mem.embedding_status())

Error Reference

Error	Cause	Fix
`DatabaseError: database is locked`	Concurrent access	Enable WAL mode
`EmbeddingError: rate limited`	OpenAI quota	Check API key, add rate limiting
`MemoryNotFoundError`	Wrong ID	Verify ID format
`ConfigurationError`	Bad env var	Check `MNEMOSYNE_*` variables