🧠 Memory Guide

Build persistent context that makes your agent smarter over time. Master the memory system for truly personalized AI.

Why Memory Matters

AI agents start fresh every conversation. They don't remember yesterday's decisions, last week's projects, or the preferences you've shared over months. Memory changes everything.

❌ Without Memory

  • "What project were we working on?"
  • Repeating the same context every time
  • Forgetting user preferences
  • No learning from past mistakes

✅ With Memory

  • "Continuing the SEO audit from yesterday..."
  • Instant context from files
  • Remembers how you like things done
  • Builds on past lessons

🏗️ Memory Architecture

OpenClaw uses a two-tier memory system inspired by how human memory works:

📅

Short-Term: Daily Logs

memory/YYYY-MM-DD.md

Raw notes from each day. Like a journal — everything gets dumped here. What happened, decisions made, context discovered.

  • One file per day
  • Fast to write, low effort
  • Contains the full detail
  • Recent files loaded at startup
→
🧠

Long-Term: MEMORY.md

MEMORY.md

Curated wisdom distilled from daily logs. Important decisions, lessons learned, key preferences. The essential context.

  • Single canonical file
  • Periodically updated
  • Only the important stuff
  • Loaded in main sessions only (security)

The Memory Flow

1

Daily Work: Agent logs raw notes to memory/2026-02-07.md

2

Session Startup: Agent reads today's + yesterday's memory files

3

Periodic Review: Agent distills key insights into MEMORY.md

4

Context Recall: Semantic search finds relevant past context

📋 Structuring MEMORY.md

A well-organized MEMORY.md makes context retrieval fast and accurate. Here's a proven structure:

# MEMORY.md - Long-Term Memory

*Last updated: 2026-02-07*

---

## 👤 About the User

- Prefers bullet points over paragraphs
- Timezone: Australia/Brisbane
- Communication style: direct, no fluff
- Model preferences: reasoning model for strategy, coding model for implementation

---

## 🏢 Work Context

### Current Clients
| Client | Website | Status |
|--------|---------|--------|
| Acme Co | acme.com | Active - Monthly SEO |
| Widget Inc | widgets.io | Paused |

### Active Projects
- SEO audit for Acme Co (due Feb 15)
- Website migration for Widget Inc (on hold)

---

## 🔑 Key Decisions

### 2026-02-05: Switched to new rank tracker
- Old tool had accuracy issues
- New tool costs more but better data
- Reason: Client satisfaction > cost savings

### 2026-01-20: Changed content workflow
- Now using markdown → HTML pipeline
- Previous: direct WordPress editing
- Result: 3x faster publishing

---

## 📝 Lessons Learned

- Always confirm before sending client emails
- User prefers morning updates (8-9am local)
- Git commit messages should reference ticket numbers
- Don't use tables in Discord messages (bad formatting)

---

## 🛠️ Tools & Services

| Service | Location | Notes |
|---------|----------|-------|
| SEO Dashboard | localhost:8090 | Content pipeline |
| Rank Tracker | localhost:8097 | Daily position checks |
| Client Portal | localhost:8102 | Token-based access |

---

## 📁 Important Locations

- Client files: `~/workspace/clients/`
- Google Drive Clients folder: `1XFhN6...` (folder ID)
- SSH config for VPS: `~/.ssh/config`

---

*Update this file with important learnings, not raw logs.*

💡 Pro Tips

  • Use tables for structured data (clients, services, locations)
  • Date your decisions so you can trace reasoning later
  • Keep it scannable — use headers, bullets, and short entries
  • Include "why" not just "what" for key decisions
  • Prune regularly — remove outdated info that's no longer relevant

📅 Daily Memory Logs

Daily logs are your raw working notes. Low effort, high capture rate. Write everything — you'll filter later.

# 2026-02-07

## 🎯 Work Done
- Completed SEO audit for Acme Co
- Fixed broken redirects on client site
- Created 3 new blog posts (saved to Drive)

## 💡 Decisions Made
- Using a high-reasoning model for this client's strategy work
- Postponed Widget Inc migration to March

## 📝 Notes
- User mentioned they're traveling next week
- Acme CEO prefers PDFs over Google Docs
- Found duplicate content issue on /services page

## ⚠️ Issues
- Rank tracker API rate limited at 2pm
- Need to renew SSL cert for staging site

## 🔗 Links & References
- Acme audit: `clients/acme/audit-2026-02-07.md`
- Competitor analysis: Drive folder "Acme Research"

Recommended Sections

🎯 Work Done

Completed tasks, deliverables shipped

💡 Decisions

