Database Architecture
Claude-Mem uses SQLite 3 with the better-sqlite3 native module for persistent storage and FTS5 for full-text search.Database Location
- Current:
~/.claude-mem/claude-mem.db
${CLAUDE_PLUGIN_ROOT}/data/, the actual implementation still uses ~/.claude-mem/.
Database Implementation
Primary Implementation: better-sqlite3 (native SQLite module)- Used by: SessionStore and SessionSearch
- Format: Synchronous API with better performance
- Note: Database.ts (using bun:sqlite) is legacy code
Core Tables
1. sdk_sessions
Tracks active and completed sessions.idx_sdk_sessions_claude_sessiononclaude_session_ididx_sdk_sessions_projectonprojectidx_sdk_sessions_statusonstatusidx_sdk_sessions_created_atoncreated_at_epoch DESC
2. observations
Individual tool executions with hierarchical structure.decision- Architectural or design decisionsbugfix- Bug fixes and correctionsfeature- New features or capabilitiesrefactor- Code refactoring and cleanupdiscovery- Learnings about the codebasechange- General changes and modifications
idx_observations_sessiononsession_ididx_observations_sdk_sessiononsdk_session_ididx_observations_projectonprojectidx_observations_tool_nameontool_nameidx_observations_created_atoncreated_at_epoch DESCidx_observations_typeontype
3. session_summaries
AI-generated session summaries (multiple per session).idx_session_summaries_sdk_sessiononsdk_session_ididx_session_summaries_projectonprojectidx_session_summaries_created_atoncreated_at_epoch DESC
4. user_prompts
Raw user prompts with FTS5 search (as of v4.2.0).idx_user_prompts_sdk_sessiononsdk_session_ididx_user_prompts_projectonprojectidx_user_prompts_created_atoncreated_at_epoch DESC
Legacy Tables
- sessions: Legacy session tracking (v3.x)
- memories: Legacy compressed memory chunks (v3.x)
- overviews: Legacy session summaries (v3.x)
FTS5 Full-Text Search
SQLite FTS5 (Full-Text Search) virtual tables enable fast full-text search across observations, summaries, and user prompts.FTS5 Virtual Tables
observations_fts
session_summaries_fts
user_prompts_fts
Automatic Synchronization
FTS5 tables stay in sync via triggers:FTS5 Query Syntax
FTS5 supports rich query syntax:- Simple:
"error handling" - AND:
"error" AND "handling" - OR:
"bug" OR "fix" - NOT:
"bug" NOT "feature" - Phrase:
"'exact phrase'" - Column:
title:"authentication"
Security
As of v4.2.3, all FTS5 queries are properly escaped to prevent SQL injection:- Double quotes are escaped:
query.replace(/"/g, '""') - Comprehensive test suite with 332 injection attack tests
Database Classes
SessionStore
CRUD operations for sessions, observations, summaries, and user prompts. Location:src/services/sqlite/SessionStore.ts
Methods:
createSession()getSession()updateSession()createObservation()getObservations()createSummary()getSummaries()createUserPrompt()
SessionSearch
FTS5 full-text search with 8 specialized search methods. Location:src/services/sqlite/SessionSearch.ts
Methods:
searchObservations()- Full-text search across observationssearchSessions()- Full-text search across summariessearchUserPrompts()- Full-text search across user promptsfindByConcept()- Find by concept tagsfindByFile()- Find by file referencesfindByType()- Find by observation typegetRecentContext()- Get recent session contextadvancedSearch()- Combined filters
Migrations
Database schema is managed via migrations insrc/services/sqlite/migrations.ts.
Migration History:
- Migration 001: Initial schema (sessions, memories, overviews, diagnostics, transcript_events)
- Migration 002: Hierarchical memory fields (title, subtitle, facts, concepts, files_touched)
- Migration 003: SDK sessions and observations
- Migration 004: Session summaries
- Migration 005: Multi-prompt sessions (prompt_counter, prompt_number)
- Migration 006: FTS5 virtual tables and triggers
- Migration 007-010: Various improvements and user prompts table
Performance Considerations
- Indexes: All foreign keys and frequently queried columns are indexed
- FTS5: Full-text search is significantly faster than LIKE queries
- Triggers: Automatic synchronization has minimal overhead
- Connection Pooling: better-sqlite3 reuses connections efficiently
- Synchronous API: better-sqlite3 uses synchronous API for better performance

