Context Memory MCP Server

An MCP server for tracking mistakes and solutions. Don't repeat what failed.

What This Is

Context Memory is a simple tool that helps Claude learn from your past sessions. It stores two things:

1. Mistakes - approaches that failed and why

2. Solutions - problems you solved and how

Before trying something, Claude can check if you've been down that road before. After solving something tricky, you can save it for next time.

Related MCP server: claude-soul

Why This Exists

The Original Problem (2025)

When this project started, Claude Code had a significant limitation: conversation compression. As context windows filled up, Claude would compress older messages to make room. This meant losing valuable context:

• Why you chose one approach over another

• Edge cases you discovered along the way

• Failed attempts and what broke

• Handoff context between specialized agents

The original v0.x built an elaborate system to preserve all of this: notes, file decisions, agent handoffs, problem caches, session management. It worked, but it was complex.

What Changed

Claude Code got smarter. A lot smarter.

The compression that once destroyed context now preserves what matters. Claude maintains its own understanding of the conversation, the codebase, and the decisions being made. Most of what v0.x did became redundant—Claude handles it natively now.

But one thing Claude still can't do: learn from sessions it wasn't part of.

If you spent two hours debugging an authentication issue last week, and hit the same issue today in a new session, Claude starts from zero. It will suggest the same failed approaches. It doesn't know what you already tried.

The v1.0 Refocus

Version 1.0 strips away everything Claude now handles itself and focuses on the one remaining gap: cross-session learning from failures.

The API went from 8+ tools to 4:

That's it. Simple, focused, useful.

Installation

Claude Code CLI

Add to your project's .mcp.json:

{
  "mcpServers": {
    "context-memory": {
      "command": "npx",
      "args": ["-y", "github:Dithilli/context-memory-mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "context-memory": {
      "command": "npx",
      "args": ["-y", "github:Dithilli/context-memory-mcp"]
    }
  }
}

Tools

mistake

Record an approach that didn't work.

{
  "what": "Tried using localStorage for auth tokens",
  "why_failed": "XSS vulnerability - any script can read localStorage",
  "tags": ["security", "auth"],
  "files": ["src/auth/storage.ts"]
}

learned

Save a problem/solution pair.

{
  "problem": "Supabase RLS returns empty array instead of 401",
  "solution": "Add explicit auth check before query - RLS fails silently",
  "tags": ["supabase", "auth"]
}

recall

Search past mistakes and solutions.

{
  "query": "authentication",
  "tags": ["security"],
  "limit": 10
}

promote

Export a learning to CLAUDE.md for permanent reference.

{
  "id": "solution-123",
  "type": "solution"
}

Storage

Data is stored in ~/.context-memory/ by default:

• mistakes.jsonl - Failed approaches

• solutions.jsonl - Working solutions

Custom Location

Use --storage-dir for per-project or custom storage:

{
  "mcpServers": {
    "context-memory": {
      "command": "npx",
      "args": [
        "-y",
        "github:Dithilli/context-memory-mcp",
        "--storage-dir",
        ".context-memory"
      ]
    }
  }
}

Project Auto-Detection

The server automatically detects your project from the git root, so mistakes and solutions are tagged with project context without manual configuration.

When to Use This

Do use it for:

• "We tried X, it failed because Y" - saves hours of repeated debugging

• Tricky solutions that aren't obvious from the code

• Patterns that apply across projects

Don't use it for:

• General notes (Claude remembers within a session)

• Implementation details (that's what git history is for)

• Obvious things (trust Claude to figure those out)

Migration from v0.x

If you have data from v0.x, the server will automatically migrate it on first run:

• Old notes.jsonl entries become mistakes

• Old problems.jsonl entries become solutions

• Handoffs and file decisions are archived (no longer needed)

Changelog

v1.0.0 (2026-01-23)

• Breaking change: Simplified API to four tools: mistake, learned, recall, promote

• Added project auto-detection from git root

• Added promote tool to export learnings to CLAUDE.md

• Automatic migration from v0.x data format

• Removed handoffs, notes, and file decisions (Claude Code handles these natively now)

v0.2.0 (2025-01-12)

• Added configurable storage directory (--storage-dir option)

• Support for per-project storage

v0.1.0 (2025-01-12)

• Initial release with full context preservation system

License

MIT