claude-mem

name	claude-mem
description	Persistent memory compression system for Claude Code enabling context preservation across sessions with automatic observations, semantic search, and privacy controls
version	1.0.0
tags	["claude-code","memory","context","persistence","mcp","plugin","sqlite","observations","sessions"]

Claude-Mem

Claude-Mem is a persistent memory compression system for Claude Code that enables context preservation across multiple sessions. It automatically captures tool usage observations, generates semantic summaries, and makes them available to future sessions, maintaining project knowledge continuity.

Key Features

• Persistent Memory - Context survives between sessions automatically
• Folder Context Files - Auto-generated CLAUDE.md files with activity timelines
• Multilingual Support - 28+ languages including Spanish, Chinese, French, Japanese
• Mode System - Switchable workflows (Code, Email Investigation, Chill)
• MCP Search Tools - Natural language queries across project history
• Web Viewer UI - Real-time memory visualization at http://localhost:37777
• Privacy Controls - <private> tags exclude sensitive content from storage
• FTS5 Search - Full-text search across all observations
• Citation System - Reference past observations by ID

System Requirements

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

Installation

Quick Start (Recommended)

# In Claude Code terminal
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Restart Claude Code after installation. Context from previous sessions will automatically appear.

Advanced Installation (Source Build)

git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
npm install
npm run build
npm run worker:start
npm run worker:status

Verification

# Check hook installation
cat plugin/hooks/hooks.json

# View worker logs
npm run worker:logs

# Test context injection
npm run test:context

How It Works

Five-Stage Pipeline

1. Session Start - Injects context from last 10 sessions
2. User Prompts - Creates session and saves user input
3. Tool Executions - Captures observations from Read, Write, Bash operations
4. Worker Processes - Extracts learnings via Claude Agent SDK
5. Session End - Generates summaries for next session

Hook Architecture

Hook	Timeout	Purpose
SessionStart	120s	Inject context from recent sessions
UserPromptSubmit	60s	Create session, save prompt
PostToolUse	120s	Capture tool observations
Stop	60s	Generate session summary

Captured Activities

The system records every tool interaction:

• File operations (reads, writes, edits)
• Command executions via bash
• File pattern searches and content queries
• All other Claude Code tools

Processing Pipeline

Captured observations produce:

• Brief titles describing what occurred
• Contextual subtitles
• Detailed narrative explanations
• Key learnings as bullet points
• Relevant concept tags
• Work classifications (bugfix, feature, decision, etc.)
• Affected file listings

Configuration

Environment Variables

AI Model Selection:

export CLAUDE_MEM_MODEL=sonnet      # haiku, sonnet, opus
export CLAUDE_MEM_PROVIDER=claude   # claude, gemini, openrouter

Provider-Specific:

# Gemini
export CLAUDE_MEM_GEMINI_API_KEY="your-key"
export CLAUDE_MEM_GEMINI_MODEL="gemini-2.5-flash-lite"

# OpenRouter
export CLAUDE_MEM_OPENROUTER_API_KEY="your-key"
export CLAUDE_MEM_OPENROUTER_MODEL="xiaomi/mimo-v2-flash:free"

Storage & Networking:

export CLAUDE_MEM_DATA_DIR=~/.claude-mem    # Database location
export CLAUDE_MEM_WORKER_PORT=37777         # Service port
export CLAUDE_MEM_WORKER_HOST=127.0.0.1     # Service address
export CLAUDE_MEM_LOG_LEVEL=INFO            # DEBUG, INFO, WARN, ERROR, SILENT

Context Injection:

export CLAUDE_MEM_CONTEXT_SESSION_COUNT=10       # Recent sessions to retrieve
export CLAUDE_MEM_CONTEXT_OBSERVATIONS=50        # Injected observations count
export CLAUDE_MEM_CONTEXT_FULL_COUNT=5           # Expanded observations
export CLAUDE_MEM_CONTEXT_FULL_FIELD=narrative   # narrative or facts

Display Options:

export CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS=true
export CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS=true
export CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT=true
export CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY=false
export CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE=false

Tool Exclusions:

# Comma-separated list of tools to skip
export CLAUDE_MEM_SKIP_TOOLS="ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion"

Settings File

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_MODEL": "sonnet",
  "CLAUDE_MEM_MODE": "code",
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": 50,
  "CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED": false
}

Or run interactive setup:

./claude-mem-settings.sh

MCP Search Tools

Available Tools

search - Memory index lookup

Parameters:
  query      FTS5 search syntax
  limit      Results per page (default: 20)
  offset     Pagination offset
  type       Filter: bugfix, feature, decision, discovery, refactor, change
  project    Filter by project name
  dateStart  Filter from date
  dateEnd    Filter to date
  orderBy    Sort order

timeline - Chronological context retrieval

Parameters:
  anchor        Observation ID to center on
  query         Alternative to anchor
  depth_before  Observations before (default: 3)
  depth_after   Observations after (default: 3)

get_observations - Full detail fetching

