# gwen-digestor

**Model Context Protocol server for conversation compression.**

Reduces token consumption by compressing conversation exchanges before they enter the LLM context window. Uses deterministic, embedding-free compression — no external APIs, no GPU required.

## Features

- **4 MCP tools**: `digest_input`, `compress_response`, `cache_reference`, `session_stats`
- **Mode-aware compression**: auto-detects checkin, task, narrative, or casual conversation
- **Content-type detection**: smart JSON crushing, code comment stripping, prose pass-through
- **Gzip-compressed reference cache**: SQLite-backed key-value store with TTL expiry
- **Token savings tracking**: persistent stats across sessions

> 📊 [View the Token Reduction Report](docs/gwen-digestor-token-reduction-report.pdf) — a professional breakdown with compression metrics and visual charts.

## Compression Levels

| Mode | Level | Strategy |
|------|-------|----------|
| checkin | 25% | Extract structured metrics (pain, sleep, energy, food, weight, stress) |
| task | 50% | Strip filler words, remove greetings/hedges |
| casual | 75% | Light structural compression |
| narrative | 95% | Preserve detail with minimal trimming |

## Tools

### `digest_input`
Compresses incoming messages by mode. Strips conversational filler, extracts health metrics in checkin mode, removes boilerplate in task mode.

### `compress_response`
Compresses outgoing responses with mode-aware sentence truncation.

### `cache_reference`
Gzip-compressed key-value store for reference texts. Configurable TTL (default 24h).

### `session_stats`
Real-time token savings dashboard showing compression rates across all calls.

## Installation

```bash
pip install mcp fastmcp
```

## Usage

Register as an MCP server in your client config:

```json
{
  "mcpServers": {
    "gwen-digestor": {
      "command": "python3",
      "args": ["/path/to/gwen_digestor.py"],
      "transport": "stdio"
    }
  }
}
```

Then call the tools from your LLM session:

```
digest_input("hey, just checking in — slept okay, pain 3/10 today, stress 5/10")
→ [MODE:checkin@25%] SLEEP:okay|PAIN:3/10|STRESS:5/10
```

## Storage

- **Cache DB**: `~/.gwen-digestor/cache.db` (SQLite, gzip-compressed blobs)
- **Stats**: `~/.gwen-digestor/stats.json` (persistent across sessions)
- **Dependencies**: Python 3.10+, `mcp`, `fastmcp`

## License

MIT