Official $CMEM Links: Bags.fm • Jupiter • Photon • DEXScreener

Official CA: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS (on Solana)

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

Magic-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 doublefx/magic-claude-mem

> /plugin install magic-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)

📚 View Full Documentation - Browse markdown docs on GitHub

• Installation Guide - Quick start & advanced installation
• Usage Guide - How Magic-Claude-Mem works automatically
• Search Tools - Query your project history with natural language

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

• Overview - System components & data flow
• Architecture Evolution - The journey from v3 to v5
• Hooks Architecture - How Magic-Claude-Mem uses lifecycle hooks
• Hooks Reference - 7 hook scripts explained
• Worker Service - HTTP API & Node.js 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 Node.js
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.

Magic-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.

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

Settings are managed in ~/.magic-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/doublefx
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) 2026 Frederic Thomas ([email protected]). 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

• Documentation: docs/
• Issues: GitHub Issues
• Repository: github.com/doublefx/magic-claude-mem
• Official X Account: @Claude_Memory
• Official Discord: Join Discord
• Author: Frederic Thomas ([email protected])

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