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.

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

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

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:

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

bun run build

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

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 1.3+
Framework (dashboard)	Next.js 16, React 19
HTTP server (standalone)	Hono 4
Database	SQLite via Prisma 6
UI	shadcn/ui, Tailwind CSS 4
MCP protocol	Model Context Protocol SDK
Validation	Zod
Logging	Pino

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 file for details.

Author

Abhradeep Paul Chowdhury

• GitHub: @abhradeep-paul-chowdhury