CHARLIE

CHARLIE is the memory layer Claude Code's built-in Auto Memory isn't. Claude Code (v2.1.59+) writes flat per-repo markdown notes and prefix-loads the first 200 lines every session; CHARLIE banks typed, priority-weighted knowledge (mistakes, decisions, patterns, conventions) in PostgreSQL+pgvector and recalls it by semantic relevance — across projects, across machines, automatically injected before related work so the same mistake never happens twice.

Where it goes beyond anything native:

• Semantic code search — search_code("where do we retry failed embeds") over a live-indexed codebase. Claude Code only has grep and LSP symbol navigation; there is no first-party vector search.
• Automatic mistake capture — failed tool calls are hook-banked (PostToolUseFailure → auto-bank) without the model deciding to remember. Native Auto Memory only saves what Claude chooses to note at session end.
• Cross-machine shared state — one Postgres knowledge base serves every machine and every Claude Code instance. Auto Memory is machine-local with no sync.
• Longitudinal cost & ROI — /usage is single-machine and approximate; CHARLIE's dashboard tracks token/dollar savings and per-session cost over months, with active waste-blocking (redirecting grep/Read to indexed equivalents) rather than just measurement.

CHARLIE is built to save you time and money with AI. Reusing recalled patterns instead of re-explaining them, 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 (legacy — minimal surface): Claude Code's native Agent tool, dynamic workflows, and agent teams now cover most orchestration; CHARLIE keeps a minimal delegation surface (activate → assign_slot → end_session) for session tracking and mistake banking. The orchestration-tier tools deprecated in #492 (agent CRUD, pool status, intent signals, artifact sharing, session timeout/retry plumbing) were removed in the #481 release. 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). Override the tier at launch time with assign_slot(..., 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