llms.txt git:20260807.6a54034A

Immutable. This exact content is served forever at /api/v1/blob/376dcc08308290e6.

# Furl

> Context compression for AI agents, plus prompt compression and token optimization. Compress tool outputs, logs, and RAG chunks before they reach the model to reduce Claude Code token usage. Same answers, typically 0-54% fewer tokens on real high-entropy content, and up to 95% on repetitive logs and fixtures as a best-case ceiling. Python library and MCP server. Apache 2.0, local-first.

Furl is shipped as a Python package (`furl-ctx`) with an MCP server exposing six tools: `furl_compress`, `furl_retrieve`, `furl_search`, `furl_list`, `furl_stats`, and `furl_purge`, plus a seventh tool `furl_read` that is off by default. Both use the same compression pipeline: per-content-type compressors (JSON, search results, logs, diffs) feed into a Compress-Cache-Retrieve (CCR) store so compression stays reversible — the LLM can ask for the original on demand, within the configured retention window (default TTL 1800 s; entries are also capacity-evicted oldest-first, and an expired/evicted retrieval is a loud miss, never silent).

## Packages

- [PyPI package](https://pypi.org/project/furl-ctx/): Python install.

## Install (copy-paste-runnable)

- Python: `pip install furl-ctx` (add `[all]` for every optional extra)
- MCP server: `pip install "furl-ctx[mcp]"` then run `python -m furl_ctx.ccr.mcp_server`
- Compress in code: `from furl_ctx import compress`

## Docs

- [Get started](README.md#quick-install): two-command installs for Claude Code (automatic hooks + MCP + skill) and Codex (MCP + skill); no `pip install` needed.
- [How it works](LIBRARY.md#how-it-works): pipeline diagram + per-content-type compressors.
- [Proof / benchmark table](README.md#proof): measured reductions on committed real captures (50–96% per dataset, redundancy-dependent; lossy rows are CCR-recoverable).
- [Configuration (environment variables)](LIBRARY.md#configuration-environment-variables): every live `FURL_*` knob with defaults.
- [Full benchmark methodology](BENCHMARKS.md): adversarial multi-seed sweep and honest-metrics definitions. See [the three public headline numbers](BENCHMARKS.md#the-three-public-headline-numbers) for how the 95% ceiling, the 91.5% six-capture subset, and the 0-54% high-entropy band relate.
- [Current baseline numbers](benchmarks/BASELINE.md): the deterministic per-dataset capture at HEAD.
- [CCR retention contract](CCR-RETENTION.md): exactly how long "reversible" lasts and what evicts.
- [Rust core developer guide](RUST_DEV.md): building the extension, workspace layout, store internals.
- [Contributing](CONTRIBUTING.md): PR policy and review gates.
- [Security policy](SECURITY.md): reporting vulnerabilities.

## Licensing

Apache 2.0. Use commercially, modify, redistribute. Data stays on the user's machine when running the library or MCP server locally. There is no telemetry — nothing is recorded or sent anywhere beyond the local session state the MCP server keeps on disk.