Parameters:
  ids    Array of observation IDs (required)

Search Syntax (FTS5)

# Boolean operators
"user auth" AND (JWT OR session) NOT deprecated

# Scoped searches
title:authentication
content:database
concepts:gotcha

# Phrase matching
"connection failed"

Three-Layer Workflow

Achieves ~10x token savings through progressive disclosure:

1. Search - Lightweight index (~50-100 tokens per result)
2. Timeline - Contextual surroundings (~100-200 tokens per observation)
3. Get Observations - Full details only when needed (~500-1,000 tokens per record)

Example:

User: "What bugs did we fix last week?"

Claude automatically:
1. Calls search(type: "bugfix", dateStart: "2025-01-09")
2. Reviews index results
3. Calls timeline(anchor: [relevant_id]) if context needed
4. Calls get_observations(ids: [...]) for specific details

Modes

What is a Mode?

A mode defines four aspects:

1. Observer Role - How Claude analyzes work (e.g., "Software Engineer")
2. Observation Types - Valid categories (Bug Fix, Feature, etc.)
3. Concepts - Semantic tags for indexing
4. Language - Output language for observations

Available Modes

Mode	Description
code	Default software development mode
code--chill	Fewer observations, only records painful-to-rediscover items
email-investigation	Email archive analysis, entity tracking
code--es	Spanish output
code--fr	French output
code--de	German output
code--ja	Japanese output
code--zh	Chinese output

Switching Modes

Via settings.json:

{
  "CLAUDE_MEM_MODE": "code--es"
}

Via environment:

export CLAUDE_MEM_MODE="code--fr"

Mode Inheritance

Uses -- separator notation:

• code--es loads code config, then merges code--es overrides
• Child settings override parent values

Privacy Controls

Private Tags

Wrap sensitive content to exclude from storage:

<private>
Your sensitive content here
</private>

Behavior:

• Claude sees content during current session
• Content stripped before database storage
• Works in user prompts and tool outputs
• Multiple tags per message allowed
• Multiline content supported

Use Cases

Sensitive Information:

<private>
Error: Database connection failed
Host: internal-db-prod.company.com
Port: 5432
User: admin_user
</private>

Temporary Context:

<private>
Deadline: Friday 5pm
Contact: [e-mail]
</private>

Debug Output:

<private>
[DEBUG] Full stack trace...
[DEBUG] Memory dump...
</private>

Verification

# Check that private content was filtered
sqlite3 ~/.claude-mem/claude-mem.db "SELECT prompt_text FROM user_prompts LIMIT 5;"
sqlite3 ~/.claude-mem/claude-mem.db "SELECT narrative FROM observations LIMIT 5;"

Data Storage

Database Location

Default: ~/.claude-mem/

• claude-mem.db - SQLite database
• .worker.pid - Worker process ID
• logs/worker-YYYY-MM-DD.log - Daily logs
• settings.json - Configuration

Database Queries

-- Recent sessions
SELECT session_id, project, created_at, status
FROM sdk_sessions
ORDER BY created_at DESC LIMIT 10;

-- Search observations
SELECT title, type, created_at
FROM observations
WHERE project = 'my-project';

Worker Management

npm run worker:start    # Start background service
npm run worker:stop     # Stop service
npm run worker:restart  # Restart service
npm run worker:status   # Check status
npm run worker:logs     # View logs

Multi-Prompt Sessions

Sessions span multiple prompts:

• Total prompt count tracked
• Individual prompt identification
• Cross-prompt observation linking
• /clear doesn't terminate session (continues with new prompt number)

Troubleshooting

Worker Not Starting

# Check port availability
lsof -i :37777

# Use alternative port
export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart

No Context Appearing

# Verify hooks installed
cat plugin/hooks/hooks.json

# Check database has data
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"

# View worker logs
npm run worker:logs

High Token Usage

# Reduce observations
export CLAUDE_MEM_CONTEXT_OBSERVATIONS=25

# Use chill mode
export CLAUDE_MEM_MODE="code--chill"

Database Issues

# Backup and recreate
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.bak
rm ~/.claude-mem/claude-mem.db
npm run worker:restart

Best Practices

1. Start simple - Use default settings initially
2. Tune observations - Adjust CLAUDE_MEM_CONTEXT_OBSERVATIONS based on project size
3. Use private tags - Protect credentials and sensitive data
4. Review periodically - Check stored observations match expectations
5. Use chill mode - For projects with high activity but few critical insights
6. Search first - Use MCP tools before asking general questions

Version History

• v9.0.0 - Folder context files, git worktree support, configurable limits
• v7.1.0 - Bun replaces PM2, bun:sqlite replaces better-sqlite3
• v7.0.0 - 11 configuration settings, dual privacy tags
• v5.4.0 - Skill-based search (~2,250 tokens saved per session)

Resources

• Documentation: https://docs.claude-mem.ai
• GitHub: https://github.com/thedotmack/claude-mem
• Changelog: https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md
• Web Viewer: http://localhost:37777 (when running)