CHARLIE

# 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. [](https://www.paypal.com/donate/?hosted_button_id=V66PQ8X35A2FJ) ## Install ```bash 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 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 | Service | Purpose | Image | |---------|---------|-------| | **db** | PostgreSQL 16 with pgvector extension | `pgvector/pgvector:pg16` | | **mcp** | FastMCP server + alembic migrations | `charlie-mcp:latest` (from Dockerfile) | | **watcher** | File watcher + cron scheduler | `charlie-watcher:latest` (from Dockerfile) | | **dashboard** | Web UI (agent pool, sessions, knowledge, metrics) | `charlie-dashboard:latest` (from Dockerfile) | 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: | Variable | Default | Notes | |----------|---------|-------| | `DB_PASSWORD` | `changeme` | **Change this!** PostgreSQL password | | `DB_HOST` | `db` | Database hostname (in Docker) | | `DB_PORT` | `5432` | Database port | | `DB_NAME` | `charlie` | Database name | | `EMBED_SERVICE_URL` | `http://192.168.1.100:8100` | Remote GPU embeddings endpoint | | `DASHBOARD_PORT` | `8200` | Web dashboard port | | `HOST_HOME` | `$HOME` | Host home directory for file watching | | `AGENT_POOL_SIZE` | `20` | Total agent pool slots | | `AGENT_MAX_CONCURRENT` | `10` | Max concurrent agents in-flight | | `SCHEDULER_ENABLED` | `true` | Enable background job scheduler | | `SCHEDULER_CHECK_INTERVAL_SECONDS` | `60` | Job scheduler poll interval | | `MCP_MEM_LIMIT` | `2g` | MCP container memory limit (one long-lived streamable-HTTP daemon; 2g is ample) | | `DB_MAX_CONNECTIONS` | `200` | PostgreSQL max connections | For advanced configuration, schema details, tool inventory, and architecture diagrams, see [TECHNICAL.md](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 ```bash docker exec charlie-mcp python scripts/migrate_data.py --verify ``` ### View container logs ```bash docker compose logs -f mcp docker compose logs -f watcher docker compose logs -f dashboard ``` ### Database shell (PostgreSQL) ```bash docker exec -it charlie-db psql -U charlie -d charlie ``` ### Rebuild after code changes ```bash 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](https://github.com/T3CCH/charlie/blob/main/README.md) in the original repo. ## License GPL-3.0-or-later ## Links - [Technical Documentation](TECHNICAL.md) - [Testing Plan](TESTING_PLAN.md) - [Database Migrations](MIGRATIONS.md) - [Repository](https://github.com/T3CCH/charlie) --- If CHARLIE saves you time, consider buying me a coffee: [](https://www.paypal.com/donate/?hosted_button_id=V66PQ8X35A2FJ)