Clever Compact

Publisher: Axiom Stream Group
Version: 2.2.3
Tier: Free
Requires: OpenClaw ≥ 2026.3.7 · Recommended: 2026.3.12+ (fixes double-compaction loop)
ClaWHub: https://clawhub.ai/jfulmines-star/clever-compact
Support: kit@axiomstreamgroup.com

---

What This Skill Does

Clever Compact fixes the three memory failure modes that hit every serious OpenClaw user:

• - /new amnesia — you start a fresh session and your agent acts like it's never met you
• Compaction loss — context fills up, compact fires, the agent forgets what you were doing mid-task
• Memory drift — decisions made three sessions ago quietly disappear; the agent makes the same mistake again

v2 is a native OpenClaw plugin with two parts:

Part 1 — Session restore (automatic)

At the start of every session (including after /new and after compaction), Clever Compact checks for a recent state file. If one exists (written within 72 hours), it injects the content as system context on the first turn only. Your agent wakes up oriented — no repeated context injections, no per-turn token overhead.

Part 2 — State write (triggered)

OpenClaw does not currently expose a pre-compaction lifecycle hook, so the write side is triggered explicitly — not automatic. You have three options:

1. 1. Manual trigger: Tell your agent "Run a Clever Compact flush and save state." It writes memory/compact-state-YYYY-MM-DD-HHmm.md immediately.
2. Pre-compact cron: Set up a cron job that fires before your scheduled compact with the system event: "Pre-compaction memory flush. Store durable memories now." Your agent writes state, then compact fires.
3. Heartbeat entry: Add a flush step to your HEARTBEAT.md that periodically writes state — no timing races because it runs on demand.

The plugin also exposes api.fn("clever-compact:write") so any tool in your stack can trigger a state write programmatically.

---

Security & Privacy

State files are stored as plaintext Markdown in your memory/ directory. They are local to your machine and not transmitted anywhere by this plugin.

Do not include in state files:

• - API keys, tokens, or secrets
• Passwords or credentials
• Private personal information you wouldn't put in a text file

The plugin generates a reminder header in every state file. Review memory/compact-state-*.md periodically and remove any sensitive content that may have been captured inadvertently.

The api.fn("clever-compact:write") exposure is intentional — it allows your heartbeat, cron, or other tools to trigger a state flush programmatically. Audit any automation that calls this function to ensure it writes only session context, not credentials.

---

How the write side works

Your agent is active and responsive right up until compact fires — so a cron job 5 minutes before your scheduled compact, or a heartbeat flush at 75% context, gives you a clean, predictable save point every time.

When OpenClaw ships a pre-compaction lifecycle hook, Clever Compact will use it automatically. Until then, the cron + heartbeat pattern is the right architecture — and it works.

---

Installation

Requires OpenClaw ≥ 2026.3.7

Step 1 — Install the plugin:

CODEBLOCK0

Or copy the folder to ~/.openclaw/extensions/clever-compact/.

Step 2 — Add to plugins.allow in ~/.openclaw/openclaw.json:

CODEBLOCK1

Step 3 — Restart the gateway:

CODEBLOCK2

Step 4 — Set up a flush trigger (pick one):

Option A — Cron (recommended):
CODEBLOCK3

Option B — Heartbeat:
Add to HEARTBEAT.md:
CODEBLOCK4

Option C — Manual:
Tell your agent: "Run a Clever Compact flush and save state."

---

State file format

CODEBLOCK5

State files live in memory/ and are ignored after 72 hours.

---

Reduce compaction frequency (recommended)

Push compaction later in the context window by lowering reserveTokens:

CODEBLOCK6

Default is 50,000 (fires at ~150k/200k). Setting to 15,000 fires at ~185k — roughly 3–4× fewer compactions per heavy session.

---

Migration from v2.0 / v2.1

The injection behavior is unchanged. One fix to apply:

v2.0/v2.1 injected the state file on every prompt turn — this added token overhead mid-session and contributed to faster compactions. v2.2.0 injects only once per session (first turn). No other changes needed; your existing state files and cron setup carry over.

Migration from v1

1. 1. Remove the Clever Compact blocks from your INLINECODE17
2. Remove heartbeat entries that referenced the pre-compact scan
3. Follow the v2 installation steps above
4. Existing state files in memory/ are picked up automatically

---

Changelog

• - 2.2.3 (2026-03-16): Version sync across all files (package.json, openclaw.plugin.json, index.ts were mismatched). Fixed install step count in description. Updated recommended OpenClaw version to 2026.3.12+. Rewrote defensive "explicit write" section. No functional changes.
• 2.2.0 (2026-03-11): Fixed per-turn injection (now injects once at session start only — eliminates mid-session token overhead). Accurately documents write side as explicit/triggered, not automatic. Exposes clever-compact:write fn for programmatic state writes. No breaking changes.
• 2.1.0 (2026-03-10): Added writeState() export. Clarified hooks.
• 2.0.0 (2026-03-08): Full rewrite as native OpenClaw plugin. Requires OpenClaw ≥ 2026.3.7. Breaking change from v1.
• 1.3.1 (2026-03-06): Clarified config/reference language. No functional changes.
• 1.3.0 (2026-03-05): Fully free. All features available at no cost.
• 1.2.0 (2026-03-04): Reframed around the three failure modes.
• 1.1.0 (2026-03-03): Added reserveTokens tuning guide.
• 1.0.0 (2026-03-01): Initial release.

---

Built by Axiom Stream Group — axiomstreamgroup.com We built this because we needed it. We run it on our own agents every day.