Skip to main content

​
Claude-Mem

Persistent memory compression system for Claude Code Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.

​
Quick Start

Start a new Claude Code session in the terminal and enter the following commands: 
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
Restart Claude Code. Context from previous sessions will automatically appear in new sessions.

​
Key Features

  • 🧠 Persistent Memory - Context survives across sessions
  • 🌐 Multilingual Modes - Supports 10+ languages (Spanish, Chinese, French, etc.)
  • 🎭 Mode System - Switch between workflows (Code, Email Investigation)
  • 🔍 mem-search Skill - Query your project history with natural language (~2,250 token savings)
  • 🌐 Web Viewer UI - Real-time memory stream visualization at http://localhost:37777
  • 🔒 Privacy Control - Use <private> tags to exclude sensitive content from storage
  • ⚙️ Context Configuration - Fine-grained control over what context gets injected
  • 🤖 Automatic Operation - No manual intervention required
  • 📊 FTS5 Search - Fast full-text search across observations
  • 🔗 Citations - Reference past observations with IDs (access via http://localhost:37777/api/observation/{id} or view all in the web viewer at http://localhost:37777)

​
How It Works

┌─────────────────────────────────────────────────────────────┐
│ Session Start → Inject context from last 10 sessions       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ User Prompts → Create session, save user prompts           │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Tool Executions → Capture observations (Read, Write, etc.)  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Worker Processes → Extract learnings via Claude Agent SDK   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Session Ends → Generate summary, ready for next session     │
└─────────────────────────────────────────────────────────────┘
Core Components:
  1. 5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
  2. Smart Install - Cached dependency checker (pre-hook script)
  3. Worker Service - HTTP API on port 37777 managed by Bun
  4. SQLite Database - Stores sessions, observations, summaries with FTS5 search
  5. mem-search Skill - Query historical context with natural language
  6. Web Viewer UI - Real-time visualization with SSE and infinite scroll
See Architecture Overview for details.

​
System Requirements

  • Node.js: 18.0.0 or higher
  • Claude Code: Latest version with plugin support
  • Bun: JavaScript runtime and process manager (auto-installed if missing)
  • SQLite 3: For persistent storage (bundled)

​
What’s New

v7.1.0 - Bun Migration:
  • Replaced PM2 with native Bun process management
  • Switched from better-sqlite3 to bun:sqlite for faster database access
  • Automatic one-time migration on first hook trigger
  • Simplified cross-platform support
v7.0.0 - Context Configuration:
  • 11 settings for fine-grained control over context injection
  • Dual-tag privacy system (<private> tags)
Previous Highlights:
  • v5.5.0: mem-search skill with 100% effectiveness rate
  • v5.4.0: Skill-based search (~2,250 tokens saved per session)
  • v5.1.0: Web viewer UI at http://localhost:37777

​
Next Steps

Installation

Quick start & advanced installation

Getting Started

Learn how Claude-Mem works automatically

Architecture

System components & data flow

Search Tools

Query your project history