Skip to main content

​
Architecture overview

Claude-Mem is a Claude Code plugin with persistent memory across sessions. It captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant context into future sessions.

​
System components

Claude-Mem operates as a Claude Code plugin built from five core components:

Plugin hooks

Six lifecycle hooks capture events: SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd, and a UserMessage debugging hook.

Smart install

A cached dependency checker (smart-install.js) that runs as a pre-hook before context-hook. Only executes when dependency versions change.

Worker service

Long-running Express.js HTTP server on port 37777. Processes observations via the Claude Agent SDK and exposes 22 HTTP endpoints.

Database layer

SQLite 3 with the bun:sqlite driver. FTS5 virtual tables for full-text search, ChromaDB for semantic vector search.

MCP search tools

Four MCP tools (search, timeline, get_observations, __IMPORTANT) following a 3-layer progressive disclosure workflow.

Viewer UI

React + TypeScript web interface at http://localhost:37777. Real-time memory stream via Server-Sent Events, packaged as a single viewer.html bundle.
smart-install.js is a pre-hook dependency checker — not a lifecycle hook. It is called before context-hook via command chaining in hooks.json and only runs when dependencies need updating.

​
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 raw observations to the SQLite database.
3

Processing

The worker service reads queued observations and processes them via the Claude Agent SDK.
4

Output

Processed summaries and structured learnings are written back to the database.
5

Retrieval

The next session’s context-hook reads summaries from the database and injects them as context.

​
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 the intent and invokes MCP search tools.
3

HTTP API

MCP tools call the HTTP endpoint (e.g., GET /api/search).
4

SessionSearch

The worker service queries FTS5 virtual tables via the SessionSearch service.
5

Format

Results are formatted as a compact index and returned via MCP.
6

Return

Claude presents formatted results to the user, fetching full details only for selected IDs.
The search pipeline uses 3-layer progressive disclosure: search → timeline → get_observations. This yields roughly 10x token savings compared to fetching all observations upfront.

​
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
│   │   │   ├── SKILL.md        # Skill frontmatter (~250 tokens)
│   │   │   ├── operations/     # 12 detailed operation docs
│   │   │   └── principles/     # 2 principle guides
│   │   └── troubleshoot/       # Troubleshooting skill
│   │       ├── SKILL.md
│   │       └── operations/     # 6 operation docs
│   │
│   └── ui/                     # Built viewer UI
│       └── viewer.html         # Self-contained bundle
│
├── tests/                      # Test suite
├── docs/                       # Documentation
└── ecosystem.config.cjs        # Process configuration (deprecated)

​
Component details

Hook fileEventResponsibility
context-hook.jsSessionStartStarts Bun worker, injects context from previous sessions
user-message-hook.jsUserMessageDebugging hook
new-hook.jsUserPromptSubmitCreates session record, saves raw prompt
save-hook.jsPostToolUseCaptures tool executions, queues for AI compression
summary-hook.jsStopGenerates final session summary
cleanup-hook.jsSessionEndMarks session complete (never deletes)
Express.js HTTP server on port 37777 (configurable via CLAUDE_MEM_WORKER_PORT) with:
  • 22 HTTP API endpoints total
  • Async observation processing via Claude Agent SDK
  • Real-time updates via Server-Sent Events
  • Auto-managed by Bun’s native ProcessManager
See Worker Service for HTTP API and endpoint reference.
SQLite 3 with bun:sqlite driver featuring:
  • FTS5 virtual tables for full-text search
  • SessionStore for CRUD operations
  • SessionSearch for FTS5 queries
  • ChromaDB integration for vector/semantic search
  • Location: ~/.claude-mem/claude-mem.db
See Database Architecture for schema and FTS5 details.
Four MCP tools following the 3-layer progressive disclosure workflow:
  • __IMPORTANT — Always-visible workflow instructions
  • search — Step 1: compact index with IDs (~50–100 tokens/result)
  • timeline — Step 2: chronological context around a result
  • get_observations — Step 3: full details for selected IDs only
Token savings: ~10x vs fetching all observations upfront.See Search Architecture for technical details.
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
  • Theme toggle (light/dark mode, v5.1.2+)
  • Self-contained HTML bundle (viewer.html)
Built with esbuild into a single file deployment.

Build docs developers (and LLMs) love

Get started for freeTalk to us