Introduction & Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Claude-mem is a persistent memory system specifically built for Claude Code. It serves as a plugin that captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant historical context into future sessions to ensure continuity of knowledge across development tasks. Sources: CLAUDE.md:5-7, README.md:120-123
The system operates automatically by monitoring lifecycle events in a Claude Code session, generating semantic summaries, and storing them in a local SQLite database for later retrieval via semantic and keyword search. Sources: README.md:124-126, CLAUDE.md:12-14
High-Level Architecture
Claude-mem is built on a distributed architecture consisting of lifecycle hooks, a background worker service, and multiple storage backends.
System Components
The architecture is divided into five primary layers:
- Lifecycle Hooks: TypeScript scripts built to ESM that trigger on specific session events.
- Worker Service: An Express API managed by Bun (port 37777) that handles AI processing and serves the viewer UI.
- Database Layer: A combination of SQLite3 for structured data and Chroma for vector embeddings.
- Search Skills: MCP-compliant HTTP APIs that allow Claude to query past work.
- Viewer UI: A React-based interface for real-time memory monitoring.
Sources: CLAUDE.md:12-25, src/services/worker/README.md:5-9
Core Data Flow
The following diagram illustrates how a user interaction triggers the memory capture process.
The diagram shows the transition from a user action to persistent storage and subsequent retrieval in future sessions.
Sources: CLAUDE.md:12-25, src/services/worker/README.md:11-18
Getting Started
Installation
To get started with Claude-mem, users must add the plugin through the Claude Code marketplace and install it within a session.
# Add the plugin from marketplace
/plugin marketplace add thedotmack/claude-mem
# Install the plugin
/plugin install claude-mem
Note: Restarting Claude Code is required after installation for context injection to take effect.
Sources: README.md:131-137
System Requirements
The project relies on a specific toolchain for both execution and vector search capabilities.
| Requirement | Description |
|---|---|
| Node.js | Version 18.0.0 or higher required. |
| Bun | JS runtime and process manager (auto-installed if missing). |
| uv | Python package manager providing Python for Chroma (auto-installed if missing). |
| SQLite 3 | Local storage for sessions and summaries (bundled). |
Sources: CLAUDE.md:43-47, README.md:258-265
Core Features & Concepts
The 5 Lifecycle Hooks
Claude-mem utilizes five distinct hooks to manage the memory lifecycle:
- SessionStart: Initializes the environment and previous context.
- UserPromptSubmit: Captures the user's intent.
- PostToolUse: Processes the output of tools (e.g., shell, read, write).
- Summary: Generates a periodic progress checkpoint.
- SessionEnd: Finalizes and cleans up the session state.
Sources: CLAUDE.md:12, README.md:173-174
Observation Types
When recording work, the system categorizes information into specific types to improve searchability:
| ID | Label | Description |
|---|---|---|
bugfix | Bug Fix | Something was broken, now fixed. |
feature | Feature | New capability or functionality added. |
refactor | Refactor | Code restructured, behavior unchanged. |
discovery | Discovery | Learning about existing system. |
decision | Decision | Architectural/design choice with rationale. |
Sources: plugin/modes/code.json:6-45
Privacy and Control
The system implements a Dual-Tag System to prevent sensitive information from being stored or recursive loops from occurring:
<private>content</private>: Manual user control to prevent storage of sensitive data.<claude-mem-context>content</claude-mem-context>: Automatic system tag for injected observations to prevent recursive storage.
Sources: CLAUDE.md:27-33, README.md:149
3-Layer Search Workflow
Claude-mem provides a token-efficient strategy for retrieving memories using MCP tools.
This sequence demonstrates the progressive disclosure pattern used to minimize token costs.
Sources: README.md:204-222, cursor-hooks/cursorrules-template.md:23-45
Directory Structure
Key file locations for configuration and data:
- Source Code:
src/ - Build Output:
plugin/ - Settings:
~/.claude-mem/settings.json(auto-created on first run). - Database:
~/.claude-mem/claude-mem.db - Vector Index:
~/.claude-mem/chroma/
Sources: CLAUDE.md:37-41, README.md:271-274
Summary
Claude-mem provides a robust framework for long-term AI context retention. By integrating deeply with Claude Code's lifecycle and utilizing a hybrid search approach (SQLite + Chroma), it allows developers to maintain complex project state without manual documentation. The architecture is designed to be non-blocking, ensuring that memory capture does not degrade the performance of the primary development session. Sources: README.md:120-130, cursor-hooks/REVIEW.md:25-30