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

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

Add to ~/.claude/mcp.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:

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