# 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. 

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-PayPal-FFDD00?style=for-the-badge&logo=paypal&logoColor=white)](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.

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](charlie-plugin/README.md) and [charlie-plugin/CHANGELOG.md](charlie-plugin/CHANGELOG.md).

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 (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

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

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:

```bash
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

```bash
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

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

## 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:

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-PayPal-FFDD00?style=for-the-badge&logo=paypal&logoColor=white)](https://www.paypal.com/donate/?hosted_button_id=V66PQ8X35A2FJ)