# Self-Learning MCP

An MCP (Model Context Protocol) server that gives AI coding assistants durable long-term memory, reusable skills, a knowledge graph, post-task reflection, and evidence-based decision intelligence. Runs fully offline with no external API keys.

Created by [Abhradeep Paul Chowdhury](https://github.com/abhradeep-paul-chowdhury).

## Features

- **Memory Engine** — Store decisions, bugs, fixes, conventions, architecture notes, and prompt outcomes. Semantic search with deterministic hash-based embeddings (256-dim, cosine similarity).
- **Skill Engine** — Create versioned, executable engineering workflows. Auto-learning from repeated successful outcomes.
- **Knowledge Graph** — Nodes and edges across 11 entity types and 7 relationship types. Multi-hop BFS traversal.
- **Reflection Engine** — Post-task analysis with heuristic root-cause categorization. Automatically creates skills from patterns that succeed 3+ times.
- **Planner** — Decompose goals into ordered multi-step plans (build, debug, deploy, refactor, research). Execution loop with auto-retry and reflection.
- **Decision Intelligence Engine** — Evidence-backed decisions with a 9-tier evidence hierarchy. Separates verified facts from assumptions. Refuses high-impact decisions when confidence falls below threshold.
- **Workspace & Knowledge Management** — Project tracking, deployment history, code pattern analysis, full JSON export/import.
- **Web Dashboard** — Next.js UI to visualize and operate all engines (8 tabs: Overview, Memory, Skills, Graph, Reflections, Planner, Decisions, Connect).

## Architecture

```
                   ┌──────────────────────────────────────────┐
AI Clients ───────>│  MCP stdio bridge (mcp-stdio.ts)         │
  (Claude Code,    │  JSON-RPC over stdin/stdout              │
   Cursor,         └─────────────────────┬────────────────────┘
   OpenCode,                            │
   VS Code)                             │ shares engines
                                        ▼
                   ┌──────────────────────────────────────────┐
Dashboard ────────>│  In-process API (engineApi.ts)           │
  (Next.js,        │  or standalone HTTP server (index.ts)    │
   port 3000)      │     ┌──────────────────────────────────┐ │
                   │     │ memory · skill · graph           │ │
                   │     │ reflection · planner · workspace │ │
                   │     │ decision                         │ │
                   │     └──────────────────────────────────┘ │
                   │              │                           │
                   │         ┌────▼─────┐                    │
                   │         │  SQLite  │                    │
                   │         │ (Prisma) │                    │
                   │         └──────────┘                    │
                   └──────────────────────────────────────────┘
```

The server runs in two modes:
- **In-process** — All engines load inside the Next.js dashboard process (default, recommended)
- **Standalone** — Hono HTTP server on port 3003 + separate MCP stdio bridge for AI clients

Both modes share the same engines and the same SQLite database.

## 26 MCP Tools

| Category | Tools |
|----------|-------|
| Memory | `remember`, `recall`, `search_memory`, `store_memory`, `update_memory`, `delete_memory` |
| Skill | `learn_skill`, `run_skill`, `search_skills` |
| Reflection | `reflect`, `analyze_failure` |
| Graph | `graph_store`, `graph_query`, `graph_update`, `find_related` |
| Workspace | `project_summary`, `workspace_analysis`, `code_pattern_analysis`, `deployment_history` |
| Knowledge | `knowledge_export`, `knowledge_import` |
| Planner | `plan`, `execute_task` |
| Decision | `decide`, `record_decision_outcome`, `compare_decision_history` |

## Quick Start

```bash
# Prerequisites: Bun >= 1.3, Node.js >= 20
git clone https://github.com/abhraweb-boop/Self-Learning-MCP.git
cd Self-Learning-MCP

# Install root dependencies (dashboard + Prisma)
bun install

# Install MCP server dependencies
cd mini-services/mcp-server && bun install && cd ../..

# Copy environment config
cp .env.example .env

# Push database schema
bun run db:push

# (Optional) Seed demo data
cd mini-services/mcp-server && bun run seed && cd ../..

# Start the standalone HTTP server
cd mini-services/mcp-server && bun run dev
```

In a second terminal, start the dashboard:

```bash
cd Self-Learning-MCP
bun run dev
```

Open `http://localhost:3000` to view the dashboard.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_URL` | `file:./db/custom.db` | SQLite database path (relative to `prisma/schema.prisma`) |
| `LOG_LEVEL` | `info` | Logging verbosity: `trace`, `debug`, `info`, `warn`, `error` |
| `NODE_ENV` | `development` | Set to `production` for production builds |

## Connecting AI Clients

Configure your MCP client to spawn `bun run mcp` from the `mini-services/mcp-server` directory:

```json
{
  "mcpServers": {
    "self-learning": {
      "command": "bun",
      "args": ["run", "mcp"],
      "cwd": "/absolute/path/to/mini-services/mcp-server"
    }
  }
}
```

Works with **Claude Code**, **Cursor**, **OpenCode**, **VS Code** (with an MCP extension), and any MCP-compatible client.

## Production Build

```bash
bun run build
```

Creates a standalone `.next/` bundle with all static assets. Serve with:

```bash
NODE_ENV=production bun .next/standalone/server.js
```

For production deployments:
- Use a reverse proxy (Caddy, Nginx) with TLS
- Set `NODE_ENV=production`
- Back up the SQLite database regularly
- Use `knowledge_export` for portable JSON backups

## Project Structure

```
├── prisma/schema.prisma        # Database schema (SQLite)
├── src/                        # Next.js dashboard + in-process engine API
│   ├── app/                    # Dashboard pages and API routes
│   ├── components/             # shadcn/ui dashboard components
│   └── lib/
│       ├── engines/            # Core engines
│       ├── mcp-utils/          # Shared utilities (db, vector, logger)
│       ├── engineApi.ts        # In-process API dispatcher
│       └── mcp.ts              # Dashboard API client
├── mini-services/mcp-server/   # Standalone MCP server
│   ├── src/
│   │   ├── index.ts            # Hono HTTP server (port 3003)
│   │   ├── mcp-stdio.ts        # MCP stdio bridge
│   │   ├── seed.ts             # Demo data seeder
│   │   └── engines/            # Re-exports for standalone use
│   └── docs/                   # Documentation
├── Caddyfile                    # Optional reverse-proxy config
└── .env.example                 # Environment variable template
```

## Technology Stack

| Layer | Technology |
|-------|-----------|
| Runtime | [Bun](https://bun.sh) 1.3+ |
| Framework (dashboard) | [Next.js](https://nextjs.org) 16, [React](https://react.dev) 19 |
| HTTP server (standalone) | [Hono](https://hono.dev) 4 |
| Database | SQLite via [Prisma](https://prisma.io) 6 |
| UI | [shadcn/ui](https://ui.shadcn.com), [Tailwind CSS](https://tailwindcss.com) 4 |
| MCP protocol | [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) |
| Validation | [Zod](https://zod.dev) |
| Logging | [Pino](https://getpino.io) |

## Example Usage

**Remember a decision:**
```
User: Remember that we use App Router for all pages.
Agent: [calls remember with type=decision, title="Use App Router"...]
```

**Evaluate a decision with evidence:**
```
User: Should we switch from SQLite to PostgreSQL?
Agent: [calls decide with facts about traffic, cost, migration effort...]
        Returns: Refused — insufficient evidence (confidence 35%, threshold 60%).
        Requests more information: traffic metrics, cost comparison, migration plan.
```

**Analyze a failure and auto-learn:**
```
User: The deployment failed because the build ran out of memory.
Agent: [calls analyze_failure with goal="Deploy API" and error details]
        Creates: reflection + prompt_failure memory.
        After 3 similar failures: auto-creates a "deploy-api" skill with extra swap.
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Author

**Abhradeep Paul Chowdhury**

- GitHub: [@abhradeep-paul-chowdhury](https://github.com/abhradeep-paul-chowdhury)