Claude-Mem Gives Claude Code a Memory That Outlives the Session

Every Claude Code session starts from zero. You re-explain the architecture, re-tell the bug you chased yesterday, and re-litigate the decision you already settled. Claude-Mem, a 94k-star plugin, closes that gap: it captures tool-usage observations while you work, compresses them into semantic summaries, and injects the relevant ones into future sessions.

Why This Skill Matters

The system runs through lifecycle hooks — SessionStart, UserPromptSubmit, PostToolUse, Stop, and SessionEnd — so capture and injection are automatic, with no manual notes to maintain. Underneath sit a local worker service managed by Bun (it exposes an HTTP API plus a web viewer), a SQLite database storing sessions, observations, and summaries, and a Chroma vector database for hybrid semantic and keyword search. A mem-search skill lets the agent query project history in natural language.

The design goal is continuity without token bloat. Memory search follows a three-layer workflow: search returns a compact index with IDs, timeline adds chronological context around interesting hits, and get_observations fetches full details only for the IDs that survived filtering.

Installation

npx claude-mem install

The installer sets everything up, then asks you to sign in through the browser (email magic link, no card). Signing in provisions a memory key and unlocks the claude-mem observer — memory that runs off your Anthropic plan, free for the first 30 days, falling back to your Anthropic plan when the trial ends unless you subscribe. You pick the provider: the observer, your own OpenRouter or Gemini key, or your Anthropic plan.

Prefer no account step? Pass an explicit --provider flag, set CLAUDE_MEM_ONLINE_OPTIN=false, or run in CI — the installer completes without any sign-in.

Inside Claude Code, the marketplace route works too:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Restart Claude Code afterwards. One trap worth flagging from the README: npm install -g claude-mem installs the SDK library only — it registers no hooks and sets up no worker. Requirements are Node.js 20 or higher; Bun and the uv Python package manager install automatically if missing.

Real Workflow: Let It Run, Then Look

After the restart, memory is hands-off: context from previous sessions appears in new sessions on its own. The worker URL printed at startup opens the web viewer, where the real-time memory stream is visible as it fills.

Real Workflow: Search Deliberately

When you want a specific answer instead of automatic priming, drive the three layers in order:

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

Index results cost roughly 50–100 tokens each; full observations run 500–1,000. Filtering before fetching is where the README's ~10x token savings come from — always batch the IDs in one get_observations call.

Tips

• Turn on Simplified Chinese observations with "CLAUDE_MEM_MODE": "code--zh" in ~/.claude-mem/settings.json — the mode is built in, and one setting controls both workflow behavior and observation language. Restart Claude Code to apply it.
• Wrap sensitive content in <private> tags to keep it out of storage.
• The Claude Desktop skill searches the same memory from desktop conversations.
• List every available mode with ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/.

When Not to Use This

Claude-Mem remembers what happened in your sessions — tool calls, decisions, fixes — not a hand-curated second brain, so do not expect it to hold notes you never made in a session. The global npm route is wrong for plugin users, as flagged above. And if you want nothing hosted, decline the sign-in deliberately: the observer is the hosted option, while the explicit --provider path keeps memory generation on your own keys or your Anthropic plan.

See the leaderboard for more skills.