docs/public/architecture/overview.mdx
Claude-Mem operates as a Claude Code plugin with the following core components:
Read, PostToolUse, Stop)mem-search skill / MCP server for progressive disclosure search| Layer | Technology |
|---|---|
| Language | TypeScript (ES2022, ESNext modules) |
| Runtime | Node.js 20+ and Bun ≥ 1.0 |
| Database | SQLite 3 with bun:sqlite driver |
| Vector Store | Chroma (optional, for semantic search) |
| HTTP Server | Express.js 5 |
| Real-time | Server-Sent Events (SSE) |
| UI Framework | React + TypeScript |
| AI SDK | @anthropic-ai/claude-agent-sdk (or Gemini / OpenRouter) |
| Build Tool | esbuild (bundles TypeScript) |
| Process Manager | Bun |
| Testing | bun test |
Hook (stdin) → Database → Worker Service → SDK Processor → Database → Next Session Hook
User Query → MCP Tools Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude
/api/search/observations)Uses 3-layer progressive disclosure: search → timeline → get_observations
┌─────────────────────────────────────────────────────────────────┐
│ 0. Setup Hook Fires (version-check.js) │
│ Sub-100ms read of .install-version; on mismatch prints │
│ "run: npx claude-mem repair" to stderr. Always exits 0. │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 1. Session Starts → Worker-start, then Context Hook │
│ 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 │
└─────────────────────────────────────────────────────────────────┘
claude-mem/
├── src/
│ ├── hooks/ # TypeScript hook implementations (built via esbuild)
│ ├── sdk/ # Claude Agent SDK integration
│ ├── services/
│ │ ├── worker-service.ts # Express HTTP + SSE service (worker entry point)
│ │ ├── sync/ChromaSync.ts # Optional Chroma vector index
│ │ └── sqlite/ # SQLite + FTS5 storage layer
│ ├── ui/viewer/ # React + TypeScript web viewer
│ ├── shared/ # Shared utilities (paths, settings defaults)
│ └── utils/ # Logging, platform, tag-stripping helpers
│
├── scripts/ # Build + utility scripts
│
├── plugin/ # Plugin distribution (synced to marketplace)
│ ├── .claude-plugin/plugin.json
│ ├── hooks/hooks.json # Hook registration (Setup + 5 lifecycle hooks)
│ ├── scripts/ # Built executables
│ │ ├── version-check.js # Setup-phase marker check (sub-100ms)
│ │ ├── bun-runner.js # Resolves Bun and runs worker-service.cjs
│ │ ├── worker-service.cjs # Worker daemon + lifecycle hook dispatcher
│ │ ├── worker-cli.js # CLI shim
│ │ ├── worker-wrapper.cjs # Process wrapper
│ │ ├── mcp-server.cjs # MCP search server
│ │ ├── statusline-counts.js
│ │ └── context-generator.cjs
│ ├── skills/ # Agent skills (mem-search, make-plan, do, etc.)
│ └── ui/viewer.html # Self-contained React bundle
│
├── tests/ # Test suite (`bun test`)
├── docs/ # Mintlify documentation
└── openclaw/ # OpenClaw integration plugin
The plugin registers a Setup-phase version-check.js plus five lifecycle hooks. Each lifecycle event invokes bun-runner.js to spawn worker-service.cjs with a hook claude-code <event> argument; the worker process is the single dispatcher for all hook logic. Events:
version-check.js (sub-100ms marker check; never installs anything)hook claude-code context (context injection)hook claude-code session-initRead) → hook claude-code file-context*) → hook claude-code observationhook claude-code summarize (summary generation)The actual runtime install (Bun, uv, bun install) is performed by npx claude-mem install / npx claude-mem repair with a visible installer spinner; the Setup hook itself only reads the .install-version marker.
See Plugin Hooks for detailed hook documentation.
Express.js HTTP server on a per-user port (default 37700 + (uid % 100), override via CLAUDE_MEM_WORKER_PORT) with:
See Worker Service for HTTP API and endpoints.
SQLite3 with bun:sqlite driver featuring:
~/.claude-mem/claude-mem.dbSee Database Architecture for schema and FTS5 search.
Skill-based search with progressive disclosure providing 10 search operations:
Token Savings: ~2,250 tokens per session vs MCP approach
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.
React + TypeScript web interface served by the worker on its configured port (default http://127.0.0.1:<worker-port>) featuring:
Built with esbuild into a single file deployment.