OpenClaw Convention Files: AI Assistants Beyond Code¶

The taxonomy post covered convention files for coding agents — AGENTS.md, SKILL.md, .prompt.md, and their relatives. Those files live in a project repo and guide agents during development work.

OpenClaw uses the same approach for a different problem: personal AI assistants that operate across messaging channels. An OpenClaw agent can reply to WhatsApp messages, monitor Discord servers, check email, control smart home devices, and run background tasks — all from a single gateway process on your own hardware.

The convention files that power this are different from the coding-agent ones, because the problems are different. A coding agent needs workflow steps and quality gates. A personal assistant needs identity, memory across sessions, and rules about when to speak in group chats.

The file types¶

OpenClaw convention files taxonomy

File	Purpose	When loaded
`AGENTS.md`	Behavioural baseline — safety, workflow, skills, session rules	Every session start
`SOUL.md`	Identity, tone, and boundaries — who the agent is	Every session start
`USER.md`	Owner context — who the agent is helping	Every session start
`MEMORY.md`	Long-term recall — curated facts, preferences, decisions	Main session only (not group chats)
`memory/YYYY-MM-DD.md`	Daily logs — raw notes from each session	Today + yesterday on startup
`TOOLS.md`	Environment specifics — device names, SSH hosts, voice preferences	When a skill needs it
`SKILL.md`	Per-skill instructions — one per tool/capability	When the skill is invoked
`HEARTBEAT.md`	Background task checklist — what to check during idle polls	On heartbeat poll
`BOOTSTRAP.md`	First-run identity setup — read once, then deleted	First session only

Three of these (AGENTS.md, SOUL.md, USER.md) load on every session start, before the agent responds to anything. The rest load on demand.

AGENTS.md — the behavioural baseline¶

OpenClaw's AGENTS.md shares the name with the coding-agent standard but serves a broader role. It covers:

Safety defaults — no directory dumps, no destructive commands without asking, no partial replies to messaging surfaces
Session startup — read SOUL.md, USER.md, and recent memory files before responding
Shared spaces — rules for group chat behaviour, including when to stay quiet
Memory system — how daily logs and long-term memory work together
Tools & skills — where skill instructions live and how to use TOOLS.md

A stripped-down version:

# AGENTS.md

## Safety defaults
Don't dump directories or secrets into chat.
Don't run destructive commands unless explicitly asked.

## Session start (required)
Read SOUL.md, USER.md, and today+yesterday in memory/.
Do it before responding.

## Memory
Daily notes: memory/YYYY-MM-DD.md
Long-term: MEMORY.md — curated memories, loaded in main session only.
Capture decisions, preferences, constraints, open loops.

## Tools & skills
Tools live in skills; follow each skill's SKILL.md when you need it.
Keep environment-specific notes in TOOLS.md.

The key difference from a coding-agent AGENTS.md: OpenClaw's version must handle multi-channel behaviour. A coding agent works in one editor session. An OpenClaw agent might be in a private WhatsApp chat, a Discord server, and monitoring email — simultaneously.

SOUL.md — identity and personality¶

This is the file that does not exist in the coding-agent world. SOUL.md defines who the agent is — not what it does, but how it thinks and communicates.

From OpenClaw's template:

# SOUL.md

## Core Truths
Be genuinely helpful, not performatively helpful.
Skip the "Great question!" and "I'd be happy to help!" — just help.

Have opinions. You're allowed to disagree, prefer things,
find stuff amusing or boring.

Be resourceful before asking. Try to figure it out.
Read the file. Check the context. Search for it.
Then ask if you're stuck.

## Boundaries
Private things stay private. Period.
When in doubt, ask before acting externally.
You're not the user's voice — be careful in group chats.

## Vibe
Be the assistant you'd actually want to talk to.
Concise when needed, thorough when it matters.
Not a corporate drone. Not a sycophant. Just… good.

A couple of things worth noting:

The "have opinions" line. Most coding-agent instructions deliberately suppress personality — you want a consistent, neutral tool. OpenClaw takes the opposite approach. A personal assistant that sounds like a press release is worse than useless when you are messaging it at 11pm asking about dinner plans.

The file belongs to the agent. SOUL.md can be updated by the agent itself, not just the owner. If the agent's personality evolves over time, it records that. The instruction is: "If you change this file, tell the user."

MEMORY.md and daily logs — session continuity¶

Every AI agent has the same fundamental problem: it wakes up fresh each session with no memory of what happened before. Coding agents solve this with project files and git history — the code is the memory. Personal assistants need something else.

OpenClaw splits memory into two tiers:

Daily logs (memory/YYYY-MM-DD.md) — raw notes from each session. Decisions made, things discussed, tasks completed. The agent creates these automatically and reads today plus yesterday on startup.

