autocondense

Zero-prompt context compression for AI coding agents — LLM-judged timing, incremental session snapshots, and per-fact long-term memory. MCP-native, works with Claude Code, Codex, Cursor & ZCode.

English | 中文

Why

Every agent ships auto-compact: it fires at a hard token threshold and hopes the summary lands well — usually mid-task. autocondense takes a different route:

• The agent decides when to compress. Rule signals (plan closed, long task finished, water level, idle streak) only propose a candidate. The agent itself answers a 5-field judgment form — is the task finished? what's the impact of compressing right now? is anything unsaved? — and only then is a snapshot written. The best moment to compress is a task boundary; no threshold knows where it is, the agent does.
• Snapshots are structured and incremental. A fixed template (goals / done / pending / decisions / pitfalls / file changes / restore pointers). Delta-only by default with a full merge every 5 snapshots — countering the well-known quality decay of repeated compaction.
• Memory, not a blob. Each snapshot is split into per-fact segments — every decision, pitfall, todo and accomplishment stored separately with its own tags and importance — so retrieval and reinforcement (Ebbinghaus-style) hit individual facts, and everything survives across sessions via an optional local memory backend.
• Restoration is priority-packed. After /compact the agent gets pending items and restore pointers first, plus a short list of key files to re-read — not a wall of truncated text.
• Fully automatic, or fully off. enabled=true means zero prompts and zero confirmations; enabled=false means the plugin is completely inert. There is no "should I compress?" chatter, ever.
• Local & private. A resident service bound to 127.0.0.1 only. No cloud, no API keys, no telemetry.

How it works

rules propose a candidate ──▶ agent self-judges (5-field form) ──▶ verdict
                                     │                                │
                              DEFERRED (backoff                COMPRESS_NOW
                              5→10→20 turns)                          │
                                     │                          write snapshot
                                  keep working                    (delta mode)
                                                                    │
                                              after /compact ◀───────┤
                                                     │                └▶ per-fact
                                            priority restore pack  ──▶ memory segments
                                            + re-read file hints

Judgment matrix: normal requires task finished AND low impact AND safe; urgent (water level ≥85%) only requires safe AND impact ≠ high — when the host is about to lossily compact anyway, archiving first is a net win even mid-task.

Architecture

┌────────────────────────────── host agent ───────────────────────────────┐
│  ZCode / Claude Code / Codex / Cursor                                    │
│    │ MCP (stdio)                              │ hooks (stdin→stdout)    │
│    ▼                                          ▼                         │
│  mcp_server.py (thin proxy, 7 tools,     ac_hook.py (event forwarder,   │
│  lazy service spawn, cwd→session map)     Stop can block, latch-guarded,│
│                                            SessionStart injects restore)│
└──────────┬─────────────────────────────────────┬───────────────────────┘
           │ HTTP 127.0.0.1:8761  (trust_env=False)
           ▼                                     │
┌───────────────────────────────────────────────▼─────────────────────────┐
│  autocondense.service  (FastAPI, the single writer)                      │
│    /session/start /report /check /judge /begin /commit /restore          │
│    /status /config /events/hook                                           │
│    signals · state · digest · sme_bridge · config                        │
└──────────────┬─────────────────────────────────────────┬────────────────┘
               ▼                                         ▼
   ~/.autocondense/ (atomic writes:         optional memory backend
   config, snapshots + index, sessions,     (local HTTP API, degrades
   delta-state, service.pid)                gracefully when offline)

Design notes: docs/设计.md · Full REST contract: docs/CONTRACT.md (Chinese).

Install

Requirements: Python 3.10+, pip install -r requirements.txt.

ZCode (desktop, recommended) — via the plugin marketplace (the desktop app does not read ~/.zcode/cli/config.json):

1. Marketplace → Add → Add Plugin Marketplace → paste the plugins/ directory of this repo
2. Personal → autocondense → Install
3. New conversation: MCP auto-connects, all four hooks register, skill + /condense command ship with the plugin

Other hosts (Claude Code / Codex / Cursor, and ZCode CLI) — installer, dry-run by default:

python installer.py                # preview diffs per host
python installer.py --hosts claude,codex,cursor --yes
python installer.py --uninstall --yes   # removes only our entries

Manual configs for every host: docs/接入.md (Chinese).

Verify:

python -m pytest -q                          # 187 tests
python -m autocondense.service --port 8761 & curl http://127.0.0.1:8761/health

The seven MCP tools

Judgment pipeline (rules, in order)

1. in-progress tasks > 0 → NO (task continuity first)
2. cooldown → NO
3. all plan items completed → candidate / plan_done
4. task spanning ≥5 turns completed → candidate / task_done
5. water level ≥70% (host-reported tokens preferred) → candidate / water_level
6. ≥3 turns without file edits or failures → candidate / idle
7. ≥25 turns since last compress → candidate / turns

Configuration

~/.autocondense/config.json (hot-reload via PUT /config); key items:

FAQ

• SME/memory backend offline? Everything degrades: snapshots still land on local disk, restore skips memory hits, judgment is unaffected. Never blocks.
• Port 8761 occupied? Start with --port 8762, set AUTOCONDENSE_PORT (MCP) and AUTOCONDENSE_BASE_URL (hooks).
• Disable temporarily? PUT /config {"enabled": false} — instantly inert, or just disable the plugin in the host.
• Plugin upgrade leaves a stale service? The MCP proxy health-checks the version and takes over the old process automatically via service.pid — never kills blindly.

License

Apache-2.0