# lessons-mcp

An MCP server for Claude Code that stores and searches lessons learned, so Claude
doesn't repeat past mistakes. Think of it as a persistent experience log with
full-text search and tag-based navigation.

## Quick Start

```bash
git clone https://github.com/<your>/lessons-mcp
cd lessons-mcp
pip install mcp
```

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "lessons": {
      "command": "python3",
      "args": ["/path/to/lessons-mcp/server/server.py"]
    }
  }
}
```

## Tools

### suggest_metadata
Preview available categories/tags before writing. Returns existing landscape + suggestion.

### record_lesson
Record a new lesson. Returns feedback on tag reuse consistency.

### search_lessons
Search past lessons. FTS5 (tags/category/title) + LIKE fallback (Chinese body).

### list_categories
Browse categories with recent tag activity.

### list_tags
Browse tags within a category with usage count.

## Storage

SQLite at `~/.claude/lessons.db` (or `$LESSONS_DB_PATH`).
One table + FTS5 index, created automatically on first run.

## Integration with Claude Code

### 1. Add to MCP config

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "lessons": {
      "command": "/Users/karsa/proj/lessons-mcp/.venv/bin/python3",
      "args": ["/Users/karsa/proj/lessons-mcp/server/server.py"]
    }
  }
}
```

### 2. Add pointer to MEMORY.md

Add to `~/.claude/memory/MEMORY.md`:

```
## Lessons System
Lessons MCP available. Tools: search_lessons, suggest_metadata, record_lesson,
list_categories, list_tags
```

### 3. Restart Claude Code

The server starts automatically when Claude Code launches.
You should see in logs: `lessons-mcp v1.0.0 | ~/.claude/lessons.db | 1 lessons`