# Clever Compact

> Your OpenClaw agent forgets everything between sessions — after /new, after compaction, after overnight. Clever Compact fixes all three: injects your last state on session start, flushes before every compact, and keeps memory stable across context resets. Native plugin. Zero per-turn overhead. Install in 3 commands, runs automatically.

- Skill: `dvcrn/clever-compact` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add dvcrn/clever-compact`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/clever-compact/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/clever-compact

---


# Clever Compact

**Publisher:** Axiom Stream Group  
**Version:** 2.2.2  
**Tier:** Free  
**Requires:** OpenClaw ≥ 2026.3.7  
**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. **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.

---

## Why explicit write is fine in practice

The compact happens *after* you hit the context limit. That means your agent is still active and responsive right up until compact fires. A cron job 5 minutes before your scheduled compact, or a heartbeat flush at 75% context, gives you a clean save point every time — without needing an OS-level hook that doesn't exist yet.

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

---

## Installation

> **Requires OpenClaw ≥ 2026.3.7**

**Step 1 — Install the plugin:**

```bash
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`:**

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

**Step 3 — Restart the gateway:**

```bash
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`:
```markdown
## 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

```markdown
# 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`:

```json
{
  "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.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.*