claude-mem

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
📊 Progressive Disclosure - Layered memory retrieval with token cost visibility
🔍 7 Search Tools - Query your project history via MCP
🤖 Automatic Operation - No manual intervention required
🔗 Citations - Reference past decisions with claude-mem:// URIs

Documentation

📚 View Full Documentation - Browse markdown docs on GitHub

💻 Local Preview: Run Mintlify docs locally:

cd docs
npx mintlify dev

Getting Started

Installation Guide - Quick start & advanced installation
Usage Guide - How Claude-Mem works automatically
MCP Search Tools - Query your project history

Best Practices

Context Engineering - AI agent context optimization principles
Progressive Disclosure - Philosophy behind Claude-Mem's context priming strategy

Architecture

Overview - System components & data flow
Architecture Evolution - The journey from v3 to v4
Hooks Architecture - How Claude-Mem uses lifecycle hooks
Hooks Reference - 5 lifecycle hooks explained
Worker Service - HTTP API & PM2 management
Database - SQLite schema & FTS5 search
MCP Search - 7 search tools & examples

Configuration & Development

Configuration - Environment variables & settings
Development - Building, testing, contributing
Troubleshooting - Common issues & solutions

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:

5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd
Worker Service - HTTP API on port 37777 managed by PM2
SQLite Database - Stores sessions, observations, summaries with FTS5 search
7 MCP Search Tools - Query historical context with citations

See Architecture Overview for details.

MCP Search Tools

Claude-Mem provides 7 specialized search tools:

search_observations - Full-text search across observations
search_sessions - Full-text search across session summaries
search_user_prompts - Search raw user requests
find_by_concept - Find by concept tags
find_by_file - Find by file references
find_by_type - Find by type (decision, bugfix, feature, etc.)
get_recent_context - Get recent session context

Example Queries:

search_observations with query="authentication" and type="decision"
find_by_file with filePath="worker-service.ts"
search_user_prompts with query="add dark mode"
get_recent_context with limit=5

See MCP Search Tools Guide for detailed examples.

What's New in v4.3.1

Critical Fix:

SessionStart hook context injection: Fixed context not being injected into new sessions
- npm install output was polluting hook JSON responses
- Changed npm loglevel to --loglevel=silent for clean output
- Context injection now works reliably across all sessions

Code Quality:

Consolidated hooks architecture by removing wrapper layer
Fixed double shebang issues in hook executables
Simplified codebase maintenance

See CHANGELOG.md for complete version history.

System Requirements

Node.js: 18.0.0 or higher
Claude Code: Latest version with plugin support
PM2: Process manager (bundled - no global install required)
SQLite 3: For persistent storage (bundled)

Key Benefits

Progressive Disclosure Context

Layered memory retrieval mirrors human memory patterns
Layer 1 (Index): See what observations exist with token costs at session start
Layer 2 (Details): Fetch full narratives on-demand via MCP search
Layer 3 (Perfect Recall): Access source code and original transcripts
Smart decision-making: Token counts help Claude choose between fetching details or reading code
Type indicators: Visual cues (🔴 critical, 🟤 decision, 🔵 informational) highlight observation importance

Automatic Memory

Context automatically injected when Claude starts
No manual commands or configuration needed
Works transparently in the background

Full History Search

Search across all sessions and observations
FTS5 full-text search for fast queries
Citations link back to specific observations

Structured Observations

AI-powered extraction of learnings
Categorized by type (decision, bugfix, feature, etc.)
Tagged with concepts and file references

Multi-Prompt Sessions

Sessions span multiple user prompts
Context preserved across /clear commands
Track entire conversation threads

Configuration

Model Selection:

./claude-mem-settings.sh

Environment Variables:

CLAUDE_MEM_MODEL - AI model for processing (default: claude-sonnet-4-5)
CLAUDE_MEM_WORKER_PORT - Worker port (default: 37777)
CLAUDE_MEM_DATA_DIR - Data directory override (dev only)

See Configuration Guide for details.

Development

# Clone and build
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
npm install
npm run build

# Run tests
npm test

# Start worker
npm run worker:start

# View logs
npm run worker:logs

See Development Guide for detailed instructions.

Troubleshooting

Common Issues:

Worker not starting → npm run worker:restart
No context appearing → npm run test:context
Database issues → sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
Search not working → Check FTS5 tables exist

See Troubleshooting Guide for complete solutions.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Update documentation
Submit a Pull Request

See Development Guide for contribution workflow.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See the LICENSE file for full details.

What This Means:

You can use, modify, and distribute this software freely
If you modify and deploy on a network server, you must make your source code available
Derivative works must also be licensed under AGPL-3.0
There is NO WARRANTY for this software

Support

Documentation: docs/
Issues: GitHub Issues
Repository: github.com/thedotmack/claude-mem
Author: Alex Newman (@thedotmack)

Built with Claude Agent SDK | Powered by Claude Code | Made with TypeScript

Languages

TypeScript 48.4%

JavaScript 45%

Shell 3.3%

HTML 2.5%

Python 0.7%