Choices made with reasoning

📝 Notes

Context, preferences, observations

⚠️ Issues

Problems encountered, blockers

🔗 References

Links to files, docs, resources

🤖 Model Used

Which AI model for which tasks

🔍 Memory Search & Recall

OpenClaw uses semantic search to find relevant memories. Instead of exact keyword matching, it understands meaning and context.

How It Works

1️⃣
Query

You ask about something ("What did we decide about the rank tracker?")

2️⃣
Search

Agent runs memory_search across MEMORY.md and memory/*.md files

3️⃣
Retrieve

Uses memory_get to pull specific lines with relevant context

4️⃣
Cite

Returns answer with Source: MEMORY.md#42 for verification

Writing Searchable Memories

Structure your memories so semantic search can find them:

  • Use descriptive headers — "Rank Tracker Decision" not just "Decision"
  • Include context words — mention related topics, people, projects
  • Date entries — helps disambiguate "which time?"
  • Be specific — "User prefers 9am AEST emails" not "User likes mornings"

📁 Project-Specific Memory

For complex projects, create dedicated memory files. Keeps detailed context separate from your main memory.

# memory/acme-seo-audit.md

## Project: Acme Co SEO Audit

**Started:** 2026-01-15
**Status:** In Progress
**Deadline:** 2026-02-15

---

## 🎯 Goals
- Improve organic traffic by 30%
- Fix technical SEO issues
- Create content strategy for Q2

## 📊 Current State (as of Feb 7)
- Domain Authority: 34
- Organic Traffic: 12,000/mo
- Top Keyword: "acme widgets" (#4)

## ✅ Completed
- [x] Technical audit
- [x] Competitor analysis
- [ ] Content gap analysis
- [ ] Final report

## 🔑 Key Findings
- 47 pages with missing meta descriptions
- Core Web Vitals failing on mobile
- Competitor "WidgetPro" outranks for 23 keywords

## 📝 Client Preferences
- CEO: Sarah, prefers PDFs
- Marketing: Tom, likes detailed data
- Meeting: Wednesdays 2pm AEST

## 🔗 Resources
- Audit spreadsheet: Google Drive "Acme/Audit-2026"
- Competitor data: `clients/acme/competitor-data.json`

💡 When to use project files: Create a project memory file when a project has deep context that would clutter MEMORY.md — usually anything lasting more than a week with multiple stakeholders or complex requirements.

🔄 Memory Maintenance

Memory isn't "set and forget." Regular maintenance keeps it useful and prevents bloat.

Recommended Schedule

Daily Log to daily file

Capture work, decisions, notes in memory/YYYY-MM-DD.md

Weekly Review & distill

Check past week's logs, update MEMORY.md with key insights

Monthly Prune & archive

Remove outdated info, archive old project files

Automate with Heartbeats

Use heartbeat polls to trigger memory maintenance:

# HEARTBEAT.md

## Memory Maintenance (every few days)
- [ ] Review last 3 days of memory/YYYY-MM-DD.md
- [ ] Update MEMORY.md with significant learnings
- [ ] Remove outdated entries from MEMORY.md

🔐 Memory Security

Memory files can contain sensitive context. OpenClaw has built-in protections.

Main Session Only

MEMORY.md is only loaded in main sessions (direct chat with you). Group chats and shared contexts don't get access to your personal memory.

No Exfiltration

Agents are instructed never to share private data. Group chat behavior is restricted — the agent participates but doesn't volunteer your context.

Scoped Memory Files

Create separate memory files for different contexts. Client-specific files stay with client work; personal notes stay in main memory.

⚠️ Don't store secrets in memory files: API keys, passwords, and tokens should go in secure config or environment variables, not MEMORY.md. Memory files are text — they can be read.

✨ Best Practices

📝

Write It Down

"Mental notes" don't survive session restarts. If you want the agent to remember something, it must be in a file.

🎯

Be Specific

"User prefers 9am AEST updates" is better than "User likes mornings." Specific memories are searchable memories.

📅

Date Everything

Context changes. Dating your entries lets you trace when decisions were made and why.

🧹

Prune Regularly

Old, irrelevant memories add noise. Remove outdated info to keep recall accurate.

🏷️

Use Headers

Good headers make semantic search more effective. "Client: Acme Co - SEO Audit" beats "Notes."

🔗

Link to Files

Reference file paths, folder IDs, and URLs in memory. Context includes where to find things.

🚀 Start Building Memory

The best time to start was yesterday. The second best time is now. Create your first MEMORY.md and watch your agent get smarter.

Workspace Files Automate with Cron