Building Your Second Brain

In the last chapter, you fixed the three failure modes that make OpenClaw forget. Your agent now flushes memories before compaction, prunes context intelligently, and searches with hybrid vector + keyword matching.

That's the engine. This chapter teaches you how to drive it.

The Memory Folder

After a few days with flush enabled, your workspace will look something like this:

workspace/
└── memory/
    ├── MEMORY.md              ← Your curated long-term memory
    ├── 2026-02-17.md          ← Daily log (auto-flushed or manual)
    ├── 2026-02-18.md          ← Daily log
    ├── 2026-02-19.md          ← Daily log
    ├── health/
    │   └── 2026-02-19.md      ← Health check reports
    ├── weekly/
    │   └── 2026-02-16.md      ← Weekly cleanup summary
    └── archive/
        └── 2026-02-10.md      ← Archived old logs

MEMORY.md is the main file. This is your curated, long-term memory — the stuff your agent should always know. Your agent loads this into context regularly. Keep it concise: your most important preferences, project details, and standing instructions. Think of it as a cheat sheet about you.

YYYY-MM-DD.md files are daily logs. With memory flush enabled (Chapter 7), these get created automatically when compaction runs. But you should still write to them manually for important things — the auto-flush captures the broad strokes, your manual notes are sharper.

Subfolders organize reports by type. Health checks in health/, weekly summaries in weekly/, archived old logs in archive/. These are the same directories your workflows from Chapter 6 are writing to.

Everything is plain Markdown. No databases, no proprietary formats. Open these in any text editor, back them up anywhere. Future-proof by design.

Sessions vs. Memory

OpenClaw has two separate systems for remembering, and understanding the difference is key:

| Feature | Sessions | Memory | |---------|----------|--------| | Location | ~/.openclaw/agents/main/sessions/ | ~/clawd/memory/ | | Format | JSONL (machine-readable) | Markdown (human-readable) | | Lifespan | Temporary (compacted over time) | Permanent (until you delete it) | | Purpose | Immediate conversation context | Long-term knowledge | | Searchable | Within current conversation | Across all time |

Sessions are like a conversation — temporary, flowing, immediate. They're the raw chat logs between you and your agent. You don't curate them. When the context window fills up, they get compacted (and now, thanks to Chapter 7, the important bits get flushed to memory first).

Memory is like a journal — permanent, structured, intentional. You curate it, and your agent helps via flush. It persists across sessions, across restarts, across months.

You need both. Sessions give your agent short-term context. Memory gives it long-term knowledge. The three fixes from Chapter 7 make sure important information flows from sessions to memory before compaction destroys it.

Writing to Memory

Automatic flush is a safety net, not a replacement for intentional note-taking. The flush captures what the model thinks is important. But you know better than the model what matters to you.

The Easy Way: Tell Your Agent

Just message it what to save:

Add to today's memory: We decided to use Claude as the primary model and keep DeepSeek as the budget fallback.

Or at the end of a productive session:

Write today's daily log. Summarize what we did, what we decided, and what's next.

Your agent creates or updates the daily log file with a structured summary.

The Thorough Way: Give It a Template

For a more complete daily log, paste this prompt at the end of your day:

Write today's daily log to memory/YYYY-MM-DD.md using this
structure:

# [Today's date] — [Day of week]

## What happened
- [List of things we did today]

## Decisions
- [Any decisions made and why]

## Learned
- [Anything new or surprising]

## What's next
- [What we should work on tomorrow]

Fill each section based on our conversation today. If a
section has nothing, leave it out.

What to Save vs. What to Skip

Save: Decisions and the reasoning behind them. Things you learned (especially mistakes). Configuration choices you'll forget. Important context about your projects. Preferences your agent should know about you.

Skip: Routine back-and-forth ("what time is it?"). Temporary debugging steps. Information that already lives in your config files. Anything you wouldn't care about rereading in a month.

Reading from Memory

Now that your agent actually saves and searches reliably, retrieving information is straightforward. Just ask:

What did we decide about the AI model budget?

What has Argus reported in the last 3 days?

What happened on Tuesday?

What configuration changes did we make this week?

With hybrid search enabled, your agent searches memory files on disk instead of guessing from conversation context. It matches both exact terms ("Argus," "budget," "baseline.sha256") and semantic meaning ("what security issues did we have?" finds reports about permission problems even though the words don't match).

When your agent pulls information from memory, look for source citations — references like Source: memory/2026-02-18.md tell you exactly where the information came from.

Useful Search Patterns

By topic: "What do my memory files say about security?"

By date: "What happened on Tuesday?" or "Summarize this week's daily logs."

By decision: "What configuration changes did we make this week?"

By agent: "What has Argus reported in the last 3 days?"

By lesson: "What mistakes did we make setting up memory?"

The more structured your daily logs are (clear headings, consistent sections), the better these searches work.

The Full Loop

Here's how everything you've built in the last three chapters connects:

1. Workflows generate data (Chapter 6) — Argus writes security reports, the morning briefing creates summaries, the health check logs system status
2. Memory stores it (Chapter 7) — Flush saves session knowledge before compaction, hybrid search makes it findable
3. You use it (this chapter) — Daily logs, structured notes, quick searches, source citations

A concrete example:

• Tuesday 2 AM: Argus runs its heartbeat, finds a world-readable config file, writes a report to memory/2026-02-18.md
• Tuesday 8 AM: Your morning briefing summarizes: "Argus flagged a permission issue overnight"
• Tuesday 8:05 AM: You message your agent: "What security issues did Argus find?"
• Your agent searches memory, finds the report, and replies with details and a source citation

You didn't dig through files. You didn't remember paths. You didn't even have to be awake when the problem was found. The system caught it, stored it, and surfaced it when you asked.

That's the second brain.

Best Practices

Write daily. Even two sentences. "Set up memory flush, Argus ran clean." Future you will be grateful.

Use clear headings. Both you and your agent scan by headings first. ## Decisions is easier to find than a decision buried in a wall of text.

Keep MEMORY.md curated. This file gets loaded into context frequently. Don't let it grow into a novel. Move detailed notes to daily logs and keep MEMORY.md as a high-level summary of what matters most.

Review weekly. Skim the week's daily logs every Sunday. What did you learn? What patterns do you see? Add a ## Reflections section to your weekly summary.

Back up your memory folder. Your memory files are the most valuable thing in your workspace. We'll cover backup strategies in a later chapter, but for now, make sure your workspace directory gets backed up.

What's Next

Chapter 7: You fixed memory. Your agent now saves, prunes, and searches reliably.

Chapter 8: You learned how to use it — where files live, how to write and search, the daily habits that make it stick.

Chapter 9: Want even better search? Meet QMD — BM25 + vectors + reranking for your second brain. QMD is optional and advanced, but when your memory folder grows past what built-in search can handle, it's a game-changer.

And after QMD, Chapter 10 covers troubleshooting — because now that you have workflows running, memory growing, and agents patrolling, you need to know how to fix things when they break.