CHARLIE

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.

Buy Me A Coffee

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

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.

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:

Buy Me A Coffee