Memory Engine Skill

A cognitive control memory system inspired by David Badre's "On Task" — applying neuroscience principles of gating, hierarchical control, and working memory to agent memory management.

Quick Start

1. Copy Templates to Your Workspace

# Copy the templates directory
cp -r memory-engine/templates/* ~/.openclaw/workspace/memory/

# Rename template files
mv ~/.openclaw/workspace/memory/active-context.template.md ~/.openclaw/workspace/memory/active-context.md
mv ~/.openclaw/workspace/memory/MEMORY.template.md ~/.openclaw/workspace/MEMORY.md

2. Directory Structure

~/.openclaw/workspace/
├── MEMORY.md                    # Strategic: Long-term lessons (from template)
├── memory/
│   ├── ARCHITECTURE.md          # Framework documentation
│   ├── active-context.md        # Working memory (from template)
│   ├── decay-policies.md        # Content lifecycle rules
│   ├── state-detectors.md       # Automated update triggers
│   ├── YYYY-MM-DD.md           # Daily notes (create as needed)
│   ├── runbooks/
│   │   ├── README.md           # Runbook index
│   │   └── *.md                # Procedural runbooks
│   └── archive/                # Decayed content (auto-created)

3. Configure Your Agent

Add to your AGENTS.md or system prompt:

## Memory Protocol

Before acting on any task:
1. Read `memory/active-context.md` (working memory)
2. If task has a runbook, read it from `memory/runbooks/`
3. Check `TOOLS.md` for domain-specific config

At session end:
1. Update `active-context.md` with any state changes
2. Write significant events to today's daily note
3. If new procedure discovered, create a runbook

Core Architecture

MEMORY.md           ← Strategic: Identity, relationships, long-term lessons
  active-context.md ← Operational: Current projects, deadlines, commitments
    YYYY-MM-DD.md   ← Tactical: Daily events, raw notes, session logs

Information flows UP through consolidation (daily notes → active context → strategic memory). Information flows DOWN through decomposition (goals → tasks → actions).

Input Gating (What Enters Memory)

Not everything is worth storing. Classify before writing:

Output Gating (When Memory Influences Action)

Key insight: Always load working memory (active-context.md), but only load domain-specific files when that domain is active.

Gating Policies (Failure Prevention)

Learned rules that prevent repeated failures:

Working Memory (active-context.md)

The prefrontal cortex analog. Holds:

• •Active commitments and deadlines (next 7 days)
• •Running project states
• •Scheduled automation (cron job IDs)
• •Pending decisions
• •Session handoff notes

Rules:

• •Updated at END of every significant session
• •Read at START of every session
• •Pruned weekly (completed items removed, lessons promoted)

Runbooks (Procedural Memory)

Location: memory/runbooks/

Runbooks capture HOW to do things — exact commands, API endpoints, auth flows.

Rule: If a task requires multi-step tool use, it MUST have a runbook. When a task has a runbook, read it before executing.

This is critical for model switches — a new model knows conceptually how to do things but doesn't know YOUR specific setup.

Retrieval Protocol

1. •Start with active-context.md (working memory)
2. •If not there, check TOOLS.md (domain config)
3. •If still unclear, use memory_search
4. •If nothing found, check MEMORY.md (long-term)
5. •If truly unknown, ask the human

Never guess when memory is available to check.

Session Checklists

Session Start

□ Read active-context.md
□ Check today's date vs Last Updated
□ If stale (>24h), scan recent daily notes
□ Identify active projects and their state
□ Load relevant runbooks for current task

Session End

□ Update active-context.md with any changed state
□ Write significant events to today's daily note
□ If new procedure discovered, create runbook
□ If lesson learned, consider promoting to MEMORY.md

Automated Systems

Decay Policies

See templates/decay-policies.md:

• •Priority-based retention (P0 permanent → P3 session-only)
• •Temporal decay with usage-based extension
• •Archive system with searchable index
• •7-day grace period before archival

State Detectors

See templates/state-detectors.md:

• •P0 triggers: Immediate update on cron/config/model changes
• •P1 triggers: Session-end batch updates
• •P2 triggers: Periodic consolidation during heartbeats

Memory Maintenance Schedule

Template Files Included

Why This Matters

From Badre's "On Task": The brain doesn't just store information — it gates what enters memory, retrieves selectively based on context, and monitors for relevance.

This system applies those principles:

1. •Input gating prevents noise from cluttering memory
2. •Output gating ensures relevant context is loaded
3. •Hierarchical control maintains abstraction levels
4. •Working memory provides session continuity
5. •Gating policies prevent repeated failures
6. •Runbooks externalize procedural knowledge

The goal: Never lose operational context, even across model switches or session resets.