claude-mem MCP — Use Cases, Install & Live Demo

Why use it

Key features

Session-spanning memory via AI compression (not just grep of logs)
SQLite + Chroma vector search for semantic recall
Real-time web viewer at localhost:37777
<private> tags to exclude sensitive content from capture
Citation system — observations are referenced by ID in answers
Works with Claude Code, Gemini CLI, OpenCode; available via plugin marketplace

Live Demo

What it looks like in practice

claude-mem-skill.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "claude-mem-skill": {
      "command": "npx",
      "args": [
        "claude-mem",
        "install"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "claude-mem-skill": {
      "command": "npx",
      "args": [
        "claude-mem",
        "install"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "claude-mem-skill": {
      "command": "npx",
      "args": [
        "claude-mem",
        "install"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "claude-mem-skill": {
      "command": "npx",
      "args": [
        "claude-mem",
        "install"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "claude-mem-skill",
      "command": "npx",
      "args": [
        "claude-mem",
        "install"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "claude-mem-skill": {
      "command": {
        "path": "npx",
        "args": [
          "claude-mem",
          "install"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add claude-mem-skill -- npx claude-mem install

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use claude-mem

Resume a multi-week project without re-briefing Claude every morning

👤 Engineers on long-running features or research ⏱ ~5 min beginner

When to use: You spend the first 10 minutes of every session re-explaining context that Claude had yesterday.

Prerequisites

Claude Code installed — npm install -g @anthropic-ai/claude-code
claude-mem installed — npx claude-mem install (registers hooks in ~/.claude)

Flow

Work normally

Just use Claude Code. claude-mem is passive — hooks capture events automatically.✓ Copied

→ localhost:37777 shows the memory stream updating as you work
Start tomorrow's session

Where did we leave off on the migration branch?✓ Copied

→ Claude recalls concrete facts + cites observation IDs
Correct misremembering

That's wrong about the DB schema — we decided to keep the v1 field. Mark that observation as corrected.✓ Copied

→ mem-search writes a correction; future recall prioritizes it

Outcome: Sessions feel continuous. The re-briefing ritual disappears.

Pitfalls

Memory recalls stale facts after you change course — Explicitly mark corrections; mem-search respects recency and overrides
Sensitive code snippets get captured — Wrap them in <private>...</private> tags; hooks skip private blocks

Combine with: filesystem

Turn individual sessions into team knowledge without writing docs

👤 Team leads; ICs who avoid writing postmortems ⏱ ~10 min intermediate

When to use: You solve a gnarly bug, explain the fix to Claude, and want that explanation findable next month without writing a README.

Flow

Narrate your fix

Walk me through why the deadlock happened and the fix you just landed. Be complete — future me might read this.✓ Copied

→ Claude writes a narrative; compression captures it
Tag the memory

Tag this observation with 'db-deadlock-2026-04' and 'billing-cluster'.✓ Copied

→ Tags stored on the observation
Recall later

A month later: 'We've got another deadlock in billing — pull any prior notes.'✓ Copied

→ The April note surfaces first

Outcome: Lightweight knowledge base that grows by itself.

Pitfalls

Memory gets noisy as months pass — Use mem-search --prune on low-signal old sessions; Endless Mode (beta) handles this automatically

Combine with: memory

Keep customer data and secrets out of memory captures

👤 Anyone working with sensitive data ⏱ ~15 min intermediate

When to use: You work on code that touches PII or secrets and can't let them land in a local vector store.

Flow

Wrap sensitive blocks

Write me the sample data with real test records wrapped in <private> tags so claude-mem doesn't capture the values.✓ Copied

→ Private blocks are in the transcript but not in the memory store
Verify

Open localhost:37777 and check today's stream. Confirm no records from the <private> block appear.✓ Copied

→ Private content absent
Add repo-wide policy

Update CLAUDE.md: 'Always wrap real customer data in <private>'.✓ Copied

→ CLAUDE.md updated; future sessions inherit

Outcome: Memory is useful without being a data-leak surface.

Pitfalls

Forgetting to tag sensitive content — Make it a pre-commit / hook convention; claude-mem can enforce prompts that remind on detection

Combinations

Pair with other MCPs for X10 leverage

claude-mem-skill + filesystem

Memory recalls the file you edited, filesystem re-reads it

Pull from mem-search the last file we edited in the billing refactor; then read it and continue where we left off.✓ Copied

claude-mem-skill + serena

Memory supplies the intent; Serena supplies the current code state

Memory says we're renaming ChargeService → BillingService; use Serena to finish the rename.✓ Copied

claude-mem-skill + github

Cross-reference memory with real PR state

Memory says we opened a PR yesterday; use GitHub MCP to get its current status and review comments.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
mem-search (skill)	query: str, limit?: int, since?: date	Any time you'd ask Claude to 'remember' — full-text and semantic search over your history	free (local SQLite + embedding model)
mem-compress (hook)	session transcript	Automatic — runs at session end; rarely invoked manually	small Claude call per session
web viewer	URL http://localhost:37777	Debug what's being captured; check privacy filters	free

Cost & Limits

What this costs to run

API quota: Local SQLite + Chroma vectors; embedding model bundled
Tokens per call: Small — observations are already compressed
Monetary: Free (MIT)
Tip: Compression calls use your Claude API key; set a monthly budget in the claude-mem config if you chat a lot

Security

Permissions, secrets, blast radius

Credential storage: None for the tool itself; compression uses your existing Claude API key

Data egress: Compression calls go to Anthropic (your account); nothing else leaves your machine

Never grant: Uploading the SQLite/Chroma store off-device without review — it contains transcripts

The local memory database is plaintext by default. If your disk isn't encrypted, enable FileVault/LUKS/BitLocker before using on sensitive projects.
Sharing your dotfiles or home dir via backup tools can leak memory. Add ~/.claude/mem/** to your backup exclusions if relevant.

Troubleshooting

Common errors and fixes

Web viewer at localhost:37777 won't load

Check the hook is running: ps aux | grep claude-mem. Reinstall with npx claude-mem install if it's absent.

Verify: curl -I http://localhost:37777

Recall returns nothing useful

First few sessions are cold; memory gets better after ~10 sessions as patterns emerge. Also check that hooks are actually firing (see viewer).

Verify: Open viewer during a session; events should stream in real time

Compression calls are expensive

Lower compression depth in config or use Endless Mode (beta) which is cheaper per session

Verify: Check Anthropic usage dashboard for attribution

<private> content still shows up

Tag must be on its own lines; inline <private>…</private> in the middle of a sentence isn't parsed. Use block form.

Verify: Reproduce and inspect the stored observation in the viewer

Alternatives

claude-mem vs others

Alternative	When to use it instead	Tradeoff
Memory MCP	You want explicit, user-controlled memory writes — not passive capture	You do the memory-saving yourself; less ambient, less magic
Serena memory	Your use case is code-focused and you'd rather have per-project notes than transcript compression	No session-stream capture; more project-level
Just take notes	You prefer explicit, human-curated notes	No automation; discipline-dependent

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills