thedotmack/claude-mem

▲ 17,074 stars today★ 113,747⑂ 9,867

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions.

About thedotmack/claude-mem

thedotmack/claude-mem is an open-source project on GitHub, mainly written in TypeScript. Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI It currently holds 113,747 stars and 9,867 forks with 127 open issues, and was last pushed on 2026-11-06 (repository created 2025-08-31).

Project Overview

Git Homed tracks it on the AI Agent Skills Trending board and on the AI AI Agent Skills Trending list.

GitHub Repository Details

Repository thedotmack/claude-mem · default branch main · size 791715 KB · watchers 358 · source: GitHub REST API and repository README

README


https://github.com/thedotmack/claude-mem/blob/HEAD/Claude-Mem

https://github.com/thedotmack/claude-mem/blob/HEAD/Vercel OSS Program     https://github.com/thedotmack/claude-mem/blob/HEAD/Greptile     https://github.com/thedotmack/claude-mem/blob/HEAD/SerpApi

🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 Português • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇵🇭 Tagalog • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk

Your coding agent forgets everything between sessions. Claude-Mem remembers for it.

https://github.com/thedotmack/claude-mem/blob/HEAD/License https://github.com/thedotmack/claude-mem/blob/HEAD/Version https://github.com/thedotmack/claude-mem/blob/HEAD/Node https://github.com/thedotmack/claude-mem/blob/HEAD/Mentioned in Awesome Claude Code

https://github.com/thedotmack/claude-mem/blob/HEAD/Star History Rank https://github.com/thedotmack/claude-mem/blob/HEAD/GitHub Trending Repository of the Day


https://github.com/thedotmack/claude-mem/blob/HEAD/Claude-Mem Preview https://github.com/thedotmack/claude-mem/blob/HEAD/Star History Chart

Quick Start • How It Works • Search Tools • Documentation • Configuration • Troubleshooting • License

Every new session, your agent starts from zero. It re-reads the same files, re-asks the same questions, and walks back into mistakes you already fixed together.

Claude-Mem runs a second agent beside it that takes notes while it works. The next session starts with a short index of what matters, and pulls in the details only when it needs them. Works with Claude Code, Codex, Cursor, OpenCode and 11 more agents. Copilot CLI, Goose, Roo Code and Warp can search your memory, but their sessions aren't recorded.

---

Quick Start

Installing for someone as an AI agent? If the user is available, run npx claude-mem install --setup browser on their computer and keep it running. It prepares the local runtime, then opens setup in their browser; if the page doesn't open, give them the printed URL. Every choice (agents, integrations, skills, model, usage analytics, the optional email) is made by the user on that page, so there are no terminal questions to relay. If the user is away, run npx claude-mem install --setup defer: it prepares the runtime and leaves setup waiting for their first visit, and their next session shows them the link. Don't make their choices for them.

npx claude-mem install

The installer finds the agents on your machine and asks which ones to set up. Then just start working: observations stream in from your first prompt, and your second session in a project opens with memory from the first. (Copilot CLI, Goose, Roo Code and Warp get memory search only, so their sessions don't add to it.)

The installer sets everything up first, then asks you to sign in to claude-mem in your browser (email magic link, no card required to sign in). Choosing the claude-mem observer then starts its 30 Day Free Trial on a checkout page that asks for a payment method; once it completes, the installer saves your memory key. With the observer, memory runs off-plan, so you get up to 100% more usage from your plan. When the free trial ends, memory automatically falls back to your Anthropic plan unless you subscribe. After sign-in you pick your memory provider: the claude-mem observer, your own OpenRouter or Gemini key, or your Anthropic plan.

Prefer to skip the sign-in? Pass an explicit --provider flag, set CLAUDE_MEM_ONLINE_OPTIN=false, or run in CI/non-interactive shells — the installer completes without any account interaction.

Your memory lives in ~/.claude-mem on your machine. Cloud sync is opt-in. Anonymous usage analytics are on by default; npx claude-mem telemetry disable turns them off (what's collected).

Or install from the plugin marketplace inside Claude Code:

/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. Always install via npx claude-mem install or the /plugin commands above.

Other agents

npx claude-mem install covers every supported agent. To set up one agent directly, pass --ide.

OpenCode (1.3.4 or later, including OpenCode 2). Restart OpenCode after installing.

npx claude-mem install --ide opencode

T3 Code (Codex and Claude Code providers). The installer discovers T3 Code's enabled providers, registers native Claude-Mem plugins in their configured homes, and supports T3-managed Codex. Restart T3 Code, trust the provider's hooks when prompted, and start a new thread. See the T3 Code integration guide for custom server settings, status, and removal.

npx claude-mem install --ide t3code

Antigravity CLI (setup guide):

npx claude-mem install --ide antigravity

OMP (Oh My Pi):

npx claude-mem install --ide omp

Pi and DeepSeek Harness use the worker runtime. See native harness setup for capture, recall, and troubleshooting.

npx claude-mem install --ide pi
npx claude-mem install --ide dsh --dsh-profile tui

Grok Bot: see Grok Bot below.

npx claude-mem install --ide grok-bot

The full list of --ide values is in npx claude-mem --help.

Grok Bot

Grok Bot has no host hooks, so we watch the chat log files. Default is CMEM Pro, the hosted memory. Local observer is opt-in: --provider host. Installing this plugin does not install Cursor.

Opt-in awareness push: needle observations (decision, bugfix, security_alert, sensitive) are appended as dated - YYYY-MM-DD [awareness] … lines into that bot's memory/log/YYYY-MM.md. Grok Bot already re-reads the log from disk. This does not write profile.md, user-memory, or project memory. Enable with CLAUDE_MEM_GROK_BOT_AWARENESS_ENABLED=true and set CLAUDE_MEM_GROK_BOT_AWARENESS_AGENT_IDS to your agent UUIDs (empty by default).

🦞 OpenClaw Gateway

Install claude-mem as a persistent memory plugin on OpenClaw gateways with a single command:

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

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 for details.

What You Get

---

Documentation

📚 View Full Documentation - Browse on official website

Getting Started

Best Practices

Architecture

Configuration & Development

---

How It Works

1. Your agent works. Hooks in your agent hand each tool call (what it reads, edits and runs) to a small local worker. 2. The observer takes notes. A second agent turns that activity into short observations, and writes a summary when the session ends. 3. The next session starts with them. When a session starts, your agent gets a compact index of the observations that matter for this project, and fetches full details only when it needs them.

Memory injection starts on your second session in a project. To front-load a whole repo instead, run /learn-codebase (~5 minutes on a typical repo, optional).

See Architecture Overview for details.

How it fits together

For contributors, the main parts and where they live:

The words we use for each of these, and the story they tell, are in docs/story.md.

---

MCP Search Tools

Search runs through three MCP tools in a token-efficient three-step workflow. The mem-search skill drives it for you:

The three steps:

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)

Step by step:

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:

// 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])

The worker also offers tools for code navigation (smart_search, smart_outline, smart_unfold), saving a note on purpose (save_memory) and tracking work in progress. See Search Tools Guide for detailed examples.

---

System Requirements

---

Windows Setup Notes

If you see an error like:

npm : The term 'npm' is not recognized as the name of a cmdlet

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

Claude Code hooks do not need Git Bash. Each hook runs claude-mem directly, and npx claude-mem install places that launcher at %LOCALAPPDATA%\claude-mem\bin\claude-mem.exe and adds the folder to your user Path. Restart your terminal or IDE afterwards so Claude Code picks up the new Path. If hooks report Executable not found in $PATH: "claude-mem", run npx claude-mem doctor and see Troubleshooting.

---

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.

To include observations from every harness in Claude Code and Codex SessionStart context, set "CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true" in that file, or enable Include all sources at session start in the viewer settings. The default is "false", which limits startup context to the current harness. The observation count limit still applies across the selected sources.

See the Configuration Guide for all available settings and examples.

Mode & Language Configuration

Claude-Mem supports multiple workflow modes and languages via the CLAUDE_MEM_MODE setting.

This option controls both:

How to Configure

Edit your settings file at ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_MODE": "code--zh"
}

Modes are defined in plugin/modes/. To see all available modes locally:

ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/

Available Modes

| Mode | Description | |------------|-------------------------| | code | Default English mode | | code--chill | Records fewer observations, keeping only what would be painful to rediscover | | code--[lang] | Same as code, with observations and summaries written in another language |

Built-in language codes: ar, bn, cs, da, de, el, es, fi, fr, he, hi, hu, id, it, ja, ko, nl, no, pl, pt-br, ro, ru, sv, th, tr, uk, ur, vi, zh. For example, code--ko writes observations and summaries in Korean.

See Modes for each language's name, the email investigation mode, and custom modes.

Note: All of these modes are built in. No additional installation or plugin update is required.

After Changing Mode

Restart Claude Code to apply the new mode configuration.

---

Development

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

---

Troubleshooting

Start with npx claude-mem doctor. It checks Bun, uv, the hook launcher and the worker, and tells you what to fix.

See the Troubleshooting Guide for common issues and solutions.

---

Bug Reports

Create comprehensive bug reports with the automated generator:

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

Contributing

Contributions are welcome! Please:

1. Fork the repository 2. Create a feature branch 3. Make your changes with tests 4. Update documentation (user-facing words follow docs/story.md) 5. Submit a Pull Request against main

Releases ship from main and are published to npm.

See Development Guide for contribution workflow.

---

License

Claude-Mem is licensed under the Apache License 2.0.

We chose Apache-2.0 because durable agentic memory should be easy to embed in develop

GitHub Stars & Activity

113,747Stars
9,867Forks
127Open issues
TypeScriptLanguage

GitHub Popularity

GitHub stars113,747
Forks9,867
Open issues127
Primary languageTypeScript
LicenseApache-2.0
Stars gained today17,074
Created2025-08-31
Last pushed2026-11-06

Trending History

Monthly boardrank #15 · ▲ 17,074 stars

Related GitHub Projects

1

morluto / rea

TypeScript★ 465,160⑂ 0
→
2

deepseek-ai / deepseek-harness

TypeScript★ 282,715⑂ 0
→
3

firecrawl / firecrawl

TypeScript★ 202,471⑂ 0
→
4

stablyai / orca

TypeScript★ 127,261⑂ 0
→
5

paperclipai / paperclip

TypeScript★ 114,449⑂ 0
→
6

google-gemini / gemini-cli

TypeScript★ 108,893⑂ 0
→
7

nexu-io / open-design

TypeScript★ 108,022⑂ 0
→
8

Egonex-AI / Understand-Anything

TypeScript★ 92,941⑂ 0
→

More Trending Repositories