Long-term memory (MEMORY.md) — curated facts that matter across days and weeks. Preferences, recurring patterns, important context. The agent periodically reviews daily logs and distills them into MEMORY.md, like a human reviewing their journal.

The security boundary matters: MEMORY.md only loads in the main session (direct chat with the owner). In group chats or shared channels, it stays unread. Personal context should not leak to strangers.

# MEMORY.md — Long-term Memory

ONLY load in main session (direct chats with your human).
DO NOT load in shared contexts (Discord, group chats).
Contains personal context that shouldn't leak.

Write significant events, thoughts, decisions, opinions, lessons.
This is curated memory — the distilled essence, not raw logs.

One strong opinion from OpenClaw's docs: no mental notes. If the agent wants to remember something, it writes it to a file. "Mental notes don't survive session restarts. Files do." That applies equally well to coding agents.

TOOLS.md — environment-specific notes¶

Skills are shared and reusable. Your specific setup is not. TOOLS.md keeps them separate.

# TOOLS.md

### Cameras
- living-room → Main area, 180° wide angle
- front-door → Entrance, motion-triggered

### SSH
- home-server → 192.168.1.100, user: admin

### TTS
- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod

This separation is practical. You can update or share skills without leaking your infrastructure details. And your device names and SSH aliases do not clutter skill definitions that are meant to be generic.

HEARTBEAT.md — proactive behaviour¶

Coding agents are reactive — they wait for you to ask something. OpenClaw agents can be proactive.

The gateway sends periodic heartbeat polls to the agent. When a heartbeat arrives, the agent reads HEARTBEAT.md and decides what to do:

# HEARTBEAT.md

Check:
- Emails: urgent unread messages?
- Calendar: events in next 24h?
- Mentions: Twitter/social notifications?
- Weather: relevant if human might go out?

The agent rotates through these checks 2-4 times per day, tracks what it last checked in memory/heartbeat-state.json, and only reaches out when something warrants it. Late night (23:00-08:00) stays quiet unless something is urgent.

OpenClaw also distinguishes heartbeats from cron jobs:

Mechanism	When to use
Heartbeat	Batch multiple checks together, timing can drift, needs conversational context
Cron	Exact timing required, isolated from main session, one-shot reminders

Group chat behaviour¶

This is where OpenClaw's convention files diverge most from coding agents. A coding agent talks to one person in an editor. An OpenClaw agent might be in a Discord server with dozens of people.

OpenClaw's AGENTS.md has explicit rules:

Respond when:

Directly mentioned or asked a question
You can add genuine value
Something witty fits naturally
Correcting important misinformation

Stay silent when:

Casual banter between humans
Someone already answered the question
Your response would just be "yeah" or "nice"
The conversation flows fine without you

The guiding principle: "Humans in group chats don't respond to every single message. Neither should you. Quality over quantity."

There is also guidance on reactions (emoji reactions are lightweight social signals — use them like a human would) and a "triple-tap" warning: don't respond multiple times to the same message with different reactions.

How it compares to coding-agent files¶

Concern	Coding agents	OpenClaw
Identity	Not needed — agent is a tool	`SOUL.md` — agent has personality
Memory	Git history, project files	`MEMORY.md` + daily logs
Scope	One repo, one session	Multiple channels, always-on
Proactivity	Reactive only	Heartbeats and cron
Multi-user	Single developer	Group chats with strangers
Privacy	Project-level (`.gitignore`)	Session-level (main vs group)
Environment	Editor context	`TOOLS.md` (devices, SSH, voices)
Bootstrapping	Not needed	`BOOTSTRAP.md` (first-run)

The shared concept is the same: markdown files that define agent behaviour, loaded at predictable times, with clear ownership. The differences come from what the agent is doing — editing code vs living in your pocket.

What coding agents can learn¶

A few of OpenClaw's ideas port well to development workflows:

Memory as files, not context. The "no mental notes" rule matters for long coding sessions too. If an agent discovers something about your codebase, it should write it down — in a memory file, a comment, a doc — not hold it in context that disappears when the session ends.

Explicit safety defaults. OpenClaw's AGENTS.md starts with safety. Coding agents often rely on tool restrictions (.agent.md in VS Code) but rarely state behavioural safety rules as plainly as "Don't run destructive commands unless explicitly asked."

Heartbeat-style proactive checks. A CI/CD agent that periodically checks pipeline health, dependency vulnerabilities, or stale branches — without being asked — would be worth having.

Getting started with OpenClaw¶

Install: npm install -g openclaw@latest
Onboard: openclaw onboard --install-daemon
Create your workspace: mkdir -p ~/.openclaw/workspace
Copy the templates: AGENTS.md, SOUL.md, TOOLS.md
Connect a channel (Telegram is fastest)
Start chatting

The workspace is just a directory with markdown files. Back it up as a private git repo if you want version history on your agent's memory and personality.