OpenClaw ~/clawd/ Directory: Memory Filesystem Structure

Introduction

OpenClaw rejects traditional databases in favor of a file-based approach. Every interaction and preference is stored as plain Markdown or YAML within ~/clawd/. Human-readable, searchable with grep, version-controllable with Git. The memory architecture is divided into specialized files, each with a clear purpose. Understanding the ~/clawd/ structure is essential for configuring your agent, debugging issues, and extending OpenClaw with custom workflows.

The "clawd" name is a nod to the project's history — the original assistant was called Clawd. The directory is the agent's "home" — where it stores everything it knows and everything it's configured to do. No black boxes. No proprietary formats. Just files you can open, edit, and inspect.

Structure

~/clawd/
├── SOUL.md
├── AGENTS.md
├── HEARTBEAT.md
├── TOOLS.md
├── SKILLS.md
├── CONTACTS/
├── memory/
└── config.yaml

This is the canonical structure. Your installation may have additional directories (e.g., PROJECTS/, GOALS/) depending on Skills and configuration. The core files — SOUL, AGENTS, HEARTBEAT, TOOLS, SKILLS — are always present in a standard setup.

File-by-File Breakdown

SOUL.md — The agent's identity. Personality, core values, and long-term instructions. Loaded at the start of every reasoning cycle. Defines who the agent is. See SOUL.md.

AGENTS.md — Workspace configurations and role definitions. Multi-agent setups use this to define boundaries. "When in work context, use formal tone." See AGENTS.md.

HEARTBEAT.md — The proactive task list. The agent reads this on each Heartbeat cycle and works through the items. Morning briefings, server checks, digest generation — all defined here. See HEARTBEAT.md.

TOOLS.md / SKILLS.md — Tool and Skill definitions. What the agent can do. TOOLS.md describes available tools; SKILLS.md maps to ClawHub packages. The runtime uses these to build the tool list for the LLM. See TOOLS.md and SKILLS.md.

CONTACTS/ — Optional. Used by Personal CRM and similar workflows. One Markdown file per contact. Extracted from email, calendar, and manual input.

memory/ — Dynamic context. Conversation summaries, learned facts, project notes. The agent reads and writes here during interactions. Can grow large; consider periodic pruning.

config.yaml — Sometimes stored here, sometimes in ~/.openclaw/. Main configuration: LLM providers, channels, Gateway settings. Secrets should be in environment variables, not in config.

Benefits of the File-Based Approach

Human-readable: Open any file in a text editor. No database tools, no SQL. You can see exactly what the agent knows.

Grep-able: grep -r "project deadline" ~/clawd/ — search across all memory. Find where a fact is stored. Debug context issues.

Git-versionable: git init in ~/clawd/, commit regularly. Roll back bad edits. Track how your agent's configuration evolved. Collaborate by sharing a repo (without secrets).

No proprietary DB: No MongoDB, no PostgreSQL, no vector store required for basic operation. OpenClaw works with just a filesystem. Simplifies deployment, backup, and migration.

Full transparency: Auditors can read the files. Compliance teams can verify what the agent stores. There's no hidden state.

Customization and Extensions

You can add your own files and directories. Many users add PROJECTS/, GOALS/, or COMPETITORS.md. Skills can create and populate custom files. The agent runtime is configured to read from specific paths — check the docs for how to register new memory sources.

Convention: use Markdown for human-authored content, YAML for structured data. Keep file names lowercase with hyphens. Avoid special characters. The agent's retrieval logic may use file names for relevance — descriptive names help.

Backup and Version Control

Back up ~/clawd/ regularly. It's your agent's entire state. Options: rsync to another machine, cloud sync (Dropbox, iCloud — be careful with conflict resolution), or S3/backup service. Exclude config.yaml if it contains secrets; back up .env separately with encryption.

Git: cd ~/clawd && git init && git add . && git commit -m "Initial memory". Add a .gitignore for logs, temp files, and any sensitive data. Commit after significant changes. Tag releases if you want to roll back to a known good state.

Wrapping Up

~/clawd/ is the heart of OpenClaw's local-first architecture. Every file has a purpose. Every byte is yours to read, edit, and own. See memory system for the full architecture and SOUL.md for identity configuration.