CHARLIE - Semantic Memory & Cost Discipline for Claude Code

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.

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.

Tested against Claude Code 2.1.220 (July 2026); the hooks and plugin require ≥ 2.1.198.

Claude Code plugin

The charlie-plugin/ bundle (skills, pool-slot agents, hooks, output style, statusline) installs via the plugin marketplace:

/plugin marketplace add T3CCH/charlie
/plugin install charlie

The CHARLIE MCP server itself must be registered at user scope first (setup.sh does this; manually: claude mcp add --transport http --scope user charlie http://127.0.0.1:8000/mcp). See charlie-plugin/README.md and charlie-plugin/CHANGELOG.md.

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

Related MCP server: mcp-server-claude

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 allocated by capability role (#497): research a1–a4, implementation a5–a8, review a9–a12, deployment a13–a16, debugging a17–a20.

• 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/fable). 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).

• Enforced budgets: max_cost_usd / max_tool_calls / max_turns and per-slot tool allowlists are enforced by PreToolUse hook gates, keyed on the Claude Code agent_id → CHARLIE session mapping (migration 025).

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://embed-host.example: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)

The dashboard also ingests Claude Code OTel telemetry: POST /otlp/v1/logs stores claude_code.api_request events (cost, tokens, model, attribution) in the llm_requests table, and cost reporting automatically prefers that source, falling back to hook capture. To send telemetry from a client:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8200/otlp/v1/logs

Key Commands

Health check

docker exec charlie-mcp python -m src.healthcheck && echo healthy   # real MCP initialize probe
docker exec charlie-mcp python scripts/migrate_data.py --verify     # schema verification

The mcp container runs under a built-in supervisor (python -m src.healthcheck --supervise): if the streamable-HTTP endpoint stops answering real MCP initialize probes (a failure mode where plain TCP/HTTP checks still pass), the supervisor replaces the daemon automatically via the container restart policy. docker ps shows the probe result as the container's health status.

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 (ch-, roi-, todo triggers, etc.) and advanced usage, see charlie-plugin/README.md or type ch- in a CHARLIE-enabled session.

License

GPL-3.0-or-later

Links

• Technical Documentation

• Testing Plan

• Database Migrations

• Repository

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