Agent project memory

[sturdy temple]

I am working with an agent on a long running project, and have its heartbeat running via cron task. I need some help dealing with memory. For example the agent has made a template for sending an email, but never remember to use it. Similarly it stores specific sources to check, but doesn't seem to ever read its notes. I have qmd setup. My guess is it is not storing these notes in correct place, and maybe agent files need to be edited to better address notes and memory. Thoughts?

[blissful fox]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[ivory prairie]

I checked the docs a bit so I don’t have to guess here. Looking at the memory/QMD docs now.

Yeah, I think your guess is mostly right. This usually ends up being a “wrong thing in the wrong file” problem more than QMD being broken.

Short version:

• AGENTS.md = behavior/rules, “always do X before Y”
• MEMORY.md = durable facts/templates/preferences you want available every turn
• memory/YYYY-MM-DD.md = daily/project notes, not guaranteed to be seen unless recalled
• HEARTBEAT.md = tiny background checklist for cron/heartbeat runs
• QMD = search/index layer, not “auto-read everything all the time”

A few important gotchas from the docs:

1. Heartbeat/background runs do not use Active Memory
   So if you expected auto-recall during cron heartbeats, that won’t happen.
   Docs: https://docs.openclaw.ai/concepts/active-memory

2. Daily memory/*.md files are not normally injected every turn

They’re usually only used through memory_search / memory_get.
Docs: https://docs.openclaw.ai/concepts/memory

3. Use MEMORY.md, not just memory.md
   Lowercase memory.md is legacy fallback. With QMD, the default indexed memory is MEMORY.md + memory/ tree.
   Docs: https://docs.openclaw.ai/concepts/memory-qmd

4. If heartbeat uses lightContext: true, it may only see HEARTBEAT.md
   That can make it look like the agent “forgot” everything else during cron runs.
   Docs: https://docs.openclaw.ai/gateway/heartbeat

What I’d recommend for your examples:

• Email template the agent should reliably use
  • Put the short canonical version in MEMORY.md
  • Also add an explicit rule in AGENTS.md like:
    “Before drafting project emails, consult the template in MEMORY.md (or templates/email.md).”

• Specific sources the agent should check on heartbeat
  • Put the checklist in HEARTBEAT.md
  • If the source list is long, keep a short heartbeat instruction like
    “Check sources listed in sources.md before reporting,” and make that a file the agent is told to read explicitly
  • If those files live outside the workspace, index them via memory.qmd.paths or agents.defaults.memorySearch.extraPaths

A good rule of thumb:

• Must always influence behavior → AGENTS.md
• Durable reusable knowledge → MEMORY.md
• Today’s working notes → memory/YYYY-MM-DD.md
• Periodic/background checklist → HEARTBEAT.md

If you want, paste these and I can tell you exactly what to change:

openclaw --version
openclaw memory status

And snippets of:

• AGENTS.md
• MEMORY.md
• HEARTBEAT.md
• your memory / agents.defaults.memorySearch config from openclaw.json

If memory_search can find the template but the agent still ignores it, that’s an instruction placement problem. If memory_search can’t find it, that’s an index/path problem.

[sturdy temple]

In general it seems that we shouldn't have to modify manually the memory files, nor update agents markdown file to tell it to use template. Is active memory made to address this? For example it I just tell agent you should always use email template it would know it should save this instruction as memory, and also read memory at start of sessions? Also how does dreaming memory feature work with this?

[ivory prairie]

Let me check the active-memory + dreaming docs so I don’t hand-wave this.

Yeah, in principle you shouldn’t need to hand-edit memory files for normal use.

But today I’d draw a pretty hard line between memory and policy:

• Memory = “things the agent should probably remember/reuse”
• AGENTS.md / HEARTBEAT.md = “things the agent must do reliably”

So for your example:

• “Peter prefers this email style” → good memory candidate
• “Always use this exact template before sending project emails” → better as explicit instruction/policy

A few concrete points:

Active Memory

Yes, this is the feature closest to what you want, but with limits.

What it does:

• runs a bounded memory-recall step before the main reply
• helps relevant stored memory surface automatically
• works best for interactive persistent chats

What it does not do:

• it does not run on heartbeat/background runs
• it does not run on one-shot/internal worker paths
• by default it is only enabled for direct chats, not group/channel sessions unless you opt those in

So Active Memory can help an agent naturally remember “use that email template” in a live chat, but it will not fix cron heartbeat forgetting by itself.

Docs: https://docs.openclaw.ai/concepts/active-memory

Dreaming

Dreaming is different.

It is a background consolidation system:

• collects short-term signals
• scores recurring/relevant items
• promotes strong candidates into MEMORY.md
• writes review output to DREAMS.md

That makes it good for:

• durable preferences
• recurring facts
• stable project context that keeps coming up

It is not a great fit for:

• exact operational rules
• “always do X every time”
• strict templates/checklists you need immediately

So I would not rely on dreaming for “always use this template on heartbeats.” It is more like slow memory consolidation than hard behavior control.

Docs: https://docs.openclaw.ai/concepts/dreaming

“Will it save this automatically and read it at session start?”

Sort of:

• OpenClaw does have automatic memory flush before compaction, so important things can get written without you hand-editing files
• MEMORY.md is injected as bootstrap context
• daily memory/*.md notes are not normally injected every turn
• if something only lands in daily notes, recall is less reliable unless memory search/active memory finds it

So if the agent saves “always use email template” into MEMORY.md, that’s much better than burying it in a daily note.

Docs: https://docs.openclaw.ai/concepts/memory

My honest recommendation

If you want this to be pleasantly automatic:

1. Enable Active Memory for the sessions where you actually chat with the agent
2. Enable Dreaming for long-term consolidation
3. Still keep hard rules in AGENTS.md or HEARTBEAT.md

That sounds less magical, but it’s the reliable setup:

• Active Memory improves recall
• Dreaming improves long-term consolidation
• AGENTS/HEARTBEAT handle exact must-follow behavior

Important gotcha for your setup

Since you mentioned heartbeat via cron:

• Active Memory will not run there
• so if heartbeat must always check certain sources or follow a template, that should live in HEARTBEAT.md or an explicitly referenced instruction file

Docs: https://docs.openclaw.ai/gateway/heartbeat

If you want, paste your:

• openclaw --version
• plugins.entries.active-memory
• plugins.entries.memory-core.config.dreaming
• heartbeat config

and I can tell you whether your current setup matches the behavior you want.

[sturdy temple]

So active memory doesn't run in cron session?

[ivory prairie]

Correct, it does not.

Active Memory only runs for interactive persistent chat sessions. It does not run for:

• cron / heartbeat / background runs
• headless one-shots
• internal helper/sub-agent paths

So for cron behavior, I’d treat it like this:

• must-follow checklist/template → HEARTBEAT.md or AGENTS.md
• durable recall / preferences → memory + QMD + optionally dreaming

Docs: https://docs.openclaw.ai/concepts/active-memory

That’s why your heartbeat agent can still feel forgetful even if memory search is set up fine.

[sturdy temple]

What instructions to add equivalent to active memory for cron?

[ivory prairie]

There isn’t a built-in “active memory for cron” toggle right now.

The closest equivalent is to make the heartbeat do an explicit recall step first.

I’d put something like this in HEARTBEAT.md:

# Heartbeat recall workflow

Before deciding what to do:

1. Recall relevant memory for the current project.
2. Search for templates, source lists, prior decisions, and blocked items.
3. Read the most relevant notes before acting.
4. If sending an email, use the saved email template.
5. If checking sources, read the saved source list first.

6. If new durable instructions are discovered, save them to long-term memory.
7. If nothing needs attention after recall + checks, reply HEARTBEAT_OK.

If you want it more concrete, even better:

tasks:

- name: project-check
  interval: 30m
  prompt: "Recall project memory, read the saved source list, check those sources, and use the email template for any outreach."

# Additional instructions

- Before acting, search memory for the current project.
- Read the top relevant notes, not just the snippet.
- Use `templates/email.md` for outbound emails.
- Use `sources.md` for recurring source checks.
- If a durable instruction changes, update long-term memory.
- If nothing needs attention, reply HEARTBEAT_OK.

A few practical tips:

• Keep HEARTBEAT.md small
• Put the big stuff in files like:
  • templates/email.md
  • sources.md
  • MEMORY.md
• Then use heartbeat instructions to tell the agent when to read them

Also, if you have heartbeat.lightContext: true, cron may only see HEARTBEAT.md, so in that mode you really want explicit “read this file first” instructions.

So the pattern is basically:

heartbeat prompt = “do memory recall now”
instead of
active memory = hidden automatic recall

Docs: https://docs.openclaw.ai/gateway/heartbeat
Memory docs: https://docs.openclaw.ai/concepts/memory

If you want, I can draft a good HEARTBEAT.md + AGENTS.md pair for this exact project pattern.

[sturdy temple]

Seems I could just put those instructions in agents.MD then to have this always happen?

[ivory prairie]

Yep, mostly yes.

If you want it to always happen, AGENTS.md is the right place for the general rule.

Good candidates for AGENTS.md:

• “Before sending project emails, read templates/email.md and use that template.”
• “Before recurring project work, recall prior notes and read sources.md.”
• “Save durable instructions to MEMORY.md, daily observations to memory/YYYY-MM-DD.md.”

But I’d still keep a split:

• AGENTS.md = global always-on behavior
• HEARTBEAT.md = cron/heartbeat-specific checklist

Important caveat:

• if heartbeat uses lightContext: true, then heartbeat runs may only see HEARTBEAT.md, not AGENTS.md

So:

• normal setup → yes, AGENTS is a good place for this
• heartbeat with lightContext → put the cron-critical bits in HEARTBEAT too

A nice pattern is:

AGENTS.md

• define the rule

HEARTBEAT.md

• remind the agent when to apply it during cron runs

So I’d say: yes, but don’t rely on AGENTS alone if your heartbeat is trimmed/light-context.

[sturdy temple]

Regarding DREAM.md , should I have this added to my AGENTS.md also, or is this added by openclaw as part of system intructions?

[ivory prairie]

I’m going to check that exact detail so I don’t misstate it.

Small correction: it’s DREAMS.md, not DREAM.md.

And no, it is not one of the default bootstrap files OpenClaw injects every turn.

Default injected files are things like:

• AGENTS.md
• SOUL.md
• TOOLS.md
• IDENTITY.md
• USER.md
• HEARTBEAT.md
• MEMORY.md

DREAMS.md is more of a review surface for the dreaming system, not a normal always-loaded instruction file.

So my recommendation is: