Full Text
# GitHub - 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. · GitHub
[Skip to content](https://github.com/thedotmack/claude-mem#start-of-content)
## Navigation Menu
Toggle navigation
[](https://github.com/)
[Sign in](https://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fthedotmack%2Fclaude-mem)
Appearance settings
*
Platform
*
AI CODE CREATION
* [GitHub Copilot Write better code with AI](https://github.com/features/copilot)
* [GitHub Spark Build and deploy intelligent apps](https://github.com/features/spark)
* [GitHub Models Manage and compare prompts](https://github.com/features/models)
* [MCP Registry New Integrate external tools](https://github.com/mcp)
*
DEVELOPER WORKFLOWS
* [Actions Automate any workflow](https://github.com/features/actions)
* [Codespaces Instant dev environments](https://github.com/features/codespaces)
* [Issues Plan and track work](https://github.com/features/issues)
* [Code Review Manage code changes](https://github.com/features/code-review)
*
APPLICATION SECURITY
* [GitHub Advanced Security Find and fix vulnerabilities](https://github.com/security/advanced-security)
* [Code security Secure your code as you build](https://github.com/security/advanced-security/code-security)
* [Secret protection Stop leaks before they start](https://github.com/security/advanced-security/secret-protection)
*
EXPLORE
* [Why GitHub](https://github.com/why-github)
* [Documentation](https://docs.github.com/)
* [Blog](https://github.blog/)
* [Changelog](https://github.blog/changelog)
* [Marketplace](https://github.com/marketplace)
[View all features](https://github.com/features)
*
Solutions
*
BY COMPANY SIZE
* [Enterprises](https://github.com/enterprise)
* [Small and medium teams](https://github.com/team)
* [Startups](https://github.com/enterprise/startups)
* [Nonprofits](https://github.com/solutions/industry/nonprofits)
*
BY USE CASE
* [App Modernization](https://github.com/solutions/use-case/app-modernization)
* [DevSecOps](https://github.com/solutions/use-case/devsecops)
* [DevOps](https://github.com/solutions/use-case/devops)
* [CI/CD](https://github.com/solutions/use-case/ci-cd)
* [View all use cases](https://github.com/solutions/use-case)
*
BY INDUSTRY
* [Healthcare](https://github.com/solutions/industry/healthcare)
* [Financial services](https://github.com/solutions/industry/financial-services)
* [Manufacturing](https://github.com/solutions/industry/manufacturing)
* [Government](https://github.com/solutions/industry/government)
* [View all industries](https://github.com/solutions/industry)
[View all solutions](https://github.com/solutions)
*
Resources
*
EXPLORE BY TOPIC
* [AI](https://github.com/resources/articles?topic=ai)
* [Software Development](https://github.com/resources/articles?topic=software-development)
* [DevOps](https://github.com/resources/articles?topic=devops)
* [Security](https://github.com/resources/articles?topic=security)
* [View all topics](https://github.com/resources/articles)
*
EXPLORE BY TYPE
* [Customer stories](https://github.com/customer-stories)
* [Events & webinars](https://github.com/resources/events)
* [Ebooks & reports](https://github.com/resources/whitepapers)
* [Business insights](https://github.com/solutions/executive-insights)
* [GitHub Skills](https://skills.github.com/)
*
SUPPORT & SERVICES
* [Documentation](https://docs.github.com/)
* [Customer support](https://support.github.com/)
* [Community forum](https://github.com/orgs/community/discussions)
* [Trust center](https://github.com/trust-center)
* [Partners](https://github.com/partners)
[View all resources](https://github.com/resources)
*
Open Source
*
COMMUNITY
* [GitHub Sponsors Fund open source developers](https://github.com/sponsors)
*
PROGRAMS
* [Security Lab](https://securitylab.github.com/)
* [Maintainer Community](https://maintainers.github.com/)
* [Accelerator](https://github.com/accelerator)
* [GitHub Stars](https://stars.github.com/)
* [Archive Program](https://archiveprogram.github.com/)
*
REPOSITORIES
* [Topics](https://github.com/topics)
* [Trending](https://github.com/trending)
* [Collections](https://github.com/collections)
*
Enterprise
*
ENTERPRISE SOLUTIONS
* [Enterprise platform AI-powered developer platform](https://github.com/enterprise)
*
AVAILABLE ADD-ONS
* [GitHub Advanced Security Enterprise-grade security features](https://github.com/security/advanced-security)
* [Copilot for Business Enterprise-grade AI features](https://github.com/features/copilot/copilot-business)
* [Premium Support Enterprise-grade 24/7 support](https://github.com/premium-support)
* [Pricing](https://github.com/pricing)
Search or jump to...
# Search code, repositories, users, issues, pull requests...
Search
Clear
[Search syntax tips](https://docs.github.com/search-github/github-code-search/understanding-github-code-search-syntax)
# Provide feedback
We read every piece of feedback, and take your input very seriously.
- [x] Include my email address so I can be contacted
Cancel Submit feedback
# Saved searches
## Use saved searches to filter your results more quickly
Name
Query
To see all available qualifiers, see our [documentation](https://docs.github.com/search-github/github-code-search/understanding-github-code-search-syntax).
Cancel Create saved search
[Sign in](https://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fthedotmack%2Fclaude-mem)
[Sign up](https://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E&source=header-repo&source_repo=thedotmack%2Fclaude-mem)
Appearance settings
Resetting focus
You signed in with another tab or window. [Reload](https://github.com/thedotmack/claude-mem) to refresh your session.You signed out in another tab or window. [Reload](https://github.com/thedotmack/claude-mem) to refresh your session.You switched accounts on another tab or window. [Reload](https://github.com/thedotmack/claude-mem) to refresh your session.Dismiss alert
{{ message }}
[thedotmack](https://github.com/thedotmack)/**[claude-mem](https://github.com/thedotmack/claude-mem)**Public
* ### Uh oh!
There was an error while loading. [Please reload this page](https://github.com/thedotmack/claude-mem).
* [Notifications](https://github.com/login?return_to=%2Fthedotmack%2Fclaude-mem)You must be signed in to change notification settings
* [Fork 3k](https://github.com/login?return_to=%2Fthedotmack%2Fclaude-mem)
* [Star 40.6k](https://github.com/login?return_to=%2Fthedotmack%2Fclaude-mem)
* [Code](https://github.com/thedotmack/claude-mem)
* [Issues 111](https://github.com/thedotmack/claude-mem/issues)
* [Pull requests 85](https://github.com/thedotmack/claude-mem/pulls)
* [Discussions](https://github.com/thedotmack/claude-mem/discussions)
* [Actions](https://github.com/thedotmack/claude-mem/actions)
* [Projects](https://github.com/thedotmack/claude-mem/projects)
* [Security 0](https://github.com/thedotmack/claude-mem/security)
* [Insights](https://github.com/thedotmack/claude-mem/pulse)
Additional navigation options
* [Code](https://github.com/thedotmack/claude-mem)
* [Issues](https://github.com/thedotmack/claude-mem/issues)
* [Pull requests](https://github.com/thedotmack/claude-mem/pulls)
* [Discussions](https://github.com/thedotmack/claude-mem/discussions)
* [Actions](https://github.com/thedotmack/claude-mem/actions)
* [Projects](https://github.com/thedotmack/claude-mem/projects)
* [Security](https://github.com/thedotmack/claude-mem/security)
* [Insights](https://github.com/thedotmack/claude-mem/pulse)
[](https://github.com/thedotmack/claude-mem)
# thedotmack/claude-mem
main
[Branches](https://github.com/thedotmack/claude-mem/branches)[Tags](https://github.com/thedotmack/claude-mem/tags)
[](https://github.com/thedotmack/claude-mem/branches)[](https://github.com/thedotmack/claude-mem/tags)
Go to file
Code
Open more actions menu
## Folders and files
| Name | Name | Last commit message | Last commit date |
| --- | --- | --- | --- |
| ## Latest commit ## History [1,493 Commits](https://github.com/thedotmack/claude-mem/commits/main/) [](https://github.com/thedotmack/claude-mem/commits/main/)1,493 Commits |
| [.claude-plugin](https://github.com/thedotmack/claude-mem/tree/main/.claude-plugin ".claude-plugin") | [.claude-plugin](https://github.com/thedotmack/claude-mem/tree/main/.claude-plugin ".claude-plugin") | | |
| [.claude](https://github.com/thedotmack/claude-mem/tree/main/.claude ".claude") | [.claude](https://github.com/thedotmack/claude-mem/tree/main/.claude ".claude") | | |
| [.github](https://github.com/thedotmack/claude-mem/tree/main/.github ".github") | [.github](https://github.com/thedotmack/claude-mem/tree/main/.github ".github") | | |
| [.plan](https://github.com/thedotmack/claude-mem/tree/main/.plan ".plan") | [.plan](https://github.com/thedotmack/claude-mem/tree/main/.plan ".plan") | | |
| [cursor-hooks](https://github.com/thedotmack/claude-mem/tree/main/cursor-hooks "cursor-hooks") | [cursor-hooks](https://github.com/thedotmack/claude-mem/tree/main/cursor-hooks "cursor-hooks") | | |
| [docs](https://github.com/thedotmack/claude-mem/tree/main/docs "docs") | [docs](https://github.com/thedotmack/claude-mem/tree/main/docs "docs") | | |
| [install](https://github.com/thedotmack/claude-mem/tree/main/install "install") | [install](https://github.com/thedotmack/claude-mem/tree/main/install "install") | | |
| [installer](https://github.com/thedotmack/claude-mem/tree/main/installer "installer") | [installer](https://github.com/thedotmack/claude-mem/tree/main/installer "installer") | | |
| [openclaw](https://github.com/thedotmack/claude-mem/tree/main/openclaw "openclaw") | [openclaw](https://github.com/thedotmack/claude-mem/tree/main/openclaw "openclaw") | | |
| [plugin](https://github.com/thedotmack/claude-mem/tree/main/plugin "plugin") | [plugin](https://github.com/thedotmack/claude-mem/tree/main/plugin "plugin") | | |
| [ragtime](https://github.com/thedotmack/claude-mem/tree/main/ragtime "ragtime") | [ragtime](https://github.com/thedotmack/claude-mem/tree/main/ragtime "ragtime") | | |
| [scripts](https://github.com/thedotmack/claude-mem/tree/main/scripts "scripts") | [scripts](https://github.com/thedotmack/claude-mem/tree/main/scripts "scripts") | | |
| [src](https://github.com/thedotmack/claude-mem/tree/main/src "src") | [src](https://github.com/thedotmack/claude-mem/tree/main/src "src") | | |
| [tests](https://github.com/thedotmack/claude-mem/tree/main/tests "tests") | [tests](https://github.com/thedotmack/claude-mem/tree/main/tests "tests") | | |
| [.gitignore](https://github.com/thedotmack/claude-mem/blob/main/.gitignore ".gitignore") | [.gitignore](https://github.com/thedotmack/claude-mem/blob/main/.gitignore ".gitignore") | | |
| [.markdownlint.json](https://github.com/thedotmack/claude-mem/blob/main/.markdownlint.json ".markdownlint.json") | [.markdownlint.json](https://github.com/thedotmack/claude-mem/blob/main/.markdownlint.json ".markdownlint.json") | | |
| [.mcp.json](https://github.com/thedotmack/claude-mem/blob/main/.mcp.json ".mcp.json") | [.mcp.json](https://github.com/thedotmack/claude-mem/blob/main/.mcp.json ".mcp.json") | | |
| [.translation-cache.json](https://github.com/thedotmack/claude-mem/blob/main/.translation-cache.json ".translation-cache.json") | [.translation-cache.json](https://github.com/thedotmack/claude-mem/blob/main/.translation-cache.json ".translation-cache.json") | | |
| [CHANGELOG.md](https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md "CHANGELOG.md") | [CHANGELOG.md](https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md "CHANGELOG.md") | | |
| [CLAUDE.md](https://github.com/thedotmack/claude-mem/blob/main/CLAUDE.md "CLAUDE.md") | [CLAUDE.md](https://github.com/thedotmack/claude-mem/blob/main/CLAUDE.md "CLAUDE.md") | | |
| [LICENSE](https://github.com/thedotmack/claude-mem/blob/main/LICENSE "LICENSE") | [LICENSE](https://github.com/thedotmack/claude-mem/blob/main/LICENSE "LICENSE") | | |
| [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md "README.md") | [README.md](https://github.com/thedotmack/claude-mem/blob/main/README.md "README.md") | | |
| [conductor.json](https://github.com/thedotmack/claude-mem/blob/main/conductor.json "conductor.json") | [conductor.json](https://github.com/thedotmack/claude-mem/blob/main/conductor.json "conductor.json") | | |
| [package.json](https://github.com/thedotmack/claude-mem/blob/main/package.json "package.json") | [package.json](https://github.com/thedotmack/claude-mem/blob/main/package.json "package.json") | | |
| [transcript-watch.example.json](https://github.com/thedotmack/claude-mem/blob/main/transcript-watch.example.json "transcript-watch.example.json") | [transcript-watch.example.json](https://github.com/thedotmack/claude-mem/blob/main/transcript-watch.example.json "transcript-watch.example.json") | | |
| [tsconfig.json](https://github.com/thedotmack/claude-mem/blob/main/tsconfig.json "tsconfig.json") | [tsconfig.json](https://github.com/thedotmack/claude-mem/blob/main/tsconfig.json "tsconfig.json") | | |
| View all files |
## Repository files navigation
* [README](https://github.com/thedotmack/claude-mem#)
* [License](https://github.com/thedotmack/claude-mem#)
# [](https://github.com/thedotmack/claude-mem)
[](https://github.com/thedotmack/claude-mem#----------------------------------)
[🇨🇳 中文](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.zh.md) • [🇹🇼 繁體中文](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.zh-tw.md) • [🇯🇵 日本語](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.ja.md) • [🇵🇹 Português](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.pt.md) • [🇧🇷 Português](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.pt-br.md) • [🇰🇷 한국어](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.ko.md) • [🇪🇸 Español](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.es.md) • [🇩🇪 Deutsch](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.de.md) • [🇫🇷 Français](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.fr.md) • [🇮🇱 עברית](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.he.md) • [🇸🇦 العربية](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.ar.md) • [🇷🇺 Русский](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.ru.md) • [🇵🇱 Polski](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.pl.md) • [🇨🇿 Čeština](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.cs.md) • [🇳🇱 Nederlands](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.nl.md) • [🇹🇷 Türkçe](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.tr.md) • [🇺🇦 Українська](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.uk.md) • [🇻🇳 Tiếng Việt](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.vi.md) • [🇵🇭 Tagalog](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.tl.md) • [🇮🇩 Indonesia](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.id.md) • [🇹🇭 ไทย](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.th.md) • [🇮🇳 हिन्दी](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.hi.md) • [🇧🇩 বাংলা](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.bn.md) • [🇵🇰 اردو](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.ur.md) • [🇷🇴 Română](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.ro.md) • [🇸🇪 Svenska](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.sv.md) • [🇮🇹 Italiano](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.it.md) • [🇬🇷 Ελληνικά](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.el.md) • [🇭🇺 Magyar](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.hu.md) • [🇫🇮 Suomi](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.fi.md) • [🇩🇰 Dansk](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.da.md) • [🇳🇴 Norsk](https://github.com/thedotmack/claude-mem/blob/main/docs/i18n/README.no.md)
#### Persistent memory compression system built for [Claude Code](https://claude.com/claude-code).
[](https://github.com/thedotmack/claude-mem#persistent-memory-compression-system-built-for-claude-code)
[](https://github.com/thedotmack/claude-mem/blob/main/LICENSE)[](https://github.com/thedotmack/claude-mem/blob/main/package.json)[](https://github.com/thedotmack/claude-mem/blob/main/package.json)[](https://github.com/thedotmack/awesome-claude-code)
[](https://trendshift.io/repositories/15496)
[](https://github.com/thedotmack/claude-mem)[](https://www.star-history.com/#thedotmack/claude-mem&Date)
[Quick Start](https://github.com/thedotmack/claude-mem#quick-start) • [How It Works](https://github.com/thedotmack/claude-mem#how-it-works) • [Search Tools](https://github.com/thedotmack/claude-mem#mcp-search-tools) • [Documentation](https://github.com/thedotmack/claude-mem#documentation) • [Configuration](https://github.com/thedotmack/claude-mem#configuration) • [Troubleshooting](https://github.com/thedotmack/claude-mem#troubleshooting) • [License](https://github.com/thedotmack/claude-mem#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
[](https://github.com/thedotmack/claude-mem#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.
> **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.
### 🦞 OpenClaw Gateway
[](https://github.com/thedotmack/claude-mem#-openclaw-gateway)
Install claude-mem as a persistent memory plugin on [OpenClaw](https://openclaw.ai/) gateways with a single command:
undefinedshell
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
undefined
The 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.
**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](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}](http://localhost:37777/api/observation/%7Bid%7D) or view all in the web viewer at [http://localhost:37777](http://localhost:37777/))
* 🧪 **Beta Channel** - Try experimental features like Endless Mode via version switching
* * *
## Documentation
[](https://github.com/thedotmack/claude-mem#documentation)
📚 **[View Full Documentation](https://docs.claude-mem.ai/)** - Browse on official website
### Getting Started
[](https://github.com/thedotmack/claude-mem#getting-started)
* **[Installation Guide](https://docs.claude-mem.ai/installation)** - Quick start & advanced installation
* **[Usage Guide](https://docs.claude-mem.ai/usage/getting-started)** - How Claude-Mem works automatically
* **[Search Tools](https://docs.claude-mem.ai/usage/search-tools)** - Query your project history with natural language
* **[Beta Features](https://docs.claude-mem.ai/beta-features)** - Try experimental features like Endless Mode
### Best Practices
[](https://github.com/thedotmack/claude-mem#best-practices)
* **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - AI agent context optimization principles
* **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Philosophy behind Claude-Mem's context priming strategy
### Architecture
[](https://github.com/thedotmack/claude-mem#architecture)
* **[Overview](https://docs.claude-mem.ai/architecture/overview)** - System components & data flow
* **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - The journey from v3 to v5
* **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - How Claude-Mem uses lifecycle hooks
* **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts explained
* **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun management
* **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema & FTS5 search
* **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search with Chroma vector database
### Configuration & Development
[](https://github.com/thedotmack/claude-mem#configuration--development)
* **[Configuration](https://docs.claude-mem.ai/configuration)** - Environment variables & settings
* **[Development](https://docs.claude-mem.ai/development)** - Building, testing, contributing
* **[Troubleshooting](https://docs.claude-mem.ai/troubleshooting)** - Common issues & solutions
* * *
## How It Works
[](https://github.com/thedotmack/claude-mem#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](https://docs.claude-mem.ai/architecture/overview) for details.
* * *
## MCP Search Tools
[](https://github.com/thedotmack/claude-mem#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)
**Example Usage:**
undefinedts
// 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])
undefined
See [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) for detailed examples.
* * *
## Beta Features
[](https://github.com/thedotmack/claude-mem#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](http://localhost:37777/) → Settings.
See **[Beta Features Documentation](https://docs.claude-mem.ai/beta-features)** for details on Endless Mode and how to try it.
* * *
## System Requirements
[](https://github.com/thedotmack/claude-mem#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)
* * *
### Windows Setup Notes
[](https://github.com/thedotmack/claude-mem#windows-setup-notes)
If you see an error like:
undefinedpowershell
npm : The term 'npm' is not recognized as the name of a cmdlet
undefined
Make sure Node.js and npm are installed and added to your PATH. Download the latest Node.js installer from [https://nodejs.org](https://nodejs.org/) and restart your terminal after installation.
* * *
## Configuration
[](https://github.com/thedotmack/claude-mem#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](https://docs.claude-mem.ai/configuration)** for all available settings and examples.
* * *
## Development
[](https://github.com/thedotmack/claude-mem#development)
See the **[Development Guide](https://docs.claude-mem.ai/development)** for build instructions, testing, and contribution workflow.
* * *
## Troubleshooting
[](https://github.com/thedotmack/claude-mem#troubleshooting)
If experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically diagnose and provide fixes.
See the **[Troubleshooting Guide](https://docs.claude-mem.ai/troubleshooting)** for common issues and solutions.
* * *
## Bug Reports
[](https://github.com/thedotmack/claude-mem#bug-reports)
Create comprehensive bug reports with the automated generator:
undefinedshell
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
undefined
## Contributing
[](https://github.com/thedotmack/claude-mem#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](https://docs.claude-mem.ai/development) for contribution workflow.
* * *
## License
[](https://github.com/thedotmack/claude-mem#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](https://github.com/thedotmack/claude-mem/blob/main/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](https://github.com/thedotmack/claude-mem/blob/main/ragtime/LICENSE) for details.
* * *
## Support
[](https://github.com/thedotmack/claude-mem#support)
* **Documentation**: [docs/](https://github.com/thedotmack/claude-mem/blob/main/docs)
* **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
* **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
* **Official X Account**: [@Claude_Memory](https://x.com/Claude_Memory)
* **Official Discord**: [Join Discord](https://discord.com/invite/J4wttp9vDu)
* **Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
* * *
**Built with Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**
* * *
### What About $CMEM?
[](https://github.com/thedotmack/claude-mem#what-about-cmem)
$CMEM is a solana token created by a 3rd party without Claude-Mem's prior consent, but officially embraced by the creator of Claude-Mem (Alex Newman, @thedotmack). The token acts as a community catalyst for growth and a vehicle for bringing real-time agent data to the developers and knowledge workers that need it most. $CMEM: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS
## About
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.
[claude-mem.ai](https://claude-mem.ai/ "https://claude-mem.ai")
### Topics
[ai](https://github.com/topics/ai "Topic: ai")[sqlite](https://github.com/topics/sqlite "Topic: sqlite")[embeddings](https://github.com/topics/embeddings "Topic: embeddings")[artificial-intelligence](https://github.com/topics/artificial-intelligence "Topic: artificial-intelligence")[ai-agents](https://github.com/topics/ai-agents "Topic: ai-agents")[claude](https://github.com/topics/claude "Topic: claude")[memory-engine](https://github.com/topics/memory-engine "Topic: memory-engine")[long-term-memory](https://github.com/topics/long-term-memory "Topic: long-term-memory")[rag](https://github.com/topics/rag "Topic: rag")[anthropic](https://github.com/topics/anthropic "Topic: anthropic")[chromadb](https://github.com/topics/chromadb "Topic: chromadb")[ai-memory](https://github.com/topics/ai-memory "Topic: ai-memory")[mem0](https://github.com/topics/mem0 "Topic: mem0")[claude-code](https://github.com/topics/claude-code "Topic: claude-code")[supermemory](https://github.com/topics/supermemory "Topic: supermemory")[openmemory](https://github.com/topics/openmemory "Topic: openmemory")[claude-agents](https://github.com/topics/claude-agents "Topic: claude-agents")[claude-agent-sdk](https://github.com/topics/claude-agent-sdk "Topic: claude-agent-sdk")[claude-code-plugin](https://github.com/topics/claude-code-plugin "Topic: claude-code-plugin")[claude-skills](https://github.com/topics/claude-skills "Topic: claude-skills")
### Resources
[Readme](https://github.com/thedotmack/claude-mem#readme-ov-file)
### License
[View license](https://github.com/thedotmack/claude-mem#License-1-ov-file)
### Uh oh!
There was an error while loading. [Please reload this page](https://github.com/thedotmack/claude-mem).
[Activity](https://github.com/thedotmack/claude-mem/activity)
### Stars
[**40.6k** stars](https://github.com/thedotmack/claude-mem/stargazers)
### Watchers
[**167** watching](https://github.com/thedotmack/claude-mem/watchers)
### Forks
[**3k** forks](https://github.com/thedotmack/claude-mem/forks)
[Report repository](https://github.com/contact/report-content?content_url=https%3A%2F%2Fgithub.com%2Fthedotmack%2Fclaude-mem&report=thedotmack+%28user%29)
## [Releases 216](https://github.com/thedotmack/claude-mem/releases)
[v10.6.2 Latest Mar 21, 2026](https://github.com/thedotmack/claude-mem/releases/tag/v10.6.2)
[+ 215 releases](https://github.com/thedotmack/claude-mem/releases)
## Sponsor this project
Sponsor
### Uh oh!
There was an error while loading. [Please reload this page](https://github.com/thedotmack/claude-mem).
[Learn more about GitHub Sponsors](https://github.com/sponsors)
## [Packages 0](https://github.com/users/thedotmack/packages?repo_name=claude-mem)
### Uh oh!
There was an error while loading. [Please reload this page](https://github.com/thedotmack/claude-mem).
## [Contributors](https://github.com/thedotmack/claude-mem/graphs/contributors)
*
*
*
### Uh oh!
There was an error while loading. [Please reload this page](https://github.com/thedotmack/claude-mem).
## Languages
* [TypeScript 80.8%](https://github.com/thedotmack/claude-mem/search?l=typescript)
* [JavaScript 13.2%](https://github.com/thedotmack/claude-mem/search?l=javascript)
* [Shell 3.0%](https://github.com/thedotmack/claude-mem/search?l=shell)
* [HTML 2.8%](https://github.com/thedotmack/claude-mem/search?l=html)
* [Python 0.2%](https://github.com/thedotmack/claude-mem/search?l=python)
## Footer
[](https://github.com/) © 2026 GitHub,Inc.
### Footer navigation
* [Terms](https://docs.github.com/site-policy/github-terms/github-terms-of-service)
* [Privacy](https://docs.github.com/site-policy/privacy-policies/github-privacy-statement)
* [Security](https://github.com/security)
* [Status](https://www.githubstatus.com/)
* [Community](https://github.community/)
* [Docs](https://docs.github.com/)
* [Contact](https://support.github.com/?tags=dotcom-footer)
* Manage cookies
* Do not share my personal information
You can’t perform that action at this time.