Skip to main content

​
Claude-Mem

Claude-Mem is a persistent memory compression system built for Claude Code. It 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 your projects even after sessions end or reconnect.
Claude-Mem operates entirely automatically. Once installed, no manual intervention is required — every session start, tool execution, and session end is handled by the plugin’s lifecycle hooks.

​
Key Features

Persistent Memory

Context survives across sessions. Observations from tool use, file reads, edits, and commands are stored in SQLite and re-injected into every new session.

Folder Context Files

Auto-generated CLAUDE.md files appear in your project folders with activity timelines, giving Claude immediate project awareness on session start.

MCP Search Tools

Query your full project history with natural language. Claude auto-invokes MCP tools following a 3-layer workflow for token-efficient recall.

Web Viewer UI

A real-time memory stream visualization runs at http://localhost:37777 with infinite scroll, SSE updates, and version channel switching.

Privacy Control

Wrap any content in <private>...</private> tags to exclude it from storage entirely. Stripping happens at the hook layer before data reaches the database.

Multilingual Modes

Supports 28 languages including Spanish, Chinese, French, Japanese, Portuguese, Korean, German, and more.

FTS5 Full-Text Search

Fast full-text search across all captured observations using SQLite’s FTS5 engine. Reference past observations directly by ID.

Context Configuration

11 settings for fine-grained control over what context gets injected, how many observations appear, and how summaries are displayed.

​
How It Works

Claude-Mem hooks into five Claude Code lifecycle events to build a complete picture of every session:
1

Session Start — Context Injection

The SessionStart hook queries the database for observations and summaries from the last 10 sessions in your project. Formatted context is injected into Claude’s initial context window, so Claude immediately knows what was done before.
2

User Prompts — Session Tracking

The UserPromptSubmit hook creates or continues a session record and saves the user’s prompt for later summarization.
3

Tool Executions — Observation Capture

The PostToolUse hook fires after every tool call (Read, Write, Edit, Bash, Glob, Grep, and all others). Raw tool output is sent to the worker service for processing.
4

Worker Processing — Semantic Extraction

A background worker service (managed by Bun on port 37777) uses the Claude Agent SDK to extract structured learnings from each observation: title, narrative, facts, concepts, file references, and a classification type.
5

Session End — Summary Generation

The Stop hook fires when Claude finishes responding. A session summary is automatically generated covering: what was requested, what was investigated, what was learned, what was completed, and suggested next steps.
Session Start  →  Inject context from last 10 sessions
      ↓
User Prompts   →  Create session, save user prompts
      ↓
Tool Executions →  Capture observations (Read, Write, Bash, etc.)
      ↓
Worker Processes →  Extract learnings via Claude Agent SDK
      ↓
Session Ends   →  Generate summary, ready for next session

​
Core Components

Claude-Mem registers hooks for SessionStart, UserPromptSubmit, PostToolUse, and Stop. Each hook is a compiled TypeScript ESM script built to plugin/scripts/. The hooks coordinate with the worker service via HTTP on localhost:37777.
An Express HTTP API managed by Bun that runs on port 37777. It handles all AI processing asynchronously so hooks return quickly without blocking Claude. It also serves the Web Viewer UI and all search endpoints.
Persistent storage at ~/.claude-mem/claude-mem.db using Bun’s native bun:sqlite driver. Stores sessions, observations, and summaries with FTS5 full-text search indexing across all content.
Three MCP tools (search, timeline, get_observations) that Claude can invoke to query project history. Follow a 3-layer workflow for ~10x token savings: search for an index, check timeline context, then fetch full details only for relevant IDs.
A React interface at http://localhost:37777 with real-time SSE updates, infinite scroll, observation details, session history, and version channel management (stable ↔ beta).

​
System Requirements

RequirementVersion
Node.js18.0.0 or higher
Claude CodeLatest version with plugin support
BunAuto-installed if missing
uvAuto-installed if missing (provides Python for Chroma)
SQLite 3Bundled

​
What’s New

  • Folder Context Files: Auto-generated CLAUDE.md in project folders with activity timelines
  • Worktree Support: Unified context from parent repos and git worktrees
  • Configurable Observation Limits: Control how many observations appear in context
  • Windows Fixes: Resolved IPC detection and hook execution issues
  • Settings Auto-Creation: settings.json now auto-creates on first run
  • MCP Tools Naming: Updated terminology from “mem-search skill” to “MCP tools”
  • Replaced PM2 with native Bun process management
  • Switched from better-sqlite3 to bun:sqlite for faster database access
  • Simplified cross-platform support across Windows, macOS, and Linux
  • 11 settings for fine-grained control over context injection
  • Dual-tag privacy system with <private> tags processed at the hook layer

​
Next Steps

Installation

Two-command plugin install, system requirements, advanced source install, and post-install verification steps.

Getting Started

Learn how Claude-Mem works automatically: what gets captured, how context injection works, and how to search your history.

Beta Features

Try Endless Mode — an experimental biomimetic memory architecture that extends sessions beyond the standard context window limit.

Search Tools

Query your full project history with natural language using the 3-layer MCP search workflow.

Build docs developers (and LLMs) love

Get started for freeTalk to us