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: [email protected]

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. 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:

openclaw plugins install ./skills/clever-compact

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

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

{
  "plugins": {
    "allow": ["clever-compact"]
  }
}

Step 3 — Restart the gateway:

openclaw gateway restart

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

Option A — Cron (recommended):

Schedule: 5 minutes before your nightly compact
Payload: "Pre-compaction memory flush. Store durable memories now (memory/YYYY-MM-DD.md). If nothing to store, reply NO_REPLY."

Option B — Heartbeat: Add to HEARTBEAT.md:

## Context Flush (every heartbeat at >75% context)
- If context > 75%: run a Clever Compact flush — write state to memory/compact-state-YYYY-MM-DD-HHmm.md

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

State file format

# Compact State — [ISO TIMESTAMP]
_Generated by Clever Compact v2.2.0 | Axiom Stream Group_

## Active Workstreams
| Name | Status | Blocker | Notes |
|---|---|---|---|
| [name] | in-progress | [blocker or —] | [key context] |

## Key Decisions
- [Decision]: [rationale / constraint]

## Open Tasks
- [ ] [Task] — Owner: [person or agent]

## Remember Flags
- [Anything explicitly flagged]

---
_Next session: read this file before responding to anything._

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:

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "reserveTokens": 15000
      }
    }
  }
}

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. Remove the Clever Compact blocks from your AGENTS.md
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.