buffer

Session management for OpenClaw agents. Context monitoring, structured handoffs, and performance optimization — so you never lose context again.

# Buffer

## First Run

Check if `buffer-optimizer` exists as a sibling skill directory. Look for `skills/buffer-optimizer/SKILL.md` relative to your workspace.

**If it does NOT exist**, extract it now:

1. Create directory `skills/buffer-optimizer/`
2. Write `skills/buffer-optimizer/SKILL.md` with the exact contents of the **Embedded: buffer-optimizer** section below.
3. If the skill references shell scripts (`{baseDir}/scripts/measure-boot.sh` and `{baseDir}/scripts/audit-agents-md.sh`), create those too from the **Embedded Scripts** section.
4. Run the **Setup** steps from the embedded optimizer (create HANDOFF.md if missing, validate MEMORY.md, check AGENTS.md structure).
5. Tell the owner what was set up and that workspace audits are now available via `buffer-optimizer`.

**If extraction fails** (sandbox, read-only filesystem, write tool denied):
- Tell the owner: "I can't write files to the skills directory. Install the optimizer separately: `clawhub install buffer-optimizer`"
- Continue with normal session management below.

**If buffer-optimizer already exists**, skip extraction. Proceed to the mode that matches your situation.

---

## Start

Run at every new session. Goal: recover context instantly.

1. Read HANDOFF.md — where you left off, outcomes, next steps.
2. Read MEMORY.md — priorities, projects, people.
3. Start working. Do not read other files unless the task requires them.

**No HANDOFF.md?** Check recent `memory/*.md` files, try `memory_search`, then ask the owner. Run `buffer-optimizer` to set up your workspace.

---

## Monitor

Apply continuously during the session.

### Intake
Before loading content:
- **Changed?** Don't re-read unmodified files.
- **Need all of it?** Use `grep`, `head`, `limit`/`offset` over full reads.
- **Can reference instead?** Write large output to file, read summary.
- **Cache impact?** Don't edit AGENTS.md/SOUL.md/USER.md/MEMORY.md mid-session (breaks prompt cache, 10x cost).

### Output
- Redirect heavy output (>20 lines) to `/tmp`, read tail/summary.
- Pipe long commands through `tail`/`head`/`grep`.

### Context Thresholds

Thresholds are percentages of your model's context window. Run `session_status` — the Context line shows current usage.

| Usage | Action |
|---|---|
| **<25%** | No concern. Full performance. |
| **25-40%** | Be intentional about what you load. |
| **40-50%** | ⚠️ Warn owner. Degradation begins on complex tasks. |
| **>50%** | 🔴 Wrap now. |

### Degradation signals — warn the owner and recommend wrapping if you notice:
- Repeating yourself (context distraction)
- Forgetting earlier decisions (retrieval failure)
- Ignoring relevant earlier context (recency bias)
- Confusion from conflicting information (context clash)
- Referencing something that was wrong earlier (context poisoning)

Do not wrap unilaterally — warn first, let the owner decide when to wrap.

### Continuous persistence
Don't wait for wrap to save important information. As decisions happen, append key outcomes to HANDOFF.md or a scratch file. If you have a long-term memory system, write decisions there immediately.

Test: if this session crashed now, would important stuff survive?

---

## Wrap

Run when: owner says "wrap session", you hit 50% context, or conversation concludes.

### Step 1: Extract from the session
Scan for: decisions, outcomes, open questions, corrections, next steps.

### Step 2: Write HANDOFF.md
Overwrite with current state:

```markdown
# HANDOFF.md

## Current Work
[One line — focus area.]

## Stopping Point
[One line — where you left off.]

## Key Outcomes
- [Conclusions, not activities. "X works because Y" not "tested X".]

## Open Questions
- [Each must be actionable by the next session.]

## Next Steps
1. [Most important first. ≤5 items.]
```

**Rules:**
- ≤2KB. Over? Compress outcomes to conclusions only.
- Outcomes = conclusions, not activities.
- Cut anything that doesn't affect future work.
- No architecture docs, standing policies, or issue lists.

### Step 3: Update MEMORY.md only if structure changed
New project, priority shift, new key person, or week rollover. Most sessions: don't touch it.

