<div align="center">

regret-mcp

A tiny local MCP memory server that stores lessons learned and resurfaces them before your AI agent repeats the same mistake.

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

🎯 Why?

Trending repos focus on agent memory, agent skills, and autonomous coding agents, but most memory systems are vector stores, hosted services, or heavyweight frameworks. Developers need a zero-dependency local memory primitive for explicit post-mortems: task, mistake, correction, tags. regret-mcp fills that gap with a small SQLite-backed MCP server and CLI that can be attached to Claude Code or any MCP client in seconds.

Target audience: Developers using Claude Code, Cursor, or custom MCP agents who want persistent local memory; agent framework authors needing a simple lesson-memory tool; DevOps and platform teams capturing operational lessons.

✨ Features

• ✨ MCP stdio server exposing add_lesson, search_lessons, list_lessons, forget_lesson, and stats tools
• ✨ Local SQLite storage with tag normalization, severity levels, and keyword search
• ✨ CLI for adding, searching, listing, forgetting, and inspecting lessons without an MCP client

🚀 Quick Start

# Install
pip install regret-mcp

# Run
regret-mcp --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/regret-mcp.git
cd regret-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

🎬 Demo

The GIF above was recorded using Charm VHS:

vhs < demo.tape

📖 Usage

# Show help
regret-mcp --help

# Common usage examples
regret-mcp --example

🏗️ Architecture

graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT © 2026 — See LICENSE for details.

---

<div align="center">

If this project helped you, please ⭐ star it!

Made with ❤️ and AI

</div>