GitHub Trending Repositories

thedotmack/claude-mem

Author: thedotmack

Stars: 779 stars today

Description: A Claude Code plugin that automatically captures everything Claude does during your coding sessions, compresses it with AI (using Claude's agent-sdk), and injects relevant context back into future sessions.

README


Claude-Mem

Persistent memory compression system built for Claude Code.

License Version Node Mentioned in Awesome Claude Code


Claude-Mem Preview

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.

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:

Documentation

📚 View Full Documentation - Browse markdown docs on GitHub

💻 Local Preview: Run Mintlify docs locally:

bash cd docs npx mintlify dev

Getting Started

Best Practices

Architecture

Configuration & Development

How It Works

┌─────────────────────────────────────────────────────────────┐ │ Session Start → Inject recent observations as context │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 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, not a lifecycle hook)
  3. Worker Service - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by PM2
  4. SQLite Database - Stores sessions, observations, summaries with FTS5 full-text search
  5. mem-search Skill - Natural language queries with progressive disclosure (~2,250 token savings vs MCP)
  6. Chroma Vector Database - Hybrid semantic + keyword search for intelligent context retrieval

See Architecture Overview for details.

mem-search Skill

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 - ~2,250 token savings per session start vs MCP approach

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.

Beta Features & Endless Mode

Claude-Mem offers a beta channel with experimental features. Switch between stable and beta versions directly from the web viewer UI.

How to Try Beta

  1. Open http://localhost:37777
  2. Click Settings (gear icon)
  3. In Version Channel, click "Try Beta (Endless Mode)"
  4. Wait for the worker to restart

Your memory data is preserved when switching versions.

Endless Mode (Beta)

The flagship beta feature is Endless Mode - a biomimetic memory architecture that dramatically extends session length:

The Problem: Standard Claude Code sessions hit context limits after ~50 tool uses. Each tool adds 1-10k+ tokens, and Claude re-synthesizes all previous outputs on every response (O(N²) complexity).

The Solution: Endless Mode compresses tool outputs into ~500-token observations and transforms the transcript in real-time:

Working Memory (Context): Compressed observations (~500 tokens each) Archive Memory (Disk): Full tool outputs preserved for recall

Expected Results: - ~95% token reduction in context window - ~20x more tool uses before context exhaustion - Linear O(N) scaling instead of quadratic O(N²) - Full transcripts preserved for perfect recall

Caveats: Adds latency (60-90s per tool for observation generation), still experimental.

See Beta Features Documentation for details.

What's New

v6.4.9 - Context Configuration Settings: - 11 new settings for fine-grained control over context injection - Configure token economics display, observation filtering by type/concept - Control number of observations and which fields to display

v6.4.0 - Dual-Tag Privacy System: - <private> tags for user-controlled privacy - wrap sensitive content to exclude from storage - System-level <claude-mem-context> tags prevent recursive observation storage - Edge processing ensures private content never reaches database

v6.3.0 - Version Channel: - Switch between stable and beta versions from the web viewer UI - Try experimental features like Endless Mode without manual git operations

Previous Highlights: - v6.0.0: Major session management & transcript processing improvements - v5.5.0: mem-search skill enhancement with 100% effectiveness rate - v5.4.0: Skill-based search architecture (~2,250 tokens saved per session) - v5.1.0: Web-based viewer UI with real-time updates - v5.0.0: Hybrid search with Chroma vector database

See CHANGELOG.md for complete version history.

System Requirements

Key Benefits

Progressive Disclosure Context

Automatic Memory

Full History Search

Structured Observations

Multi-Prompt Sessions

Configuration

Settings are managed in ~/.claude-mem/settings.json. The file is auto-created with defaults on first run.

Available Settings:

| Setting | Default | Description | |---------|---------|-------------| | CLAUDE_MEM_MODEL | claude-haiku-4-5 | AI model for observations | | CLAUDE_MEM_WORKER_PORT | 37777 | Worker service port | | CLAUDE_MEM_DATA_DIR | ~/.claude-mem | Data directory location | | CLAUDE_MEM_LOG_LEVEL | INFO | Log verbosity (DEBUG, INFO, WARN, ERROR, SILENT) | | CLAUDE_MEM_PYTHON_VERSION | 3.13 | Python version for chroma-mcp | | CLAUDE_CODE_PATH | (auto-detect) | Path to Claude executable | | CLAUDE_MEM_CONTEXT_OBSERVATIONS | 50 | Number of observations to inject at SessionStart |

Settings Management:

```bash

Edit settings via CLI helper

./claude-mem-settings.sh

Or edit directly

nano ~/.claude-mem/settings.json

View current settings

curl http://localhost:37777/api/settings ```

Settings File Format:

json { "CLAUDE_MEM_MODEL": "claude-haiku-4-5", "CLAUDE_MEM_WORKER_PORT": "37777", "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "50" }

See Configuration Guide for details.

Development

```bash

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

Quick Diagnostic:

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

Common Issues:

See Troubleshooting Guide for complete solutions.

Contributing

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.

License

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:

Support

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

File Structure

Unable to fetch file structure.

Back to Trending