# Claude-Mem Codebase Map **Version**: 3.9.16 **Description**: Memory compression system for Claude Code - persist context across sessions --- ## Table of Contents 1. [Project Overview](#project-overview) 2. [Architecture Overview](#architecture-overview) 3. [Directory Structure](#directory-structure) 4. [Core Components](#core-components) 5. [Entry Points & CLI](#entry-points--cli) 6. [Commands](#commands) 7. [Hooks System](#hooks-system) 8. [SDK & Worker](#sdk--worker) 9. [Services](#services) 10. [Shared Components](#shared-components) 11. [Utilities](#utilities) 12. [Key Workflows](#key-workflows) --- ## Project Overview **claude-mem** is a sophisticated memory compression system designed to persist context across Claude Code sessions. It provides: - **Automatic memory capture** via Claude Code hooks (SessionStart, Stop, UserPromptSubmit, PostToolUse) - **SDK-powered intelligence** that extracts meaningful insights from tool observations - **Vector storage** using Chroma MCP for semantic search - **SQLite persistence** for structured data and session summaries - **Smart trash system** with file recovery capabilities - **Cross-platform support** (Windows, macOS, Linux) --- ## Architecture Overview ### High-Level Flow ``` User Works in Claude Code ↓ Hooks Trigger ↓ ┌────────────────────────────────────┐ │ SessionStart → context hook │ Shows recent memories │ UserPromptSubmit → new hook │ Spawns SDK worker │ PostToolUse → save hook │ Queues observations │ Stop → summary hook │ Finalizes session └────────────────────────────────────┘ ↓ SDK Worker Process (Background daemon) ↓ ┌──────────────────────┐ │ Claude Agent SDK │ Analyzes observations │ Streaming Session │ Extracts insights └──────────────────────┘ ↓ ┌─────────┬─────────┐ │ SQLite │ Chroma │ Persistent storage └─────────┴─────────┘ ↓ Next Session Start (Memories restored) ``` ### Key Components 1. **CLI Layer** (`src/bin/cli.ts`) - User-facing commands 2. **Hooks Layer** (`src/hooks/`) - Claude Code integration points 3. **SDK Layer** (`src/sdk/`) - Background intelligence worker 4. **Storage Layer** (`src/services/sqlite/`) - Data persistence 5. **Services Layer** (`src/services/`) - Path discovery, utilities --- ## Directory Structure ``` src/ ├── bin/ # CLI entry point │ └── cli.ts # Commander-based CLI router ├── commands/ # CLI command implementations │ ├── install.ts # Hook installation wizard │ ├── uninstall.ts # Hook removal │ ├── doctor.ts # Health checks │ ├── status.ts # System status │ ├── logs.ts # Log viewer │ ├── trash.ts # Move files to trash │ ├── trash-view.ts # View trash contents │ ├── trash-empty.ts # Empty trash │ └── restore.ts # Restore from trash ├── hooks/ # Claude Code hook handlers │ ├── index.ts # Hook exports │ ├── context.ts # SessionStart hook │ ├── new.ts # UserPromptSubmit hook │ ├── save.ts # PostToolUse hook │ └── summary.ts # Stop hook ├── sdk/ # Agent SDK integration │ ├── index.ts # SDK exports │ ├── worker.ts # Background worker process │ ├── prompts.ts # Prompt builders for SDK │ └── parser.ts # XML response parser ├── services/ # Core services │ └── sqlite/ # Database layer │ ├── index.ts # Database exports │ ├── Database.ts # SQLite manager with migrations │ ├── HooksDatabase.ts # Lightweight hooks interface │ ├── migrations.ts # Schema migrations │ └── types.ts # TypeScript interfaces ├── shared/ # Shared configuration │ ├── config.ts # Package metadata │ ├── paths.ts # Path configuration constants │ ├── storage.ts # Storage provider interface │ └── types.ts # Core type definitions └── utils/ # Utility functions └── platform.ts # Platform-specific helpers ``` --- ## Core Components ### Entry Points & CLI #### `src/bin/cli.ts` **Purpose**: Main CLI entry point using Commander.js **Key Responsibilities**: - Route CLI commands to handlers - Define command-line arguments and options - Handle stdin for hook commands - Export database utilities for programmatic use **Key Functions**: - `readStdin()`: Reads JSON input from stdin for hooks - Command definitions: - `install`: Install hooks wizard - `uninstall`: Remove hooks - `doctor`: Health check - `status`: System status - `logs`: View operation logs - `trash [files...]`: Move files to trash - `trash view`: View trash contents - `trash empty`: Empty trash - `restore`: Restore from trash - `context`: SessionStart hook (internal) - `new`: UserPromptSubmit hook (internal) - `save`: PostToolUse hook (internal) - `summary`: Stop hook (internal) - `worker `: SDK worker (internal) **Exports**: ```typescript export { DatabaseManager, migrations, initializeDatabase, getDatabase } ``` --- ## Commands ### `src/commands/install.ts` **Purpose**: Interactive installation wizard for claude-mem hooks **Key Functions**: - **`install(options)`**: Main installation flow - Creates directory structure - Installs uv package manager - Configures Claude Code hooks - Installs Chroma MCP server - Adds CLAUDE.md instructions - Optionally configures Smart Trash alias - **`runInstallationWizard(existingInstall)`**: Interactive prompts - Scope selection (user/project/local) - Hook timeout configuration - Smart Trash opt-in - Save-on-clear opt-in - **`ensureDirectoryStructure()`**: Creates all data directories - **`configureHooks(settingsPath)`**: Writes Claude settings.json - **`installChromaMcp(forceReinstall)`**: Installs Chroma MCP via `claude mcp add` - **`ensureClaudeMdInstructions()`**: Adds/updates CLAUDE.md quick reference - **`configureSmartTrashAlias()`**: Adds `rm` alias to shell configs - **`installClaudeCommands()`**: Copies slash commands to ~/.claude/commands/ **Installation Scopes**: - **User**: `~/.claude/settings.json` (recommended) - **Project**: `./.claude/settings.json` (project-specific) - **Local**: Custom path **Hook Configuration**: ```json { "hooks": { "SessionStart": [{ "hooks": [{ "type": "command", "command": "claude-mem context", "timeout": 180 }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "claude-mem summary", "timeout": 60 }] }], "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "claude-mem new", "timeout": 60 }] }], "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "claude-mem save", "timeout": 180 }] }] } } ``` --- ### `src/commands/uninstall.ts` **Purpose**: Remove claude-mem hooks from Claude Code settings **Key Functions**: - **`uninstall(options)`**: Removes hooks from settings - Supports `--user`, `--project`, `--all` flags - Creates backups before modification - Removes Smart Trash alias from shell configs - **`removeSmartTrashAlias()`**: Cleans up shell configuration files --- ### `src/commands/doctor.ts` **Purpose**: Run health checks on claude-mem installation **Key Functions**: - **`doctor(options)`**: System health diagnostics - Checks data directory existence and permissions - Tests SQLite database connectivity - Verifies Chroma vector store initialization - Outputs results as JSON with `--json` flag **Check Results**: - ✅ `pass`: System component healthy - ⚠️ `warn`: Non-critical issue - ❌ `fail`: Critical problem --- ### `src/commands/status.ts` **Purpose**: Display comprehensive system status **Key Functions**: - **`status()`**: Shows complete system state - Hook configuration (global and project) - Compressed transcript counts - Archive counts - Runtime environment (Node.js, Bun) - Chroma storage status - Installation summary --- ### `src/commands/logs.ts` **Purpose**: View claude-mem operation logs **Key Functions**: - **`logs(options)`**: Display log files - Shows last N lines (default: 20) - Finds most recent log file - Supports `--tail` option - **`showLog(logPath, logType, tail)`**: Formats and displays log content **Log Location**: `~/.claude-mem/logs/claude-mem-{timestamp}.log` --- ### `src/commands/trash.ts` **Purpose**: Smart trash implementation - safer file deletion **Key Functions**: - **`trash(filePaths, options)`**: Move files to trash - Supports glob patterns - `-r, --recursive`: Remove directories - `-f, --force`: Suppress errors - Adds timestamp to avoid conflicts **Trash Location**: `~/.claude-mem/trash/` --- ### `src/commands/trash-view.ts` **Purpose**: Display trash contents with metadata **Key Functions**: - **`viewTrash()`**: Shows trash items - Original filename - Size (files and directories) - Timestamp - Restore instructions - **`formatSize(bytes)`**: Human-readable file sizes - **`getDirectorySize(dirPath)`**: Recursive size calculation --- ### `src/commands/trash-empty.ts` **Purpose**: Permanently delete all trash contents **Key Functions**: - **`emptyTrash(options)`**: Clear trash - Confirmation prompt (unless `--force`) - Shows counts before deletion - Recursive removal of all items --- ### `src/commands/restore.ts` **Purpose**: Interactive file restoration from trash **Key Functions**: - **`restore()`**: Restore files - Interactive file selection - Restores to current directory - Preserves original filename --- ## Hooks System The hooks system integrates claude-mem with Claude Code's lifecycle events. ### `src/hooks/index.ts` **Purpose**: Export all hook handlers **Exports**: ```typescript export { contextHook } from './context.js'; export { saveHook } from './save.js'; export { newHook } from './new.js'; export { summaryHook } from './summary.js'; ``` --- ### `src/hooks/context.ts` **Purpose**: SessionStart hook - provides recent session context **Trigger**: When Claude Code starts a new session (source='startup') **Key Functions**: - **`contextHook(input)`**: Load and display recent memories - Extracts project name from `cwd` - Queries last 5 session summaries - Formats as markdown for Claude to read - Only runs on startup (not resume) **Input**: ```typescript interface SessionStartInput { session_id: string; cwd: string; source?: string; // 'startup' | 'resume' } ``` **Output** (to stdout): ```markdown # Recent Session Context Here's what happened in recent {project} sessions: --- **Request:** {what user asked} **Completed:** {what was done} **Learned:** {key insights} **Next Steps:** {future work} **Files Edited:** file1.ts, file2.ts **Date:** 2025-10-15 ``` --- ### `src/hooks/new.ts` **Purpose**: UserPromptSubmit hook - initializes SDK session **Trigger**: When user submits their first prompt in a session **Key Functions**: - **`newHook(input)`**: Start SDK worker - Creates SDK session record in SQLite - Spawns detached worker process via `claude-mem worker {sessionId}` - Returns immediately (non-blocking) **Input**: ```typescript interface UserPromptSubmitInput { session_id: string; cwd: string; prompt: string; } ``` **Workflow**: 1. Check if SDK session already exists (prevent duplicates) 2. Create `sdk_sessions` table record with status='active' 3. Spawn worker: `spawn('claude-mem', ['worker', sessionId], { detached: true, stdio: 'ignore' })` 4. Output: `{"continue": true, "suppressOutput": true}` **Worker Lifecycle**: The spawned worker runs in the background until Stop hook --- ### `src/hooks/save.ts` **Purpose**: PostToolUse hook - queues tool observations **Trigger**: After every tool execution in Claude Code **Key Functions**: - **`saveHook(input)`**: Send observation to worker - Skips low-value tools (TodoWrite, ListMcpResourcesTool) - Finds active SDK session - Sends observation via Unix socket to worker **Input**: ```typescript interface PostToolUseInput { session_id: string; cwd: string; tool_name: string; tool_input: any; tool_output: any; } ``` **Skipped Tools**: - `TodoWrite`: Too noisy - `ListMcpResourcesTool`: Not meaningful **Communication**: Unix socket at `~/.claude-mem/worker-{sessionId}.sock` **Message Format**: ```json { "type": "observation", "tool_name": "Read", "tool_input": "{\"file_path\": \"/path/to/file.ts\"}", "tool_output": "{\"content\": \"...\"}" } ``` --- ### `src/hooks/summary.ts` **Purpose**: Stop hook - finalizes SDK session **Trigger**: When Claude Code session ends (user closes or `/clear`) **Key Functions**: - **`summaryHook(input)`**: Signal worker to finalize - Finds active SDK session - Sends FINALIZE message via Unix socket - Worker generates summary and stores to database **Input**: ```typescript interface StopInput { session_id: string; cwd: string; } ``` **Message Format**: ```json { "type": "finalize" } ``` **Worker Action**: Generates structured summary and stores to `session_summaries` table --- ## SDK & Worker The SDK worker is a background daemon that analyzes tool observations using Claude Agent SDK. ### `src/sdk/worker.ts` **Purpose**: Background process that synthesizes observations into insights **Key Class**: `SDKWorker` **Lifecycle**: ``` 1. new hook spawns worker ↓ 2. Worker starts Unix socket server ↓ 3. Worker initializes SDK streaming session ↓ 4. save hooks send observations via socket ↓ 5. Worker feeds observations to SDK agent ↓ 6. SDK agent extracts insights (observations) ↓ 7. summary hook sends finalize message ↓ 8. SDK agent generates summary ↓ 9. Worker stores summary and exits ``` **Key Methods**: - **`main()`**: Entry point - Parses sessionDbId from argv - Creates SDKWorker instance - Calls `run()` - **`run()`**: Main worker loop - Loads session from database - Starts Unix socket server - Runs SDK agent with streaming input - Marks session as completed/failed - Cleans up socket - **`startSocketServer()`**: Creates Unix socket - Socket path: `~/.claude-mem/worker-{sessionId}.sock` - Receives observation and finalize messages - Adds messages to `pendingMessages` queue - **`handleMessage(message)`**: Process incoming messages - Queues observations for SDK processing - Sets `isFinalized` flag on finalize message - **`runSDKAgent()`**: Initialize SDK streaming session - Model: `claude-sonnet-4-5` - Disallowed tools: `Glob, Grep, ListMcpResourcesTool, WebSearch` - Streaming input via async generator - Captures SDK session ID from init message - **`createMessageGenerator()`**: Async generator for SDK - Yields initial prompt - Polls `pendingMessages` queue - Yields observation prompts - Yields finalize prompt when session ends - **`handleAgentMessage(content)`**: Parse SDK responses - Extracts `` blocks → stores to `observations` table - Extracts `` block → stores to `session_summaries` table - **`cleanup()`**: Shutdown - Closes socket server - Deletes socket file **Socket Message Types**: - `observation`: Tool execution to analyze - `finalize`: Generate summary and exit **SDK Session Configuration**: ```typescript await query({ model: 'claude-sonnet-4-5', messages: () => this.createMessageGenerator(), disallowedTools: ['Glob', 'Grep', 'ListMcpResourcesTool', 'WebSearch'], signal: this.abortController.signal, onSystemInitMessage: (msg) => { // Capture SDK session ID }, onAgentMessage: (msg) => { // Parse observations and summaries } }); ``` --- ### `src/sdk/prompts.ts` **Purpose**: Build prompts for SDK agent **Key Functions**: - **`buildInitPrompt(project, sessionId, userPrompt)`**: Initialize SDK agent - Explains the agent's role - Defines what to capture (decisions, bugfixes, features, refactorings, discoveries) - Defines what NOT to capture (routine operations, WIP, obvious facts) - Provides XML format for observations - **`buildObservationPrompt(obs)`**: Send tool observation - Shows tool name, time, input, output - Asks: "Is this worth remembering?" - If yes, output `......` - **`buildFinalizePrompt(session)`**: Generate session summary - Reviews all observations - Generates structured summary with 8 required fields **Observation Types**: - `decision`: Architecture or design decisions - `bugfix`: Bug fixes - `feature`: New functionality - `refactor`: Code restructuring - `discovery`: New findings **XML Formats**: **Observation**: ```xml feature Implemented JWT token refresh flow with 7-day expiry ``` **Summary**: ```xml User's request What we explored Key insights What was done Future work src/auth.ts src/auth.ts Additional notes ``` **Types**: ```typescript export interface Observation { id: number; tool_name: string; tool_input: string; tool_output: string; created_at_epoch: number; } export interface SDKSession { id: number; sdk_session_id: string | null; project: string; user_prompt: string; } ``` --- ### `src/sdk/parser.ts` **Purpose**: Parse XML observation and summary blocks from SDK responses **Key Functions**: - **`parseObservations(text)`**: Extract observation blocks - Regex: `/\s*([^<]+)<\/type>\s*([^<]+)<\/text>\s*<\/observation>/g` - Validates observation type (decision/bugfix/feature/refactor/discovery) - Returns array of observations - **`parseSummary(text)`**: Extract summary block - Regex: `/([\s\S]*?)<\/summary>/` - Extracts 8 required fields - Extracts file arrays - Returns null if missing required fields - **`extractField(content, fieldName)`**: Extract simple text field - **`extractFileArray(content, arrayName)`**: Extract file list **Types**: ```typescript export interface ParsedObservation { type: string; text: string; } export interface ParsedSummary { request: string; investigated: string; learned: string; completed: string; next_steps: string; files_read: string[]; files_edited: string[]; notes: string; } ``` --- ### `src/sdk/index.ts` **Purpose**: Export SDK module components **Exports**: ```typescript export { buildInitPrompt, buildObservationPrompt, buildFinalizePrompt } from './prompts.js'; export { parseObservations, parseSummary } from './parser.js'; export type { Observation, SDKSession } from './prompts.js'; export type { ParsedObservation, ParsedSummary } from './parser.js'; ``` --- ## Services ### `src/shared/paths.ts` **Purpose**: Simple path configuration with standard constants **Key Exports**: **Data Directory Constants**: - `DATA_DIR`: `~/.claude-mem` (or CLAUDE_MEM_DATA_DIR env var) - `ARCHIVES_DIR`: `~/.claude-mem/archives` - `LOGS_DIR`: `~/.claude-mem/logs` - `TRASH_DIR`: `~/.claude-mem/trash` - `BACKUPS_DIR`: `~/.claude-mem/backups` - `CHROMA_DIR`: `~/.claude-mem/chroma` - `USER_SETTINGS_PATH`: `~/.claude-mem/settings.json` - `DB_PATH`: `~/.claude-mem/claude-mem.db` **Claude Integration Constants**: - `CLAUDE_CONFIG_DIR`: `~/.claude` (or CLAUDE_CONFIG_DIR env var) - `CLAUDE_SETTINGS_PATH`: `~/.claude/settings.json` - `CLAUDE_COMMANDS_DIR`: `~/.claude/commands` - `CLAUDE_MD_PATH`: `~/.claude/CLAUDE.md` **Helper Functions**: - `getProjectArchiveDir(projectName)`: Get project-specific archive directory - `getWorkerSocketPath(sessionId)`: Get Unix socket path for worker process - `ensureDir(dirPath)`: Create directory with `{recursive: true}` - `ensureAllDataDirs()`: Create all data directories - `ensureAllClaudeDirs()`: Create all Claude integration directories - `getCurrentProjectName()`: Get project name from git root or cwd - `getPackageRoot()`: Find claude-mem package root (2 fallback methods) - `getPackageCommandsDir()`: Find commands directory in package - `createBackupFilename(originalPath)`: Generate timestamped backup filename **Environment Variable Overrides**: - `CLAUDE_MEM_DATA_DIR`: Override data directory location - `CLAUDE_CONFIG_DIR`: Override Claude config directory location --- ### `src/services/sqlite/Database.ts` **Purpose**: SQLite database manager with migration support **Key Class**: `DatabaseManager` (Singleton) **Key Responsibilities**: - Initialize SQLite database with optimized settings - Run schema migrations in order - Provide transaction support - Manage connection lifecycle **Key Methods**: - **`initialize()`**: Setup database - Creates data directory - Opens database: `~/.claude-mem/claude-mem.db` - Applies optimized pragmas - Initializes schema_versions table - Runs pending migrations - **`getConnection()`**: Get active database connection - **`withTransaction(fn)`**: Execute function in transaction - **`close()`**: Close database connection - **`registerMigration(migration)`**: Add migration to queue - **`runMigrations()`**: Apply pending migrations - **`getCurrentVersion()`**: Get current schema version **Optimized SQLite Settings**: ```sql PRAGMA journal_mode = WAL; -- Write-Ahead Logging for concurrency PRAGMA synchronous = NORMAL; -- Balance safety and performance PRAGMA foreign_keys = ON; -- Enforce relationships PRAGMA temp_store = memory; -- Use RAM for temp tables PRAGMA mmap_size = 268435456; -- 256MB memory-mapped I/O PRAGMA cache_size = 10000; -- Large cache for performance ``` **Migration Interface**: ```typescript interface Migration { version: number; up: (db: Database) => void; down?: (db: Database) => void; } ``` **Exports**: ```typescript export { DatabaseManager } export function getDatabase(): Database export function initializeDatabase(): Promise ``` --- ### `src/services/sqlite/HooksDatabase.ts` **Purpose**: Lightweight synchronous database interface for hooks **Key Class**: `HooksDatabase` **Why Separate?**: Hooks need fast, synchronous operations without complex logic **Key Methods**: **Session Summaries**: - **`getRecentSummaries(project, limit)`**: Get last N summaries for project - Returns: request, investigated, learned, completed, next_steps, files_read, files_edited, notes, created_at **SDK Sessions**: - **`findActiveSDKSession(claudeSessionId)`**: Find active session for Claude session - **`createSDKSession(claudeSessionId, project, userPrompt)`**: Create new SDK session - **`updateSDKSessionId(id, sdkSessionId)`**: Update with SDK session ID - **`markSessionCompleted(id)`**: Mark session as completed - **`markSessionFailed(id)`**: Mark session as failed **Observations** (extracted by SDK): - **`storeObservation(sdkSessionId, project, type, text)`**: Store insight **Session Summaries**: - **`storeSummary(sdkSessionId, project, summary)`**: Store structured summary **Lifecycle**: - **`close()`**: Close database connection --- ### `src/services/sqlite/migrations.ts` **Purpose**: Database schema migrations **Migrations**: **Migration 001** - Initial schema: - `sessions`: Core session tracking - `memories`: Compressed memory chunks - `overviews`: Session summaries (legacy) - `diagnostics`: System health logs - `transcript_events`: Raw conversation events **Migration 002** - Hierarchical memory fields: - Adds: `title`, `subtitle`, `facts`, `concepts`, `files_touched` to memories table **Migration 003** - Streaming sessions: - `streaming_sessions`: Real-time session tracking (DEPRECATED - dropped in migration005) **Migration 004** - SDK agent architecture: - `sdk_sessions`: Track SDK streaming sessions - `observation_queue`: Pending observations (DEPRECATED - dropped in migration005, superseded by Unix sockets) - `observations`: Extracted insights - `session_summaries`: Structured session summaries **Migration 005** - Remove orphaned tables: - Drops `streaming_sessions` (superseded by `sdk_sessions`) - Drops `observation_queue` (superseded by Unix socket communication in worker.ts) **Table Schemas**: **`sdk_sessions`**: ```sql CREATE TABLE sdk_sessions ( id INTEGER PRIMARY KEY, claude_session_id TEXT UNIQUE NOT NULL, sdk_session_id TEXT UNIQUE, project TEXT NOT NULL, user_prompt TEXT, started_at TEXT NOT NULL, started_at_epoch INTEGER NOT NULL, completed_at TEXT, completed_at_epoch INTEGER, status TEXT CHECK(status IN ('active', 'completed', 'failed')) ); ``` **`observations`**: ```sql CREATE TABLE observations ( id INTEGER PRIMARY KEY, sdk_session_id TEXT NOT NULL, project TEXT NOT NULL, text TEXT NOT NULL, type TEXT CHECK(type IN ('decision', 'bugfix', 'feature', 'refactor', 'discovery')), created_at TEXT NOT NULL, created_at_epoch INTEGER NOT NULL ); ``` **`session_summaries`**: ```sql CREATE TABLE session_summaries ( id INTEGER PRIMARY KEY, sdk_session_id TEXT UNIQUE NOT NULL, project TEXT NOT NULL, request TEXT, investigated TEXT, learned TEXT, completed TEXT, next_steps TEXT, files_read TEXT, -- JSON array files_edited TEXT, -- JSON array notes TEXT, created_at TEXT NOT NULL, created_at_epoch INTEGER NOT NULL ); ``` **Export**: ```typescript export const migrations: Migration[] = [ migration001, migration002, migration003, migration004, migration005 ]; ``` --- ### `src/services/sqlite/types.ts` **Purpose**: TypeScript interfaces for database operations **Key Types**: **Input Types** (for creating records): ```typescript export interface SessionInput { session_id: string; project: string; created_at: string; created_at_epoch: number; source?: string; archive_path?: string; metadata_json?: string; } export interface MemoryInput { session_id: string; text: string; document_id?: string; keywords?: string; project: string; created_at?: string; created_at_epoch?: number; } export interface OverviewInput { session_id: string; content: string; project: string; created_at?: string; created_at_epoch?: number; } export interface DiagnosticInput { session_id?: string; message: string; severity?: 'info' | 'warn' | 'error'; project: string; created_at?: string; created_at_epoch?: number; } ``` **Row Types** (returned from queries): ```typescript export interface SessionRow { id: number; session_id: string; project: string; created_at: string; created_at_epoch: number; source: string; archive_path: string | null; metadata_json: string | null; } export interface MemoryRow { id: number; session_id: string; text: string; document_id: string | null; keywords: string | null; created_at: string; created_at_epoch: number; project: string; } export interface OverviewRow { id: number; session_id: string; content: string; created_at: string; created_at_epoch: number; project: string; } export interface DiagnosticRow { id: number; session_id: string | null; message: string; severity: string; created_at: string; created_at_epoch: number; project: string; } ``` **Utilities**: ```typescript export function normalizeTimestamp(timestamp: string | Date | number): { iso: string; epoch: number; } ``` --- ### `src/services/sqlite/index.ts` **Purpose**: Export all SQLite components **Exports**: ```typescript // Database manager export { DatabaseManager, getDatabase, initializeDatabase } from './Database.js'; // Hooks database export { HooksDatabase } from './HooksDatabase.js'; // Types export * from './types.js'; // Migrations export { migrations } from './migrations.js'; ``` --- ## Shared Components ### `src/shared/config.ts` **Purpose**: Package metadata configuration **Exports**: ```typescript export const PACKAGE_NAME: string; // 'claude-mem' export const PACKAGE_VERSION: string; // From package.json or __DEFAULT_PACKAGE_VERSION__ export const PACKAGE_DESCRIPTION: string; // Project description export const CLI_NAME: string; // Alias for PACKAGE_NAME ``` **Build Process**: Version is replaced by build script using `--define` flag --- ### `src/shared/types.ts` **Purpose**: Core type definitions **Key Types**: ```typescript export interface Settings { autoCompress?: boolean; projectName?: string; installed?: boolean; backend?: string; // 'chroma' embedded?: boolean; saveMemoriesOnClear?: boolean; rollingCaptureEnabled?: boolean; rollingSummaryEnabled?: boolean; rollingSessionStartEnabled?: boolean; rollingChunkTokens?: number; rollingChunkOverlapTokens?: number; rollingSummaryTurnLimit?: number; [key: string]: unknown; } ``` --- ### `src/shared/storage.ts` **Purpose**: Storage provider abstraction (currently SQLite-only) **Key Interfaces**: ```typescript export type StorageBackend = 'sqlite' | 'jsonl'; export interface IStorageProvider { backend: StorageBackend; // Session operations createSession(session: SessionInput): Promise; getSession(sessionId: string): Promise; hasSession(sessionId: string): Promise; getAllSessionIds(): Promise>; getRecentSessions(limit?: number): Promise; getRecentSessionsForProject(project: string, limit?: number): Promise; // Memory operations createMemory(memory: MemoryInput): Promise; createMemories(memories: MemoryInput[]): Promise; getRecentMemories(limit?: number): Promise; getRecentMemoriesForProject(project: string, limit?: number): Promise; hasDocumentId(documentId: string): Promise; // Overview operations createOverview(overview: OverviewInput): Promise; upsertOverview(overview: OverviewInput): Promise; getRecentOverviews(limit?: number): Promise; getRecentOverviewsForProject(project: string, limit?: number): Promise; // Diagnostic operations createDiagnostic(diagnostic: DiagnosticInput): Promise; // Health check isAvailable(): Promise; } ``` **Implementation**: ```typescript export class SQLiteStorageProvider implements IStorageProvider { // ... implementation } export async function getStorageProvider(): Promise ``` --- ## Utilities ### `src/utils/platform.ts` **Purpose**: Platform-specific utilities for cross-platform compatibility **Key Functions**: - **`Platform.installUv()`**: Install uv package manager - Windows: PowerShell script - Unix: curl + sh script - **`Platform.getShellConfigPaths()`**: Get shell config files - Windows: PowerShell profiles - Unix: `.bashrc`, `.zshrc`, `.bash_profile` - **`Platform.getAliasDefinition(aliasName, command)`**: Get alias syntax - Windows: `function aliasName { command $args }` - Unix: `alias aliasName='command'` **Platform Detection**: ```typescript const isWindows = platform() === 'win32'; ``` **Shell Configs**: - **Windows**: - `~/Documents/PowerShell/Microsoft.PowerShell_profile.ps1` - `~/Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` - **Unix**: - `~/.bashrc` - `~/.zshrc` - `~/.bash_profile` --- ## Key Workflows ### 1. Installation Flow ``` User runs: claude-mem install ↓ 1. Interactive wizard - Select scope (user/project/local) - Configure timeouts - Enable Smart Trash? - Enable save-on-clear? ↓ 2. Install uv package manager ↓ 3. Create directory structure ~/.claude-mem/ ├── archives/ ├── logs/ ├── trash/ ├── backups/ └── chroma/ ↓ 4. Install Chroma MCP server claude mcp add claude-mem -- uvx chroma-mcp ... ↓ 5. Configure Claude hooks ~/.claude/settings.json ↓ 6. Add CLAUDE.md instructions ~/.claude/CLAUDE.md ↓ 7. Install slash commands ~/.claude/commands/ ├── save.md ├── remember.md └── claude-mem.md ↓ 8. Configure Smart Trash alias (optional) Add to shell config: alias rm="claude-mem trash" ↓ 9. Show success message ``` --- ### 2. Session Memory Capture Flow ``` User starts Claude Code ↓ SessionStart hook fires ↓ context hook runs ↓ Query recent summaries for project ↓ Output markdown to Claude ↓ User sees context: "# Recent Session Context Here's what happened in recent sessions: **Request:** Add authentication **Completed:** Implemented JWT flow **Learned:** Token rotation prevents security issues **Next Steps:** Add refresh token API **Files Edited:** src/auth.ts, src/middleware.ts" ↓ User types first prompt ↓ UserPromptSubmit hook fires ↓ new hook runs ↓ Create sdk_sessions record (status='active') ↓ Spawn detached worker: claude-mem worker {sessionId} ↓ Worker starts Unix socket server ↓ Worker initializes SDK streaming session ↓ User works (reads files, edits code, etc.) ↓ PostToolUse hook fires after each tool ↓ save hook runs ↓ Send observation to worker via socket: { "type": "observation", "tool_name": "Edit", "tool_input": "{...}", "tool_output": "{...}" } ↓ Worker receives observation ↓ Worker feeds to SDK agent ↓ SDK analyzes: "Is this worth remembering?" ↓ If yes: SDK outputs: feature Implemented JWT refresh flow with 7-day expiry ↓ Worker parses XML and stores to observations table ↓ User finishes work and closes session ↓ Stop hook fires ↓ summary hook runs ↓ Send finalize message to worker: { "type": "finalize" } ↓ Worker receives finalize ↓ Worker sends finalize prompt to SDK ↓ SDK reviews all observations ↓ SDK generates summary: Add JWT authentication Session management, token storage Rotation prevents token reuse attacks Implemented JWT + refresh flow with 7-day expiry Add token revocation endpoint src/auth.ts src/auth.ts src/middleware/auth.ts Token secret in .env, rotation strategy used ↓ Worker parses summary XML ↓ Worker stores to session_summaries table ↓ Worker marks session as completed ↓ Worker closes socket and exits ↓ Next session: context hook loads this summary! ``` --- ### 3. Smart Trash Flow ``` User runs: rm file.txt ↓ (Smart Trash enabled) ↓ Alias redirects: claude-mem trash file.txt ↓ trash command runs ↓ 1. Check if file exists 2. Add timestamp: file.txt.1729123456789 3. Move to ~/.claude-mem/trash/ ↓ User wants to see trash ↓ User runs: claude-mem trash view ↓ Display: 🗑️ Trash Contents ──────────────────────────────────────── 📄 file.txt Size: 1.2 KB | Trashed: 2025-10-16 10:30:45 ID: file.txt.1729123456789 ──────────────────────────────────────── Total: 0 folders, 1 files (1.2 KB) ↓ User wants to restore ↓ User runs: claude-mem restore ↓ Interactive selection ↓ Restore file.txt.1729123456789 → ./file.txt ↓ User wants to empty trash ↓ User runs: claude-mem trash empty ↓ Confirmation prompt ↓ Permanently delete all files ``` --- ### 4. Doctor/Status Flow ``` User runs: claude-mem doctor ↓ Check data directory: ~/.claude-mem ✅ Data directory accessible ↓ Check SQLite database ✅ SQLite database connected ↓ Check Chroma vector store ✅ Chroma vector store data dir exists ↓ User runs: claude-mem status ↓ Show: ⚙️ Settings Configuration: 📋 Global: ~/.claude/settings.json SessionStart (claude-mem context): ✅ Stop (claude-mem summary): ✅ UserPromptSubmit (claude-mem new): ✅ PostToolUse (claude-mem save): ✅ 📦 Compressed Transcripts: Compressed files: 5 Archive files: 2 🔧 Runtime Environment: ✅ Node.js: v20.11.0 ✅ Bun: 1.0.26 🧠 Chroma Storage Status: ✅ Storage backend: Chroma MCP 📍 Data location: ~/.claude-mem/chroma 📊 Summary: ✅ Claude Memory System is installed (Global) ``` --- ## Summary **claude-mem** is a sophisticated memory system that: 1. **Captures context automatically** via Claude Code hooks 2. **Analyzes observations intelligently** using Claude Agent SDK 3. **Extracts meaningful insights** (not just raw data) 4. **Stores structured summaries** in SQLite 5. **Provides vector search** via Chroma MCP 6. **Restores context seamlessly** in new sessions **Key Innovation**: Instead of saving raw transcripts, claude-mem uses an AI agent to synthesize observations into actionable insights, creating a compressed, searchable knowledge base that grows with your work. **Core Philosophy**: Quality over quantity - only meaningful insights are stored. --- ## File Reference Index ### Entry Points - `src/bin/cli.ts:20-213` - CLI router with Commander ### Commands - `src/commands/install.ts:429-538` - Installation wizard - `src/commands/uninstall.ts:67-162` - Uninstall hooks - `src/commands/doctor.ts:22-93` - Health checks - `src/commands/status.ts:11-158` - System status - `src/commands/logs.ts:40-73` - Log viewer - `src/commands/trash.ts:11-60` - Move to trash - `src/commands/trash-view.ts:53-124` - View trash - `src/commands/trash-empty.ts:6-66` - Empty trash - `src/commands/restore.ts:6-24` - Restore files ### Hooks - `src/hooks/context.ts:16-92` - SessionStart hook - `src/hooks/new.ts:16-56` - UserPromptSubmit hook - `src/hooks/save.ts:25-81` - PostToolUse hook - `src/hooks/summary.ts:16-62` - Stop hook ### SDK - `src/sdk/worker.ts:36-311` - Background worker process - `src/sdk/prompts.ts:24-177` - Prompt builders - `src/sdk/parser.ts:26-132` - XML parser ### Services - `src/services/sqlite/Database.ts:20-177` - Database manager - `src/services/sqlite/HooksDatabase.ts:11-207` - Hooks database - `src/services/sqlite/migrations.ts:7-374` - Schema migrations ### Shared - `src/shared/config.ts:1-51` - Package metadata - `src/shared/paths.ts:1-146` - Path configuration - `src/shared/types.ts:15-30` - Core types - `src/shared/storage.ts:26-188` - Storage abstraction ### Utilities - `src/utils/platform.ts:11-78` - Platform helpers --- **Generated**: 2025-10-16 **Claude-Mem Version**: 3.9.16