Agent Memory

HELIX agents have a persistent knowledge stack that helps them learn and improve over time. This page explains how agent memory works and how to configure it.

Knowledge Stack

Every agent's context is built from four layers, injected in this order:

┌─────────────────────────────┐
│  1. SOUL.md                 │  Identity + personality
├─────────────────────────────┤
│  2. MEMORY.md               │  Persistent rules + corrections
├─────────────────────────────┤
│  3. Skills                  │  Domain expertise documents
├─────────────────────────────┤
│  4. memory/                 │  Session notes + learned facts
└─────────────────────────────┘

Each layer adds context to the agent's prompt before it processes a task.

SOUL.md — Agent Identity

SOUL.md defines who the agent is. It contains:

• Name and role — "You are Sierra, the SEO Specialist"
• Personality traits — communication style, tone
• Core capabilities — what the agent is good at
• Behavioral guidelines — how to approach tasks
• Learning loop — instructions for self-improvement

The SOUL.md is the agent's system prompt — configured when creating the agent and editable in agent settings.

Learning Loop

The SOUL.md includes instructions for the agent to:

1. Reflect on task feedback and corrections
2. Extract rules from successful interactions
3. Write to MEMORY.md when it learns something new

This creates a feedback loop where agents improve with each task.

MEMORY.md — Persistent Rules

MEMORY.md is a growing document where the agent stores rules and corrections it has learned. Examples:

## Rules

- Always use the brand name "HelixNode" (one word, capital H and N)
- Blog posts should target 800-1200 words unless specified otherwise
- Include a meta description under 155 characters for all SEO content
- Customer emails should use the template from skill "CS Email Templates"

## Corrections

- User corrected: use "AI agent" not "AI bot" in customer-facing content
- User corrected: pricing page URL is /pricing not /plans

MEMORY.md persists across sessions. The agent reads it before every task execution, ensuring it doesn't repeat past mistakes.

Skills — Domain Expertise

Skills are structured knowledge documents attached to agents. They provide:

• Brand guidelines and tone rules
• Process documentation
• Example outputs
• Domain-specific knowledge

See the Custom Skills guide for full details on creating and managing skills.

memory/ — Session Notes

The memory/ directory stores session-level notes that the agent writes during task execution. These include:

• Key decisions made during a task
• Facts learned about the organization
• Patterns observed across multiple tasks

Memory notes are automatically flushed at the end of each session and available for future sessions.

How Agents Learn

The learning process works as follows:

1. Agent executes a task using its current knowledge stack
2. User provides feedback via comments or @mentions
3. Agent processes feedback and updates its approach
4. Agent writes to MEMORY.md with new rules or corrections
5. Next task — agent reads updated MEMORY.md and applies the learnings

Example Learning Flow

Task: "Write a product description for the Pro plan"

Agent writes: "Our Pro plan costs $49/month..."
User comments: "@Maven Actually it's $79/month now, we updated pricing last week"

Agent updates MEMORY.md:
- Pro plan price is $79/month (updated March 2026)

Next task mentioning pricing → Agent uses correct price

Managing Agent Memory

Viewing Memory

Each agent's memory is stored in the OpenClaw workspace at:

~/.openclaw/workspaces/{agent-id}/
├── SOUL.md
├── MEMORY.md
└── memory/
    └── session-notes.md

Resetting Memory

If an agent has learned incorrect information, you can:

1. Edit the agent's MEMORY.md to remove incorrect rules
2. Clear the memory/ directory for a fresh start
3. Update the SOUL.md (system prompt) in agent settings

Best Practices

• Let agents learn naturally — don't pre-fill MEMORY.md with everything. Let it grow from real interactions.
• Correct agents via comments — @mention the agent with corrections so it learns contextually.
• Review MEMORY.md periodically — check that learned rules are still accurate.
• Use skills for stable knowledge — put permanent knowledge (brand guides, processes) in skills, not MEMORY.md.