Skip to main content

​
Architecture Overview

​
System Components

Claude-Mem operates as a Claude Code plugin with five core components:
  1. Plugin Hooks - Capture lifecycle events (6 hook files)
  2. Smart Install - Cached dependency checker (pre-hook script, runs before context-hook)
  3. Worker Service - Process observations via Claude Agent SDK + HTTP API (10 search endpoints)
  4. Database Layer - Store sessions and observations (SQLite + FTS5 + ChromaDB)
  5. mem-search Skill - Skill-based search with progressive disclosure (v5.4.0+)
  6. Viewer UI - Web-based real-time memory stream visualization

​
Technology Stack

LayerTechnology
LanguageTypeScript (ES2022, ESNext modules)
RuntimeNode.js 18+
DatabaseSQLite 3 with bun:sqlite driver
Vector StoreChromaDB (optional, for semantic search)
HTTP ServerExpress.js 4.18
Real-timeServer-Sent Events (SSE)
UI FrameworkReact + TypeScript
AI SDK@anthropic-ai/claude-agent-sdk
Build Toolesbuild (bundles TypeScript)
Process ManagerBun
TestingNode.js built-in test runner

​
Data Flow

​
Memory Pipeline

Hook (stdin) → Database → Worker Service → SDK Processor → Database → Next Session Hook
  1. Input: Claude Code sends tool execution data via stdin to hooks
  2. Storage: Hooks write observations to SQLite database
  3. Processing: Worker service reads observations, processes via SDK
  4. Output: Processed summaries written back to database
  5. Retrieval: Next session’s context hook reads summaries from database

​
Search Pipeline

User Query → MCP Tools Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude
  1. User Query: User asks naturally: “What bugs did we fix?”
  2. MCP Tools Invoked: Claude recognizes intent and invokes MCP search tools
  3. HTTP API: MCP tools call HTTP endpoint (e.g., /api/search/observations)
  4. SessionSearch: Worker service queries FTS5 virtual tables
  5. Format: Results formatted and returned via MCP
  6. Return: Claude presents formatted results to user
Uses 3-layer progressive disclosure: search → timeline → get_observations

​
Session Lifecycle

┌─────────────────────────────────────────────────────────────────┐
│ 0. Smart Install Pre-Hook Fires                                 │
│    Checks dependencies (cached), only runs on version changes   │
│    Not a lifecycle hook - runs before context-hook starts       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 1. Session Starts → Context Hook Fires                          │
│    Starts Bun worker if needed, injects context from previous   │
│    sessions (configurable observation count)                    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. User Types Prompt → UserPromptSubmit Hook Fires              │
│    Creates session in database, saves raw user prompt for FTS5  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. Claude Uses Tools → PostToolUse Hook Fires (100+ times)      │
│    Captures tool executions, sends to worker for AI compression │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. Worker Processes → Claude Agent SDK Analyzes                 │
│    Extracts structured learnings via iterative AI processing    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 5. Claude Stops → Summary Hook Fires                            │
│    Generates final summary with request, completions, learnings │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 6. Session Ends → Cleanup Hook Fires                            │
│    Marks session complete (graceful, not DELETE), ready for     │
│    next session context. Skips on /clear to preserve ongoing    │
└─────────────────────────────────────────────────────────────────┘

​
Directory Structure

