Skip to content
<open-source>
Oeiuwq Faith Blog OpenSource Porfolio

thedotmack/claude-mem

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.
Source code at GitHub https://claude-mem.ai
thedotmack/claude-mem.json
{
  "createdAt": "2025-08-31T20:50:03Z",
  "defaultBranch": "main",
  "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.",
  "fullName": "thedotmack/claude-mem",
  "homepage": "https://claude-mem.ai",
  "language": "TypeScript",
  "name": "claude-mem",
  "pushedAt": "2026-01-08T01:46:29Z",
  "stargazersCount": 11942,
  "topics": [
    "ai",
    "ai-agents",
    "ai-memory",
    "anthropic",
    "artificial-intelligence",
    "chromadb",
    "claude",
    "claude-agent-sdk",
    "claude-agents",
    "claude-code",
    "claude-code-plugin",
    "claude-skills",
    "embeddings",
    "long-term-memory",
    "mem0",
    "memory-engine",
    "openmemory",
    "rag",
    "sqlite",
    "supermemory"
  ],
  "updatedAt": "2026-01-08T01:56:23Z",
  "url": "https://github.com/thedotmack/claude-mem"
}


Claude-Mem

🇨🇳 中文 • 🇯🇵 日本語 • 🇧🇷 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

Persistent memory compression system built for Claude Code.

License Version Node Mentioned in Awesome Claude Code

thedotmack/claude-mem | Trendshift


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

Section titled “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
  • 🔍 Skill-Based Search - Query your project history with mem-search skill
  • 🖥️ Web Viewer UI - Real-time memory stream at http://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 http://localhost:37777/api/observation/{id} or view all in the web viewer at http://localhost:37777)
  • 🧪 Beta Channel - Try experimental features like Endless Mode via version switching

Documentation

Section titled “Documentation”

📚 [View Full Documentation]!(docs/) - Browse markdown docs on GitHub

Getting Started

Section titled “Getting Started”

Best Practices

Section titled “Best Practices”

Architecture

Section titled “Architecture”

Configuration & Development

Section titled “Configuration & Development”

How It Works

Section titled “How It Works”

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.

MCP Search Tools

Section titled “MCP Search Tools”

Claude-Mem provides intelligent memory search through 4 MCP tools following a token-efficient 3-layer workflow pattern:

The 3-Layer Workflow:

  1. search - Get compact index with IDs (~50-100 tokens/result)
  2. timeline - Get chronological context around interesting results
  3. get_observations - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result)

How It Works:

  • Claude uses MCP tools to search your memory
  • Start with search to get an index of results
  • Use timeline to see what was happening around specific observations
  • Use get_observations to fetch full details for relevant IDs
  • ~10x token savings by filtering before fetching details

Available MCP Tools:

  1. search - Search memory index with full-text queries, filters by type/date/project
  2. timeline - Get chronological context around a specific observation or query
  3. get_observations - Fetch full observation details by IDs (always batch multiple IDs)
  4. __IMPORTANT - Workflow documentation (always visible to Claude)

Example Usage:

// Step 1: Search for index
search(query="authentication bug", type="bugfix", limit=10)


// Step 2: Review index, identify relevant IDs (e.g., #123, #456)


// Step 3: Fetch full details
get_observations(ids=[123, 456])

See Search Tools Guide for detailed examples.

Beta Features

Section titled “Beta Features”

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 http://localhost:37777 → Settings.

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

System Requirements

Section titled “System Requirements”
  • 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)

Configuration

Section titled “Configuration”

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.

Development

Section titled “Development”

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

Troubleshooting

Section titled “Troubleshooting”

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.

Bug Reports

Section titled “Bug Reports”

Create comprehensive bug reports with the automated generator:

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

Contributing

Section titled “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

Section titled “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]!(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]!(ragtime/LICENSE) for details.

Support

Section titled “Support”

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