Agent Memory Tiers

Stop your agents from forgetting everything between runs.

OpenClaw agents start every activation with zero memory of what they did last time. They waste hundreds or thousands of tokens re-reading old files, parsing chat history, and reconstructing context. This skill fixes that.

Agent Memory Tiers is a structured, self-updating memory system that gives agents instant context on startup. Two files, updated automatically at the end of every run, so the next activation starts warm.

Tested in production across a 20-agent swarm running daily for 3+ weeks.

How It Works

Two memory layers sit in each agent's workspace:

Layer	Purpose	Size	Loaded
L0	Instant state snapshot	4 lines	Every activation
L1

7-day rolling context | ~20-40 lines | Every activation |
| L2+ | Historical memory | Varies | Only when needed |

The agent reads L0 and L1 before doing anything else. Before finishing, it updates both files. Next activation picks up exactly where this one left off.

Token savings: 300-3700 tokens per activation depending on agent complexity. Over a week of daily runs, that adds up fast.

Setup

Step 1: Create L0.md in your agent's workspace

CODEBLOCK0

Example — a content agent:

CODEBLOCK1

Example — a monitoring agent:

CODEBLOCK2

Step 2: Create L1.md in your agent's workspace

CODEBLOCK3

Example — a lead generation agent:

CODEBLOCK4

Step 3: Add the Quick Context header to your SOUL.md

Paste this at the top of your agent's SOUL.md file, right after the role description:

CODEBLOCK5

Step 4: Add the End-of-Run footer to your SOUL.md

Paste this at the bottom of your agent's SOUL.md file:

CODEBLOCK6

Why This Structure

L0 is for speed. Four lines. The agent reads it in under 50 tokens and immediately knows: who am I, what should I focus on, what did I do last, and is anything broken. No digging through files.

L1 is for context. Seven days of history, three active tasks, key numbers, and blockers. Enough to make informed decisions without loading the full memory archive. Stays under 200 tokens for most agents.

L2+ is on-demand. Historical memory files in a memory/ folder. Only loaded when the task explicitly requires older context. This keeps routine activations fast and cheap.

Self-updating is critical. The agent writes its own L0/L1 before finishing. No external process needed. No sync scripts. The agent that did the work is the one that records what happened.

Multi-Agent Coordination

When running multiple agents, any orchestrator agent can read another agent's L0.md to get instant status without interrupting it or parsing logs.

CODEBLOCK7

This eliminates the "is this agent available?" guessing game and prevents task collisions in multi-agent setups.

Common Mistakes

Mistake	Fix
L0 grows beyond 4 lines	Ruthlessly compress. If it does not fit in 4 lines, it belongs in L1.
L1 "Last 7 Days" keeps growing

Hard cap at 7 entries. Drop the oldest every time you add a new one. | | Agent skips the end-of-run update | Put "MANDATORY" in the SOUL.md footer. Bold it. Agents follow strong directives. | | L1 blockers pile up | Remove blockers the moment they are resolved. Stale blockers cause confusion. | | Storing detailed logs in L1 | L1 is summaries only. One line per day. Details go in dedicated log files. | | Using relative dates ("yesterday") | Always use absolute dates (YYYY-MM-DD). The agent does not know when it last ran. |

Error Handling

Agent does not read L0/L1 on startup:
The "Quick Context" header in SOUL.md must be near the top. If it is buried below other instructions, the agent may skip it. Move it directly after the role description.

Agent overwrites L0/L1 with garbage:
This usually means the SOUL.md footer instructions are too vague. Use the exact template above with explicit line counts and section names. Agents follow precise structure better than general guidance.

L1 file grows too large (over 50 lines):
Your "Key State" section is probably accumulating instead of updating. Each run should replace old state values, not append. Restructure: state is current values, not a changelog.

Multiple agents writing to the same L0/L1:
Each agent must have its own L0.md and L1.md in its own workspace. Never share these files between agents. The orchestrator reads them, but only the owning agent writes them.

Permissions

This skill requires:

• - File read/write in the agent's workspace directory — to read and update L0.md and L1.md.
• No network access required.
• No external API access required.
• No sensitive data access required.

Credits

Built and battle-tested by the Megaport swarm team. Inspired by the OpenViking tiered memory architecture.

License

MIT — use it, modify it, share it.