claude-mem/
├── src/
│   ├── hooks/                  # Hook implementations (6 hooks)
│   │   ├── context-hook.ts     # SessionStart
│   │   ├── user-message-hook.ts # UserMessage (for debugging)
│   │   ├── new-hook.ts         # UserPromptSubmit
│   │   ├── save-hook.ts        # PostToolUse
│   │   ├── summary-hook.ts     # Stop
│   │   ├── cleanup-hook.ts     # SessionEnd
│   │   └── hook-response.ts    # Hook response utilities
│   │
│   ├── sdk/                    # Claude Agent SDK integration
│   │   ├── prompts.ts          # XML prompt builders
│   │   ├── parser.ts           # XML response parser
│   │   └── worker.ts           # Main SDK agent loop
│   │
│   ├── services/
│   │   ├── worker-service.ts   # Express HTTP + SSE service
│   │   └── sqlite/             # Database layer
│   │       ├── SessionStore.ts # CRUD operations
│   │       ├── SessionSearch.ts # FTS5 search service
│   │       ├── migrations.ts
│   │       └── types.ts
│   │
│   ├── ui/                     # Viewer UI
│   │   └── viewer/             # React + TypeScript web interface
│   │       ├── components/     # UI components
│   │       ├── hooks/          # React hooks
│   │       ├── utils/          # Utilities
│   │       └── assets/         # Fonts, logos
│   │
│   ├── shared/                 # Shared utilities
│   │   ├── config.ts
│   │   ├── paths.ts
│   │   └── storage.ts
│   │
│   └── utils/
│       ├── logger.ts
│       ├── platform.ts
│       └── port-allocator.ts
│
├── scripts/                    # Build and utility scripts
│   └── smart-install.js        # Cached dependency checker (pre-hook)
│
├── plugin/                     # Plugin distribution
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── hooks/
│   │   └── hooks.json
│   ├── scripts/                # Built executables
│   │   ├── context-hook.js
│   │   ├── user-message-hook.js
│   │   ├── new-hook.js
│   │   ├── save-hook.js
│   │   ├── summary-hook.js
│   │   ├── cleanup-hook.js
│   │   └── worker-service.cjs  # Background worker + HTTP API
│   │
│   ├── skills/                 # Agent skills (v5.4.0+)
│   │   ├── mem-search/         # Search skill with progressive disclosure (v5.5.0)
│   │   │   ├── SKILL.md        # Skill frontmatter (~250 tokens)
│   │   │   ├── operations/     # 12 detailed operation docs
│   │   │   └── principles/     # 2 principle guides
│   │   ├── troubleshoot/       # Troubleshooting skill
│   │   │   ├── SKILL.md
│   │   │   └── operations/     # 6 operation docs
│   │   └── version-bump/       # Version management skill (deprecated)
│   │
│   └── ui/                     # Built viewer UI
│       └── viewer.html         # Self-contained bundle
│
├── tests/                      # Test suite
├── docs/                       # Documentation
└── ecosystem.config.cjs        # Process configuration (deprecated)

​
Component Details

​
1. Plugin Hooks (6 Hooks)

  • context-hook.js - SessionStart: Starts Bun worker, injects context
  • user-message-hook.js - UserMessage: Debugging hook
  • new-hook.js - UserPromptSubmit: Creates session, saves prompt
  • save-hook.js - PostToolUse: Captures tool executions
  • summary-hook.js - Stop: Generates session summary
  • cleanup-hook.js - SessionEnd: Marks session complete
Note: smart-install.js is a pre-hook dependency checker (not a lifecycle hook). It’s called before context-hook via command chaining in hooks.json and only runs when dependencies need updating. See Plugin Hooks for detailed hook documentation.

​
2. Worker Service

Express.js HTTP server on port 37777 (configurable) with:
  • 10 search HTTP API endpoints (v5.4.0+)
  • 8 viewer UI HTTP/SSE endpoints
  • Async observation processing via Claude Agent SDK
  • Real-time updates via Server-Sent Events
  • Auto-managed by Bun
See Worker Service for HTTP API and endpoints.

​
3. Database Layer

SQLite3 with bun:sqlite driver featuring:
  • FTS5 virtual tables for full-text search
  • SessionStore for CRUD operations
  • SessionSearch for FTS5 queries
  • Location: ~/.claude-mem/claude-mem.db
See Database Architecture for schema and FTS5 search.

​
4. mem-search Skill (v5.4.0+)

Skill-based search with progressive disclosure providing 10 search operations:
  • Search observations, sessions, prompts (full-text FTS5)
  • Filter by type, concept, file
  • Get recent context, timeline, timeline by query
  • API help documentation
Token Savings: ~2,250 tokens per session vs MCP approach
  • Skill frontmatter: ~250 tokens (loaded at session start)
  • Full instructions: ~2,500 tokens (loaded on-demand when invoked)
  • HTTP API endpoints instead of MCP tools
Skill Enhancement (v5.5.0): Renamed from “search” to “mem-search” for better scope differentiation. Effectiveness increased from 67% to 100% with enhanced triggers and comprehensive documentation. See Search Architecture for technical details and examples.

​
5. Viewer UI

React + TypeScript web interface at http://localhost:37777 featuring:
  • Real-time memory stream via Server-Sent Events
  • Infinite scroll pagination with automatic deduplication
  • Project filtering and settings persistence
  • GPU-accelerated animations
  • Self-contained HTML bundle (viewer.html)
Built with esbuild into a single file deployment.