CHARLIE - Unified Knowledge & Orchestration MCP Server

External memory and agent orchestration for Claude Code. CHARLIE remembers your project's patterns, conventions, and decisions across sessions so you never re-explain context. When you ask Claude to do something, CHARLIE automatically assigns the right specialist agent, loads relevant knowledge into its prompt, and tracks the work.

CHARLIE is built to save you time and money with AI. Reusing recalled patterns instead of re-explaining them, routing work to the cheapest model that can handle it (Haiku → Sonnet → Opus only when needed), capping per-session spend with hard budgets, and bypassing redundant tool calls all add up. The dashboard's /savings page tracks the token and dollar savings over time so you can see the ROI.

Runs as a Docker-based FastMCP server with PostgreSQL+pgvector database, file watcher, scheduler, and web dashboard. The project will change how your claude environment works. So please either deploy on a fresh system or back up your claude files first before using this.

Install

git clone https://github.com/T3CCH/charlie.git
cd charlie
cp .env.example .env        # edit DB_PASSWORD at minimum
bash setup.sh              # full installer: wizard, build, start, migrate, host config

setup.sh is idempotent — re-running it after changing .env fixes stale MCP registrations and re-applies host config without prompting again.

Verify everything is running:

bash scripts/check-install.sh        # post-setup diagnostic: checks every artifact setup.sh creates
docker exec charlie-mcp python scripts/migrate_data.py --verify

Architecture

CHARLIE is a unified FastMCP server for knowledge management and agent orchestration.

Stack:

• Framework: FastMCP (mcp[cli]>=1.0.0)

• Database: PostgreSQL 16 + pgvector (27 tables, schema managed by alembic)

• Embeddings: sentence-transformers via the GPU embed service. Run it locally (build the gpu/ Docker image on a host with CUDA) or remotely (point EMBED_SERVICE_URL at a shared GPU host). Falls back to CPU-only inference inside the MCP container if no embed service is reachable.

• Code Analysis: tree-sitter (7 languages: Python, JavaScript, TypeScript, Go, Java, C, C++) + shebang detection for extensionless scripts and non-standard extensions (.start, .stop, .ksh, .csh, OpenRC init scripts, git hooks, etc.)

• Async Runtime: asyncpg, aiohttp

Agent Pool: 20 pool slots (2 opus, 12 sonnet, 6 haiku)

• Concurrency-safe slot allocation and release

• Pool status visible in dashboard

• Automatic timeout detection and session cleanup

• Tunable model tier per agent: Each agent template has a preferred_model (opus/sonnet/haiku). Upgrade or downgrade an agent's tier any time with charlie_update_agent(agent_id, preferred_model="opus"). CHARLIE also auto-escalates an agent to a higher tier after repeated failures (controlled by MODEL_ESCALATION_THRESHOLD, default 3).

Scheduler: Embedded cron scheduler in MCP process

• Runs heartbeat checks every 60 seconds (configurable)

• Supports cron expressions, one-shot at datetime, fixed intervals

• Notifications tracked in scheduler_runs table

• Automatic job deactivation after completion

Docker Services

All MCP/watcher/dashboard images use Python 3.11-slim with CPU-only PyTorch. GPU embeddings come from a fifth optional service defined in gpu/Dockerfile — run it locally on a CUDA host or point EMBED_SERVICE_URL at a remote one (default: http://192.168.1.100:8100). If unreachable, embeddings fall back to CPU.

Configuration

Edit .env to customize:

For advanced configuration, schema details, tool inventory, and architecture diagrams, see TECHNICAL.md.

Dashboard

Open http://localhost:8200 to view:

• Agent Pool Status — Current slot assignments and utilization

• Session History — Completed, active, and failed sessions

• Knowledge Base — Stored patterns, conventions, decisions

• Health Checks — System diagnostics and alerts

• Token Savings — ROI analysis and usage trends

• File Activity — Recent file watcher events and indexing

• Jobs — Scheduler job definitions and execution history (/jobs)

Key Commands

Health check

docker exec charlie-mcp python scripts/migrate_data.py --verify

View container logs

docker compose logs -f mcp
docker compose logs -f watcher
docker compose logs -f dashboard

Database shell (PostgreSQL)

docker exec -it charlie-db psql -U charlie -d charlie

Rebuild after code changes

docker compose --profile db build
docker compose --profile db up -d

Usage

Once CHARLIE is running, use it via Claude Code:

You: fix the login bug where users get logged out after 5 minutes

CHARLIE:
  -> Classifies as "debugging"
  -> Assigns Senior Engineer agent
  -> Agent recalls past auth patterns
  -> Agent searches codebase for session logic
  -> Agent fixes the bug and reports findings

For shortcuts and advanced usage, see README.md in the original repo.

License

GPL-3.0-or-later

Links

• Technical Documentation

• Testing Plan

• Database Migrations

• Repository

If CHARLIE saves you time, consider buying me a coffee: