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

## 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:

| Tool | Purpose |
|------|---------|
| `mistake` | Record what you tried and why it failed |
| `learned` | Save a problem/solution pair that worked |
| `recall` | Search for relevant past context |
| `promote` | Export important learnings to CLAUDE.md |

That's it. Simple, focused, useful.

## Installation

### Claude Code CLI

Add to your project's `.mcp.json`:

```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`:

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

## Tools

### `mistake`

Record an approach that didn't work.

```typescript
{
  "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.

```typescript
{
  "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.

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

### `promote`

Export a learning to CLAUDE.md for permanent reference.

```typescript
{
  "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:

```json
{
  "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