#OpenClaw Memory System

OpenClaw's memory design is delightfully plain yet powerful: everything is a plain-text file. Conversations, long-term memory, and skills are stored as readable Markdown / YAML — Git-backable and greppable.

#Philosophy: Text Is Memory

Unlike a "black-box database / vector store," OpenClaw makes memory inspectable text files, stored in the workspace and the ~/.openclaw directory:

Traditional memory            OpenClaw memory
──────────────────            ───────────────
Cloud / invisible      →      Local plain text, readable anytime
Hard to back up        →      git commit to version it
Can't edit directly    →      Edit with any text editor
Not searchable         →      grep / ripgrep in seconds

This "transparent memory" brings three benefits: auditable, backable, manually correctable.

#Storage Layout

~/.openclaw/
├── openclaw.json     # Main config
├── memory/           # Long-term memory (Markdown / YAML)
└── skills/           # Skills (SKILL.md)
<workspace>/
├── HEARTBEAT.md      # Checklist for the autonomy heartbeat
└── ...               # Conversation and project files

Adjust locations with environment variables:

#Managing Memory with Git

Because memory is plain text, Git is a natural backup and versioning tool:

cd ~/.openclaw
git init
git add .
git commit -m "snapshot: openclaw memory & skills"

Benefits:

• Rollback: restore accidentally deleted/edited memory in one step
• Sync: push to a private repo to share across machines
• Audit: git log / git diff show how memory evolved

Note: do not commit openclaw.json or any credentials to a public repo.

#Retrieval & Maintenance

Since it's text, retrieval and maintenance are direct:

• Search: grep -r "keyword" ~/.openclaw/memory
• Prune: edit/delete stale entries to keep signal high
• Correct: if the agent remembered something wrong, edit the file by hand

Compared to vector memory, plain-text memory is simple and transparent but weaker at large-scale semantic retrieval. If you need searchable vector memory, consider the sibling project Hermes Agent.

#Working with Autonomy (Heartbeat)

The workspace's HEARTBEAT.md is essentially a memory/checklist "note to your future self": when the heartbeat wakes the agent, it reads this to decide whether to act.

HEARTBEAT.md (checklist) → heartbeat wakes → read & decide → act / HEARTBEAT_OK

Write "things to remember and check periodically" into HEARTBEAT.md to close the loop of "has memory, acts proactively." See CLI & Automation.

#Practical Tips

• Set up a Git repo for ~/.openclaw immediately and commit regularly
• Explicitly write long-term preferences and context into memory files to avoid repeating yourself
• Periodically review memory; remove noise and stale info
• Manage credentials and private info separately — never in a public repo

#Next Steps

• Skills — memory + skills = smoother over time
• CLI & Automation — HEARTBEAT.md and autonomy
• Architecture & Features — where memory sits in the loop