### Step 4: Persist unpersisted decisions
Scan for decisions or outcomes not yet captured in HANDOFF.md.

### Step 5: Confirm to owner
What was saved. Whether MEMORY.md was updated. Top next step.

---

## Quick Reference

| File | Purpose | Target | Updated |
|---|---|---|---|
| HANDOFF.md | Session state — recovery file | ≤2KB | Every wrap |
| MEMORY.md | Big picture — priorities, projects, people | ≤1.5KB | When structure changes |
| AGENTS.md | Behavioral rules | ≤4KB | Rarely |

| Zone | Range | Behavior |
|---|---|---|
| Green | <25% | Full performance |
| Yellow | 25-40% | Intentional loading |
| Orange | 40-50% | Warn owner, prepare to wrap |
| Red | >50% | Wrap immediately |

---

## Embedded: buffer-optimizer

On first run, write this as `skills/buffer-optimizer/SKILL.md`:

```
---
name: buffer-optimizer
description: "Workspace auditing and setup for Buffer. Measures boot payload, checks AGENTS.md structure, classifies skills, validates memory files. Run on first install, when things feel off, or every week or two. Companion to the buffer skill."
---

# Buffer Optimizer

Two modes: **setup** (first install) and **audit** (periodic maintenance).

---

## Setup

Run on first install, or when the owner asks to configure their workspace.

### 1. Create HANDOFF.md
If missing, create:

# HANDOFF.md
## Current Work
## Stopping Point
## Key Outcomes
## Open Questions
## Next Steps

### 2. Validate MEMORY.md
Must contain only: this week (2-3 lines), priorities (≤5), project states (one line each), key people. Target: ≤1.5KB. If missing, create a minimal version with the owner's name and current focus.

### 3. Check AGENTS.md structure
Verify these exist. If missing, draft them and present to owner for approval:

**Pre-response checkpoint** (must be the first section):

## Before Every Response
1. Does this message match a skill trigger? → Load that skill.
2. Am I about to do something a skill already handles? → Use the skill.

**Skill trigger table** (immediately after checkpoint):

## Skill Triggers
| Event | Skill |
|---|---|
| [event] | [skill-name] |

**Negative triggers:**

## Don't Reinvent Skills
- [manual pattern] → Use [skill-name]

**Context management rules:**

## Context Management
- Heavy output (>20 lines): redirect to file, read summary.
- Use targeted reads (limit/offset, grep, tail) over full file loads.
- 40-50% context: Warn owner. >50%: Wrap immediately.
- Don't edit boot files mid-session (breaks prompt cache, 10x cost).

### 4. Classify skills
List all loaded skills. Classify as DAILY/WEEKLY/RARE/NEVER. Draft a daily driver list. Flag NEVER skills for potential exclusion.

### 5. Report setup status
Tell the owner what was created, what was validated, and what needs their review.

---

## Audit

Run periodically (weekly or bi-weekly), after major changes, or when the owner asks.

### Step 1: Measure Boot Payload

Run `bash {baseDir}/scripts/measure-boot.sh` if the script exists. Otherwise measure manually.

#### Thresholds

| File | Target | Action if exceeded |
|---|---|---|
| AGENTS.md | ≤4KB | Convert descriptions to directives. Move reference content out. |
| MEMORY.md | ≤1.5KB | Keep only: this week, priorities, projects, people. |
| HANDOFF.md | ≤2KB | Apply template: current work, stopping point, outcomes, questions, next steps. |
| Each memory/*.md | ≤2KB | Summarize transcripts. |
| Total boot | ≤12KB | Something doesn't belong in boot. |
| Skills loaded | <20 | Exclude unused skills (~75 tokens each). |

### Step 2: Audit AGENTS.md

Run `bash {baseDir}/scripts/audit-agents-md.sh` if the script exists. Otherwise check manually.

Verify:
- 2.1 Pre-response checkpoint is the first section.
- 2.2 Skill trigger table immediately follows.
- 2.3 Negative triggers section exists.
- 2.4 No weak patterns ("You have access to", "Consider", "Try to", "If appropriate"