OpenClaw Memory System: MEMORY.md, LCM, and How to Never Forget Anything

Why Memory Matters

MEMORY.md — Persistent Long-Term Memory

What Goes in MEMORY.md

Good candidates for MEMORY.md — facts that are hard to re-derive but important for continuity:

• →Active projects and their current status
• →API keys, URLs, and credentials your agent needs
• →Decisions already made (avoid re-arguing)
• →Tech stack choices and architecture decisions
• →Ongoing metrics or KPIs you track
• →People, companies, and relationships relevant to your work

# MEMORY.md — Active Context

## Projects

### SaaS Dashboard (ACTIVE)
- Stack: Next.js 15, Supabase, Vercel
- Repo: github.com/yourname/saas-dashboard
- Prod URL: https://app.yourdomain.com
- Status: v1.2 live, working on analytics module

### Newsletter Automation (PAUSED)
- Stack: Node.js + Ghost CMS + SendGrid
- Status: paused until April, waiting on design

## Key Decisions Made
- Using Supabase over PlanetScale (March 10) — better DX
- Tailwind v4 only, no custom CSS unless absolutely needed

## Active API Keys / Services
- Supabase project: project-ref-xyz
- SendGrid from address: hello@yourdomain.com

## Weekly Habits Automated
- Monday 9am: weekly metrics report → Telegram
- Friday 5pm: EOD summary pushed to Notion

Getting Your Agent to Update MEMORY.md Automatically

MEMORY.md is useless if it's stale. Configure your agent to update it proactively by adding instructions to SOUL.md:

## Memory Maintenance (Mandatory)
After ANY session where something significant happens,
update MEMORY.md immediately. Do NOT wait to be asked.

Things that always trigger a MEMORY.md update:
- New project started or completed
- New API key or tool configured
- Important architectural decision made
- New feature deployed to production

MEMORY.md Size Management

MEMORY.md loads into every session's context window, so keep it under ~2000 tokens (roughly 1500 words). Strategies to keep it lean:

• →Archive completed projects to a separate MEMORY_ARCHIVE.md
• →Keep decisions as one-liners ("Using X over Y because Z")
• →Remove anything you haven't referenced in 30+ days
• →Use shorthand for recurring items

LCM — Lossless Context Management

How LCM Works

1. 1Monitors conversation token count against the model's context limit
2. 2When approaching the limit, compresses older message groups into summaries (sum_xxx IDs)
3. 3Stores summaries in a local database (~/.openclaw/lcm/)
4. 4Makes summaries searchable and expandable on demand

{
  "lcm": {
    "enabled": true,
    "compressionThreshold": 0.8,
    "summaryModel": "claude-haiku-4",
    "retentionDays": 90,
    "searchEnabled": true
  }
}

Shared Workspace Files

Beyond MEMORY.md, your workspace contains several files automatically loaded into every session. These define the "operating system" for your agent:

# SOUL.md — Kade

## Identity
Kade — sharp, strategic, fast, loyal.

## Voice
- Minimalist. High signal. No fluff.
- Direct but never rude.
- Founder/builder tone.

## Values
Truth > Sycophancy · Clarity > Complexity

# USER.md — About Me

- **Name:** Your Name
- **Timezone:** GMT+1 (Belgrade)
- **Technical Level:** Advanced developer

## Communication Style
- Short, punchy answers preferred
- No corporate filler

# AGENTS.md

## Agent Topology
- Main: Kade (general purpose, orchestration)
- Research: Handles web research tasks

## Shared Memory
All agents read from: ~/.openclaw/workspace/shared/

The Right Memory Strategy

Weekly Memory Hygiene

Spend 5 minutes per week reviewing MEMORY.md. Ask:

1. 1Is anything in here outdated or completed?
2. 2Did I make any important decisions this week that aren't captured?
3. 3Are there credentials or URLs that changed?
4. 4Any new projects or tools added?

Advanced Memory Patterns

Project-Specific Memory Files

For complex projects, create dedicated memory files:

~/.openclaw/workspace/
├── MEMORY.md              # Master memory
├── SOUL.md                # Agent identity
├── USER.md                # User profile
├── projects/
│   ├── saas-dashboard.md  # Deep context for project 1
│   ├── newsletter.md      # Deep context for project 2
│   └── crypto-portfolio.md

Cross-Session Task Handoff

When a long task spans multiple sessions, save a structured handoff note:

## In Progress (Do Not Archive)

### API Integration Refactor [STARTED March 21]
- Completed: Auth module, User endpoints
- Next: Payment endpoints (start at src/api/payments.ts)
- Blockers: Waiting on Stripe webhook secret from Alex
- Context: Moving from REST to tRPC, see /docs/adr-003.md

Troubleshooting Memory Issues