System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Claude-mem is a persistent memory plugin for Claude Code designed to capture, compress, and inject context across different development sessions. By observing tool usage and user prompts, the system builds a semantic history of a project, allowing the AI agent to maintain continuity without manual context re-provisioning.
The architecture is built on a distributed hook-based capture system that feeds into a centralized local worker service. This worker manages a dual-database storage layer (SQLite for structured data and Chroma for vector embeddings) and provides a web-based UI for real-time monitoring.
Sources: CLAUDE.md:3-8, README.md:104-106
Core System Components
The system is partitioned into several functional layers that handle everything from event capture to semantic retrieval.
| Component | Responsibility | Technical Implementation |
|---|---|---|
| Lifecycle Hooks | Capture events within the Claude session | TypeScript/ESM scripts in src/hooks/ |
| Worker Service | Orchestration, API, and AI processing | Express/Bun server on port 37777 |
| Storage Layer | Persistent storage and vector search | SQLite3 & Chroma DB |
| Search Skill | Natural language interface to memory | MCP Skill (mem-search) |
| Viewer UI | Real-time observation feed and settings | React-based web interface |
Sources: CLAUDE.md:10-21, src/services/worker/README.md:5-15
Component Interaction Flow
The following diagram illustrates how a hook-triggered event propagates through the system to persistent storage.
This flow ensures that memory processing happens asynchronously in the worker layer, preventing the active Claude session from being blocked by AI summarization tasks.
Sources: CLAUDE.md:12-16, src/services/worker/README.md:9-15
Data Capture and Lifecycle Hooks
The system utilizes five distinct lifecycle hooks to monitor the progress of a development session. These hooks transform raw session data into structured observations.
- SessionStart: Initializes the memory context for a new session.
- UserPromptSubmit: Captures the user's intent before processing.
- PostToolUse: Records the outcome of tool executions (the primary source of "facts").
- Summary: Triggers intermediate progress checkpoints.
- SessionEnd: Finalizes and persists the session state.
Sources: CLAUDE.md:10, README.md:143-145
Privacy and Filtering
Before data reaches the worker, a "Dual-Tag System" strips sensitive information. The <private> tag allows users to manually exclude blocks from storage, while the <claude-mem-context> tag prevents recursive storage of information the system itself injected.
Sources: CLAUDE.md:23-28
Worker Service Architecture
The Worker Service acts as the central hub for the application. It is organized into specialized route handlers that interact with a service layer for business logic.
Key API Endpoint Categories
- Session Management: Endpoints like
POST /sessions/initandPOST /sessions/:sessionId/observationsmanage the lifecycle of a conversation. - Data Retrieval: Endpoints such as
GET /observationsandGET /statsprovide raw and aggregated data for the UI. - Search/MCP Proxy: Facilitates complex queries through endpoints like
GET /searchandGET /timeline.
Sources: src/services/worker/README.md:20-80
Memory Search and Progressive Disclosure
Claude-mem implements a 3-layer workflow pattern to maximize token efficiency when retrieving past information. This prevents "context stuffing" by only fetching detailed information when necessary.
Observation Schema
Observations are classified into specific types to aid retrieval:
- bugfix: Correcting broken functionality.
- feature: New capabilities.
- refactor: Structural code changes.
- discovery: System learning.
- decision: Architectural rationale.
Sources: README.md:166-180, plugin/modes/code.json:5-46
Integration with External Tools
Cursor Rules Integration
For developers using the Cursor IDE, the system automatically maintains a .cursor/rules/claude-mem-context.mdc file. This file includes YAML frontmatter with alwaysApply: true, ensuring that the most recent project context is always available to the IDE's AI.
Sources: cursor-hooks/cursorrules-template.md:3-15, tests/cursor-context-update.test.ts:37-65
Translation and Localization
The system includes a dedicated translation module (readme-translator) that leverages the Claude Agent SDK to maintain documentation across multiple languages. It uses the ANTHROPIC_API_KEY or existing Claude Code authentication to perform translations while preserving code blocks.
Sources: scripts/translate-readme/README.md:3-25
Conclusion
The architecture of Claude-mem prioritizes local, asynchronous processing to maintain performance while providing deep semantic project history. By separating the capture logic (hooks) from the heavy lifting (Worker/AI SDK) and storage (SQLite/Chroma), the system provides a robust framework for long-term AI memory in software development.
Sources: CLAUDE.md:73-86, src/services/worker/README.md:100-108