🇨🇳 中文 • 🇯🇵 日本語 • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk

Quick Start • How It Works • Search Tools • Documentation • Configuration • Troubleshooting • License

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.

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
• 🔍 Skill-Based Search - Query your project history with mem-search skill
• 🖥️ Web Viewer UI - Real-time memory stream at https://localhost:37777
• 💻 Claude Desktop Skill - Search memory from Claude Desktop conversations
• 🔒 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
• 🔗 Citations - Reference past observations with IDs (access via https://localhost:37777/api/observation/{id} or view all in the web viewer at https://localhost:37777)
• 🧪 Beta Channel - Try experimental features like Endless Mode via version switching

📚 View Full Documentation - Browse markdown docs on GitHub

• Installation Guide - Quick start & advanced installation
• Usage Guide - How Claude-Mem works automatically
• Search Tools - Query your project history with natural language
• Beta Features - Try experimental features like Endless Mode

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

• Overview - System components & data flow
• Architecture Evolution - The journey from v3 to v5
• Hooks Architecture - How Claude-Mem uses lifecycle hooks
• Hooks Reference - 7 hook scripts explained
• Worker Service - HTTP API & Bun management
• Database - SQLite schema & FTS5 search
• Search Architecture - Hybrid search with Chroma vector database

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

Core Components:

1. 5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
2. Smart Install - Cached dependency checker (pre-hook script, not a lifecycle hook)
3. Worker Service - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun
4. SQLite Database - Stores sessions, observations, summaries
5. mem-search Skill - Natural language queries with progressive disclosure
6. Chroma Vector Database - Hybrid semantic + keyword search for intelligent context retrieval

See Architecture Overview for details.

Claude-Mem provides intelligent search through the mem-search skill that auto-invokes when you ask about past work:

How It Works:

• Just ask naturally: "What did we do last session?" or "Did we fix this bug before?"
• Claude automatically invokes the mem-search skill to find relevant context

Available Search Operations:

1. Search Observations - Full-text search across observations
2. Search Sessions - Full-text search across session summaries
3. Search Prompts - Search raw user requests
4. By Concept - Find by concept tags (discovery, problem-solution, pattern, etc.)
5. By File - Find observations referencing specific files
6. By Type - Find by type (decision, bugfix, feature, refactor, discovery, change)
7. Recent Context - Get recent session context for a project
8. Timeline - Get unified timeline of context around a specific point in time
9. Timeline by Query - Search for observations and get timeline context around best match
10. API Help - Get search API documentation

Example Natural Language Queries:

"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"

See Search Tools Guide for detailed examples.

Claude-Mem offers a beta channel with experimental features like Endless Mode (biomimetic memory architecture for extended sessions). Switch between stable and beta versions from the web viewer UI at https://localhost:37777 → Settings.

See Beta Features Documentation for details on Endless Mode and how to try it.

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

Settings are managed in ~/.claude-mem/settings.json (auto-created with defaults on first run). Configure AI model, worker port, data directory, log level, and context injection settings.

See the Configuration Guide for all available settings and examples.

See the Development Guide for build instructions, testing, and contribution workflow.

If experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically diagnose and provide fixes.

See the Troubleshooting Guide for common issues and solutions.

Create comprehensive bug reports with the automated generator:

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Update documentation
5. Submit a Pull Request

See Development Guide for contribution workflow.

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

Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.

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

Note on Ragtime: The ragtime/ directory is licensed separately under the PolyForm Noncommercial License 1.0.0. See ragtime/LICENSE for details.

• 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