Persistent memory compression system built for Claude Code. Gives your AI agent long-term memory across sessions with automatic context compression and retrieval.
Add this skill
npx mdskills install thedotmack/claude-memSophisticated persistent memory system with semantic search, progressive disclosure, and well-architected hook system
1<p align="center">2 Official $CMEM Links:3 <a href="https://bags.fm/2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS">Bags.fm</a> •4 <a href="https://jup.ag/tokens/2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS">Jupiter</a> •5 <a href="https://photon-sol.tinyastro.io/en/lp/6MzFAkWnac6GSK1EdFX93dZeukGfzrFq4UHWarhGSQyd">Photon</a> •6 <a href="https://dexscreener.com/solana/6mzfakwnac6gsk1edfx93dzeukgfzrfq4uhwarhgsqyd">DEXScreener</a>7</p>89<p align="center">Official CA: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS (on Solana)</p>1011<h1 align="center">12 <br>13 <a href="https://github.com/thedotmack/claude-mem">14 <picture>15 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">16 <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">17 <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">18 </picture>19 </a>20 <br>21</h1>2223<p align="center">24 <a href="docs/i18n/README.zh.md">🇨🇳 中文</a> •25 <a href="docs/i18n/README.zh-tw.md">🇹🇼 繁體中文</a> •26 <a href="docs/i18n/README.ja.md">🇯🇵 日本語</a> •27 <a href="docs/i18n/README.pt.md">🇵🇹 Português</a> •28 <a href="docs/i18n/README.pt-br.md">🇧🇷 Português</a> •29 <a href="docs/i18n/README.ko.md">🇰🇷 한국어</a> •30 <a href="docs/i18n/README.es.md">🇪🇸 Español</a> •31 <a href="docs/i18n/README.de.md">🇩🇪 Deutsch</a> •32 <a href="docs/i18n/README.fr.md">🇫🇷 Français</a> •33 <a href="docs/i18n/README.he.md">🇮🇱 עברית</a> •34 <a href="docs/i18n/README.ar.md">🇸🇦 العربية</a> •35 <a href="docs/i18n/README.ru.md">🇷🇺 Русский</a> •36 <a href="docs/i18n/README.pl.md">🇵🇱 Polski</a> •37 <a href="docs/i18n/README.cs.md">🇨🇿 Čeština</a> •38 <a href="docs/i18n/README.nl.md">🇳🇱 Nederlands</a> •39 <a href="docs/i18n/README.tr.md">🇹🇷 Türkçe</a> •40 <a href="docs/i18n/README.uk.md">🇺🇦 Українська</a> •41 <a href="docs/i18n/README.vi.md">🇻🇳 Tiếng Việt</a> •42 <a href="docs/i18n/README.tl.md">🇵🇭 Tagalog</a> •43 <a href="docs/i18n/README.id.md">🇮🇩 Indonesia</a> •44 <a href="docs/i18n/README.th.md">🇹🇭 ไทย</a> •45 <a href="docs/i18n/README.hi.md">🇮🇳 हिन्दी</a> •46 <a href="docs/i18n/README.bn.md">🇧🇩 বাংলা</a> •47 <a href="docs/i18n/README.ur.md">🇵🇰 اردو</a> •48 <a href="docs/i18n/README.ro.md">🇷🇴 Română</a> •49 <a href="docs/i18n/README.sv.md">🇸🇪 Svenska</a> •50 <a href="docs/i18n/README.it.md">🇮🇹 Italiano</a> •51 <a href="docs/i18n/README.el.md">🇬🇷 Ελληνικά</a> •52 <a href="docs/i18n/README.hu.md">🇭🇺 Magyar</a> •53 <a href="docs/i18n/README.fi.md">🇫🇮 Suomi</a> •54 <a href="docs/i18n/README.da.md">🇩🇰 Dansk</a> •55 <a href="docs/i18n/README.no.md">🇳🇴 Norsk</a>56</p>5758<h4 align="center">Persistent memory compression system built for <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>5960<p align="center">61 <a href="LICENSE">62 <img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">63 </a>64 <a href="package.json">65 <img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">66 </a>67 <a href="package.json">68 <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">69 </a>70 <a href="https://github.com/thedotmack/awesome-claude-code">71 <img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">72 </a>73</p>7475<p align="center">76 <a href="https://trendshift.io/repositories/15496" target="_blank">77 <picture>78 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">79 <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">80 <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>81 </picture>82 </a>83</p>8485<br>8687<p align="center">88 <a href="https://github.com/thedotmack/claude-mem">89 <picture>90 <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">91 </picture>92 </a>93</p>9495<p align="center">96 <a href="#quick-start">Quick Start</a> •97 <a href="#how-it-works">How It Works</a> •98 <a href="#mcp-search-tools">Search Tools</a> •99 <a href="#documentation">Documentation</a> •100 <a href="#configuration">Configuration</a> •101 <a href="#troubleshooting">Troubleshooting</a> •102 <a href="#license">License</a>103</p>104105<p align="center">106 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.107</p>108109---110111## Quick Start112113Start a new Claude Code session in the terminal and enter the following commands:114115```116/plugin marketplace add thedotmack/claude-mem117118/plugin install claude-mem119```120121Restart Claude Code. Context from previous sessions will automatically appear in new sessions.122123> **Note:** Claude-Mem is also published on npm, but `npm install -g claude-mem` installs the **SDK/library only** — it does not register the plugin hooks or set up the worker service. To use Claude-Mem as a plugin, always install via the `/plugin` commands above.124125### 🦞 OpenClaw Gateway126127Install claude-mem as a persistent memory plugin on [OpenClaw](https://openclaw.ai) gateways with a single command:128129```bash130curl -fsSL https://install.cmem.ai/openclaw.sh | bash131```132133The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more. See the [OpenClaw Integration Guide](https://docs.claude-mem.ai/openclaw-integration) for details.134135**Key Features:**136137- 🧠 **Persistent Memory** - Context survives across sessions138- 📊 **Progressive Disclosure** - Layered memory retrieval with token cost visibility139- 🔍 **Skill-Based Search** - Query your project history with mem-search skill140- 🖥️ **Web Viewer UI** - Real-time memory stream at http://localhost:37777141- 💻 **Claude Desktop Skill** - Search memory from Claude Desktop conversations142- 🔒 **Privacy Control** - Use `<private>` tags to exclude sensitive content from storage143- ⚙️ **Context Configuration** - Fine-grained control over what context gets injected144- 🤖 **Automatic Operation** - No manual intervention required145- 🔗 **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)146- 🧪 **Beta Channel** - Try experimental features like Endless Mode via version switching147148---149150## Documentation151152📚 **[View Full Documentation](https://docs.claude-mem.ai/)** - Browse on official website153154### Getting Started155156- **[Installation Guide](https://docs.claude-mem.ai/installation)** - Quick start & advanced installation157- **[Usage Guide](https://docs.claude-mem.ai/usage/getting-started)** - How Claude-Mem works automatically158- **[Search Tools](https://docs.claude-mem.ai/usage/search-tools)** - Query your project history with natural language159- **[Beta Features](https://docs.claude-mem.ai/beta-features)** - Try experimental features like Endless Mode160161### Best Practices162163- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - AI agent context optimization principles164- **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Philosophy behind Claude-Mem's context priming strategy165166### Architecture167168- **[Overview](https://docs.claude-mem.ai/architecture/overview)** - System components & data flow169- **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - The journey from v3 to v5170- **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - How Claude-Mem uses lifecycle hooks171- **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts explained172- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun management173- **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema & FTS5 search174- **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search with Chroma vector database175176### Configuration & Development177178- **[Configuration](https://docs.claude-mem.ai/configuration)** - Environment variables & settings179- **[Development](https://docs.claude-mem.ai/development)** - Building, testing, contributing180- **[Troubleshooting](https://docs.claude-mem.ai/troubleshooting)** - Common issues & solutions181182---183184## How It Works185186**Core Components:**1871881. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)1892. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook)1903. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun1914. **SQLite Database** - Stores sessions, observations, summaries1925. **mem-search Skill** - Natural language queries with progressive disclosure1936. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval194195See [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) for details.196197---198199## MCP Search Tools200201Claude-Mem provides intelligent memory search through **5 MCP tools** following a token-efficient **3-layer workflow pattern**:202203**The 3-Layer Workflow:**2042051. **`search`** - Get compact index with IDs (~50-100 tokens/result)2062. **`timeline`** - Get chronological context around interesting results2073. **`get_observations`** - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result)208209**How It Works:**210- Claude uses MCP tools to search your memory211- Start with `search` to get an index of results212- Use `timeline` to see what was happening around specific observations213- Use `get_observations` to fetch full details for relevant IDs214- Use `save_memory` to manually store important information215- **~10x token savings** by filtering before fetching details216217**Available MCP Tools:**2182191. **`search`** - Search memory index with full-text queries, filters by type/date/project2202. **`timeline`** - Get chronological context around a specific observation or query2213. **`get_observations`** - Fetch full observation details by IDs (always batch multiple IDs)2224. **`save_memory`** - Manually save a memory/observation for semantic search2235. **`__IMPORTANT`** - Workflow documentation (always visible to Claude)224225**Example Usage:**226227```typescript228// Step 1: Search for index229search(query="authentication bug", type="bugfix", limit=10)230231// Step 2: Review index, identify relevant IDs (e.g., #123, #456)232233// Step 3: Fetch full details234get_observations(ids=[123, 456])235236// Save important information manually237save_memory(text="API requires auth header X-API-Key", title="API Auth")238```239240See [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) for detailed examples.241242---243244## Beta Features245246Claude-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.247248See **[Beta Features Documentation](https://docs.claude-mem.ai/beta-features)** for details on Endless Mode and how to try it.249250---251252## System Requirements253254- **Node.js**: 18.0.0 or higher255- **Claude Code**: Latest version with plugin support256- **Bun**: JavaScript runtime and process manager (auto-installed if missing)257- **uv**: Python package manager for vector search (auto-installed if missing)258- **SQLite 3**: For persistent storage (bundled)259260---261### Windows Setup Notes262263If you see an error like:264265```powershell266npm : The term 'npm' is not recognized as the name of a cmdlet267```268269Make sure Node.js and npm are installed and added to your PATH. Download the latest Node.js installer from https://nodejs.org and restart your terminal after installation.270271---272273## Configuration274275Settings 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.276277See the **[Configuration Guide](https://docs.claude-mem.ai/configuration)** for all available settings and examples.278279---280281## Development282283See the **[Development Guide](https://docs.claude-mem.ai/development)** for build instructions, testing, and contribution workflow.284285---286287## Troubleshooting288289If experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically diagnose and provide fixes.290291See the **[Troubleshooting Guide](https://docs.claude-mem.ai/troubleshooting)** for common issues and solutions.292293---294295## Bug Reports296297Create comprehensive bug reports with the automated generator:298299```bash300cd ~/.claude/plugins/marketplaces/thedotmack301npm run bug-report302```303304## Contributing305306Contributions are welcome! Please:3073081. Fork the repository3092. Create a feature branch3103. Make your changes with tests3114. Update documentation3125. Submit a Pull Request313314See [Development Guide](https://docs.claude-mem.ai/development) for contribution workflow.315316---317318## License319320This project is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0).321322Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.323324See the [LICENSE](LICENSE) file for full details.325326**What This Means:**327328- You can use, modify, and distribute this software freely329- If you modify and deploy on a network server, you must make your source code available330- Derivative works must also be licensed under AGPL-3.0331- There is NO WARRANTY for this software332333**Note on Ragtime**: The `ragtime/` directory is licensed separately under the **PolyForm Noncommercial License 1.0.0**. See [ragtime/LICENSE](ragtime/LICENSE) for details.334335---336337## Support338339- **Documentation**: [docs/](docs/)340- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)341- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)342- **Official X Account**: [@Claude_Memory](https://x.com/Claude_Memory)343- **Official Discord**: [Join Discord](https://discord.com/invite/J4wttp9vDu)344- **Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack))345346---347348**Built with Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**349
Full transparency — inspect the skill content before installing.