{"id":"4d9efeb6-9bfe-4cb6-a66f-4bda1635f4d7","slug":"autocondense","kind":"mcp","name":"autocondense","summary":"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.","owner":"jack66g","repoUrl":"https://github.com/jack66g/autocondense","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-27T04:53:01.000Z","addedAt":"2026-10-29T00:53:01.814Z","logoUrl":"https://avatars.githubusercontent.com/u/200968408?u=1d069ba57fba081d0c943fc40d6dd34219ec2b9a&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","developer-tools"],"tags":["ai-agents","claude-code","codex","context-compression","context-management","context-window","cursor","llm-agents"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-29T00:59:17.693Z","sample":false,"url":"https://conduits.dev/tools/autocondense","language":"Python","transports":["stdio"],"install":{"pypi":"autocondense"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# autocondense\n\n**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.**\n\nEnglish | [中文](README.zh-CN.md)\n\n## Why\n\nEvery 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:\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **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.\n- **Local & private.** A resident service bound to `127.0.0.1` only. No cloud, no API keys, no telemetry.\n\n## How it works\n\n```\nrules propose a candidate ──▶ agent self-judges (5-field form) ──▶ verdict\n                                     │                                │\n                              DEFERRED (backoff                COMPRESS_NOW\n                              5→10→20 turns)                          │\n                                     │                          write snapshot\n                                  keep working                    (delta mode)\n                                                                    │\n                                              after /compact ◀───────┤\n                                                     │                └▶ per-fact\n                                            priority restore pack  ──▶ memory segments\n                                            + re-read file hints\n```\n\nJudgment 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.\n\n## Architecture\n\n```\n┌────────────────────────────── host agent ───────────────────────────────┐\n│  ZCode / Claude Code / Codex / Cursor                                    │\n│    │ MCP (stdio)                              │ hooks (stdin→stdout)    │\n│    ▼                                          ▼                         │\n│  mcp_server.py (thin proxy, 7 tools,     ac_hook.py (event forwarder,   │\n│  lazy service spawn, cwd→session map)     Stop can block, latch-guarded,│\n│                                            SessionStart injects restore)│\n└──────────┬─────────────────────────────────────┬───────────────────────┘\n           │ HTTP 127.0.0.1:8761  (trust_env=False)\n           ▼                                     │\n┌───────────────────────────────────────────────▼─────────────────────────┐\n│  autocondense.service  (FastAPI, the single writer)                      │\n│    /session/start /report /check /judge /begin /commit /restore          │\n│    /status /config /events/hook                                           │\n│    signals · state · digest · sme_bridge · config                        │\n└──────────────┬─────────────────────────────────────────┬────────────────┘\n               ▼                                         ▼\n   ~/.autocondense/ (atomic writes:         optional memory backend\n   config, snapshots + index, sessions,     (local HTTP API, degrades\n   delta-state, service.pid)                gracefully when offline)\n```\n\nDesign notes: [docs/设计.md](docs/设计.md) · Full REST contract: [docs/CONTRACT.md](docs/CONTRACT.md) (Chinese).\n\n## Install\n\nRequirements: Python 3.10+, `pip install -r requirements.txt`.\n\n**ZCode (desktop, recommended)** — via the plugin marketplace (the desktop app does not read `~/.zcode/cli/config.json`):\n\n1. Marketplace → Add → Add Plugin Marketplace → paste the `plugins/` directory of this repo\n2. Personal → **autocondense** → Install\n3. New conversation: MCP auto-connects, all four hooks register, skill + `/condense` command ship with the plugin\n\n**Other hosts (Claude Code / Codex / Cursor, and ZCode CLI)** — installer, dry-run by default:\n\n```bash\npython installer.py                # preview diffs per host\npython installer.py --hosts claude,codex,cursor --yes\npython installer.py --uninstall --yes   # removes only our entries\n```\n\nManual configs for every host: [docs/接入.md](docs/接入.md) (Chinese).\n\n**Verify:**\n\n```bash\npython -m pytest -q                          # 187 tests\npython -m autocondense.service --port 8761 & curl http://127.0.0.1:8761/health\n```\n\n## The seven MCP tools\n\n| Tool | When | What |\n| --- | --- | --- |\n| `condense_restore` | session start / after compaction | priority restore pack + memory hits + next actions |\n| `condense_report` / `condense_check` | after each task batch / turn | report plan items, get candidate verdict |\n| `condense_judge` | when `should=JUDGE` | submit the 5-field judgment form (agent self-assessment) |\n| `condense_begin` / `condense_commit` | after COMPRESS_NOW | get template (delta by default) → submit snapshot |\n| `condense_status` | debugging | service / sessions / config overview |\n\n## Judgment pipeline (rules, in order)\n\n1. in-progress tasks > 0 → **NO** (task continuity first)\n2. cooldown → **NO**\n3. all plan items completed → candidate / `plan_done`\n4. task spanning ≥5 turns completed → candidate / `task_done`\n5. water level ≥70% (host-reported tokens preferred) → candidate / `water_level`\n6. ≥3 turns without file edits or failures → candidate / `idle`\n7. ≥25 turns since last compress → candidate / `turns`\n\n## Configuration\n\n`~/.autocondense/config.json` (hot-reload via `PUT /config`); key items:\n\n| Key | Default | Meaning |\n| --- | --- | --- |\n| `enabled` | `true` | fully automatic vs completely inert |\n| `cooldown_minutes` / `turns_threshold` / `water_threshold` | 30 / 25 / 0.7 | candidate thresholds |\n| `usable_context_tokens` | 160000 | context window for water level |\n| `judge_defer_turns` / `judge_defer_max_turns` | 5 / 20 | deferred-judgment backoff cap |\n| `restore_max_chars` / `restore_reread_files` | 8000 / 5 | restore pack budget & re-read list |\n| `delta_mode` / `delta_merge_every` | true / 5 | incremental snapshots & full-merge cycle |\n| `idle_signal_rounds` | 3 | idle candidate threshold |\n| `sme.*` | — | memory backend: url, segmentation, dedup threshold, batch size |\n\n## FAQ\n\n- **SME/memory backend offline?** Everything degrades: snapshots still land on local disk, restore skips memory hits, judgment is unaffected. Never blocks.\n- **Port 8761 occupied?** Start with `--port 8762`, set `AUTOCONDENSE_PORT` (MCP) and `AUTOCONDENSE_BASE_URL` (hooks).\n- **Disable temporarily?** `PUT /config {\"enabled\": false}` — instantly inert, or just disable the plugin in the host.\n- **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.\n\n## License\n\nApache-2.0\n"}