Clever Compact

Your OpenClaw agent forgets everything between sessions — after /new, after compaction, after overnight. Clever Compact fixes all three: injects your last st...

Security Scan

The skill's code and runtime instructions align with its stated purpose: it writes and later restores local plaintext state files to reduce compaction loss; it does not ask for external credentials or network access and its filesystem usage matches the documented behavior.

Purpose & Capability

Name/description, SKILL.md, index.ts, and manifest are consistent: the plugin reads/writes state files in a local memory/ directory and injects the most-recent file at session start. All required capabilities (filesystem access in workspace) are proportionate to the stated goal.

Instruction Scope

Runtime instructions limit actions to writing a Markdown state file and injecting it once at session start. The SKILL.md explicitly warns not to include secrets and documents trigger mechanisms (manual, cron, heartbeat, api.fn). No instructions attempt to read other system configuration or transmit files externally.

Install Mechanism

No remote install/downloads or third-party registries are used; installation is local (copy folder or openclaw plugins install from local path) and the plugin consists of the included files. This is low-risk and expected for an OpenClaw extension.

Credentials

The plugin reads OPENCLAW_WORKSPACE and HOME to locate the workspace and creates files under memory/. It does not request secrets or external credentials. Note: state files are plaintext and may capture sensitive data if the agent/automation includes it; the docs warn about this, but filesystem writes are inherently sensitive and should be audited.

Persistence & Privilege

The skill does not set always:true and doesn't modify other skills. It exposes api.fn("clever-compact:write") so other tools/automations can programmatically trigger state writes — this is intentional and useful, but any automation that calls that function should be audited so it doesn't cause unexpected captures of sensitive context.

Assessment

This plugin appears to do what it says: it saves and restores local plaintext state files to reduce memory loss across sessions. Before installing, review where files will be written (~/.openclaw/workspace/memory by default or OPENCLAW_WORKSPACE if set) and periodically inspect/delete memory/compact-state-*.md files to ensure no secrets were captured. Audit any cron/heartbeat/automation that will call api.fn("clever-compact:write") so it doesn't write credentials or other sensitive values. If you use this in a shared environment or backed-up workspace, consider tightening retention (maxStateAgeHours) and access controls on the memory directory.

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: [e-mail]

---

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.