Fleet Memory Manager

Upgrade your agent's memory from basic notes to a 3-layer production system with nightly consolidation. Based on patterns from running 7 AI bots in production for 30+ days.

memory-manager

Upgrade your agent's memory from basic notes to a 3-layer production system with nightly consolidation. Based on patterns from running 7 AI bots in production for 30+ days.

---

Overview

Every AI agent has the same problem: it wakes up fresh every session with no memory of what happened before. The naive fix is a single MEMORY.md file — but that doesn't scale. After a few weeks, it's either a wall of text the agent ignores, or so curated it's missing operational context.

This skill installs a 3-layer memory architecture that mirrors how humans actually store knowledge:

Layer	File	What goes here
1 — Long-term	MEMORY.md	Curated wisdom, architecture decisions, hard-won lessons
2 — Operational	memory/YYYY-MM-DD.md	What happened today, active project state, raw context
3 — Tacit	USER.md	How your human works, preferences, frustrations, patterns

Plus a nightly consolidation cron that reviews recent sessions and promotes important context up the layers automatically.

---

When to Use This Skill

Activate this skill when the user asks you to:

• Set up memory for their agent
• Upgrade from a basic MEMORY.md system
• Add nightly consolidation or memory cron
• Improve agent continuity between sessions
• Track active projects across agent restarts
• Set up the memory-manager skill

---

Setup Instructions

Step 1: Run the Setup Script

bash

bash ~/.openclaw/skills/memory-manager/scripts/setup.sh

This creates the memory/ directory, copies templates into place, and prints next steps.

Step 2: Customize the Templates

After setup, edit these files in your agent's workspace:

1. MEMORY.md — Add your agent's existing long-term context
2. USER.md — Fill in who the human is, how they work, what frustrates them
3. AGENTS.md — Review the startup sequence (already wired for 3-layer loading)
4. HEARTBEAT.md — Configure which projects to monitor

Step 3: Configure the Startup Sequence

Your agent's AGENTS.md must include this memory loading sequence at the top of "Every Session":

markdown

## Every Session

Before doing anything else:
1. Read `SOUL.md` — identity and persona
2. Read `USER.md` — who you're helping and how they work  
3. Read `memory/YYYY-MM-DD.md` (today) — what happened today
4. Read `memory/YYYY-MM-DD.md` (yesterday) — recent context bridge
5. **If in MAIN SESSION** (direct chat with your human): Also read `MEMORY.md`

Why read yesterday too? Sessions started after midnight won't have today's file yet. Yesterday bridges the gap. This prevented context loss in our production fleet during late-night sessions.

Step 4: Set Up Nightly Consolidation

Add a cron job to consolidate memory each night at 2 AM:

text

0 2 * * * openclaw cron run memory-consolidation --model anthropic/claude-opus-4-5 --channel <your-main-channel-id>

The consolidation prompt to configure in OpenClaw cron:

text

You are performing nightly memory consolidation for this agent.

Tasks:
1. Read memory/YYYY-MM-DD.md files from the last 7 days
2. Read the current MEMORY.md
3. Identify: significant decisions, lessons learned, architecture changes, resolved issues, evolving patterns
4. Update MEMORY.md with distilled insights (add new, update stale, remove obsolete)
5. Check USER.md — update any new preferences or patterns you observed
6. Write a brief summary of what you consolidated to memory/consolidation-log.md

Be selective. MEMORY.md should stay under 500 lines. Quality over quantity.
Signal completion: reply "CONSOLIDATION_COMPLETE" to the channel when done.

Why 2 AM? Low activity period. The consolidation model has full context of the day's events. Running nightly (not weekly) means no single consolidation is overwhelming.

---

Memory Loading Rules

In Main Session (direct human chat)

Load all three layers:

text

SOUL.md → USER.md → memory/today.md → memory/yesterday.md → MEMORY.md

In Group Chats / Shared Channels

Load only layers 2 and 3 (no MEMORY.md):

text

SOUL.md → USER.md → memory/today.md → memory/yesterday.md

Why skip MEMORY.md in group chats? Long-term memory often contains personal context — private preferences, health info, financial details — that shouldn't leak into conversations with strangers. Daily operational notes are usually safe.

In Subagent / Worker Sessions

Load only today's notes:

text

memory/today.md (if relevant to task)

Subagents are ephemeral. Don't load full memory — it wastes tokens and context.

---

Daily Notes Format

Each memory/YYYY-MM-DD.md file follows this structure:

markdown

# YYYY-MM-DD

## Sessions

### [Time] — Session summary
- What happened
- Decisions made
- Tasks completed / in progress

## Active Projects

### Project Name
- **Status:** In Progress / Blocked / Complete
- **Last action:** What was done last
- **Next:** What needs to happen next
- **Blockers:** Anything blocking progress

## Context for Next Session

Key things future-me needs to know to pick up without re-explaining:
- [item 1]
- [item 2]

## Raw Log

(Less curated — dump things here that might matter)

The "Context for Next Session" section is the most important. Agents often end sessions mid-task. Without this section, the next session has to reconstruct state from scratch. Write it as if briefing a colleague who just joined the project.

---

Active Project Tracking

Projects move through these states in daily notes:

text

PLANNING → IN_PROGRESS → BLOCKED → REVIEW → COMPLETE

The heartbeat integration (see HEARTBEAT.md) checks active projects and surfaces blockers automatically.

---

MEMORY.md Curation Rules

Long-term memory should be:

• Curated, not comprehensive — the distilled essence, not raw logs
• Actionable — things that change future decisions
• Evergreen — not "what I did Tuesday" but "lesson learned from the Tuesday incident"
• Organized by topic — architecture, lessons, human preferences, recurring patterns

Things that belong in MEMORY.md:

• Architecture decisions and the reasoning behind them
• Lessons learned from failures
• Patterns in how the human works / thinks
• Important context about key projects
• Things you've been told to always/never do

Things that do NOT belong in MEMORY.md:

• One-off task completions
• Information that will be stale in a week
• Raw conversation transcripts
• Things already captured in USER.md

---

Heartbeat Integration

Add to your HEARTBEAT.md to enable project monitoring:

markdown

## Active Project Check

For each project in active_projects.json (if it exists):
1. Check last updated timestamp
2. If project hasn't been touched in >48h, surface it: "⚠️ [Project] hasn't been updated in X days"
3. If status is BLOCKED, surface blocker to human
4. If status is COMPLETE but not archived, prompt to archive

## Memory Health Check (weekly, Sundays)

1. Check MEMORY.md line count — if >500 lines, flag for pruning
2. Check memory/ folder — if daily files >30 days old exist, flag for archiving
3. Report: X daily files, MEMORY.md is X lines, last consolidation: [date]

---

File Reference

File	Location	Purpose
SKILL.md	~/.openclaw/skills/memory-manager/	This file
setup.sh	scripts/setup.sh	One-command installer
templates/MEMORY.md	templates/	Long-term memory template
templates/AGENTS.md	templates/	Startup sequence template
templates/USER.md	templates/	User profile template
templates/HEARTBEAT.md	templates/	Heartbeat config template