openclaw-backups/skills/workspace-review/references/openclaw-conventions.md

OpenClaw Workspace Conventions

Source: OpenClaw docs (/docs/concepts/agent-workspace.md, /docs/concepts/memory.md)

Workspace Location

• Default: ~/.openclaw/workspace
• Override via agents.defaults.workspace in ~/.openclaw/openclaw.json
• Profile-specific: ~/.openclaw/workspace-<profile> when OPENCLAW_PROFILE is set

Important: Only ONE active workspace. Multiple workspaces cause auth/state drift.

What Lives WHERE

In Workspace (~/.openclaw/workspace/)

File	Purpose	Loaded
AGENTS.md	Operating instructions, memory workflow, behavior rules	Every session
SOUL.md	Persona, tone, boundaries	Every session
USER.md	User profile, preferences	Every session
IDENTITY.md	Agent name, vibe, emoji, external handles	Every session
TOOLS.md	Environment-specific tool notes	Every session
HEARTBEAT.md	Short checklist for heartbeat runs	On heartbeat
BOOT.md	Startup checklist on gateway restart	On boot
BOOTSTRAP.md	One-time first-run ritual	Once, then delete
MEMORY.md	Curated long-term memory	Main session only
memory/YYYY-MM-DD.md	Daily logs	Read today + yesterday
memory/*.md	Reference docs (deep dives, projects)	On demand
skills/	Workspace-specific skills	On demand
canvas/	Canvas UI files	On demand

Note: Only MEMORY.md and memory/**/*.md are vector-indexed.

NOT in Workspace (lives in ~/.openclaw/)

• openclaw.json — Config
• credentials/ — OAuth tokens, API keys
• agents/<agentId>/sessions/ — Session transcripts
• skills/ — Managed/installed skills
• memory/<agentId>.sqlite — Vector index (SQLite with embeddings)

Never commit these to git.

File Specifications

AGENTS.md

• Purpose: Operating instructions for the agent
• Contains: Rules, priorities, "how to behave", memory workflow instructions
• Size: < 500 lines ideal, < 1000 max
• Anti-patterns:
  • Personal memories (use MEMORY.md or daily files)
  • Skill-specific procedures (use skills/)
  • Environment config (use TOOLS.md)

SOUL.md

• Purpose: Persona definition
• Contains: Identity philosophy, tone guidelines, boundaries, emotional character
• Size: < 200 lines ideal
• Anti-patterns:
  • Task lists
  • Technical instructions
  • Memories about what happened

USER.md

• Purpose: User profile
• Contains: Name, pronouns, timezone, preferences, how to address them
• Size: < 100 lines ideal
• Anti-patterns:
  • Agent memories
  • System configuration
  • Relationship history (that goes in MEMORY.md)

IDENTITY.md

• Purpose: Agent's external identity
• Contains: Name, nickname, emoji, avatar, external handles (GitHub, Twitter, wallets)
• Size: < 50 lines ideal
• Anti-patterns:
  • Philosophy about identity (that's SOUL.md)
  • Instructions

TOOLS.md

• Purpose: Environment-specific notes
• Contains: Camera names, SSH hosts, voice preferences, device nicknames
• Size: Variable
• Anti-patterns:
  • Skill instructions (use skills/)
  • Operating procedures (use AGENTS.md)

HEARTBEAT.md

• Purpose: Checklist for periodic heartbeat runs
• Contains: Short, actionable items to check
• Size: < 100 lines (token burn concern)
• Anti-patterns:
  • Full procedures (just reference them)
  • Documentation

Heartbeat Response Contract:

• Reply HEARTBEAT_OK when nothing needs attention
• HEARTBEAT_OK at start/end of reply is stripped; if remaining content ≤ 300 chars, reply is dropped
• For alerts, do NOT include HEARTBEAT_OK — just return the alert text
• If HEARTBEAT.md is empty (only headers/blank lines), heartbeat is skipped to save API calls

MEMORY.md

• Purpose: Curated long-term memory
• Contains: Distilled lessons, key people, important projects, lasting context
• Loaded: Main/private session ONLY (never in group chats)
• Anti-patterns:
  • Raw daily logs (use memory/*.md)
  • Duplicate of daily file content
  • Sensitive credentials

memory/YYYY-MM-DD.md

• Purpose: Daily log
• Contains: What happened today, raw notes, session summaries
• Naming: Strict YYYY-MM-DD.md format
• Workflow: Read today + yesterday on session start
• Anti-patterns:
  • Curated insights without also putting in MEMORY.md
  • Very old files never reviewed

memory/*.md (reference docs)

• Purpose: Searchable reference material
• Contains: Deep dives, project docs, technical references
• Why here: memory/ is vector-indexed for semantic search. Files elsewhere are NOT searchable.
• Examples: api-integration-notes.md, project-alpha.md
• Note: Daily logs use YYYY-MM-DD.md naming; reference docs use descriptive names

Git Conventions

⚠️ IMPORTANT: This workspace is PRIVATE. Never push to GitHub or any public remote.

The workspace contains personal memory, identity, and potentially sensitive context. Git is for LOCAL version control and backup only.

Do Track (locally)

• All bootstrap files (AGENTS.md, SOUL.md, etc.)
• memory/*.md
• skills/

Do NOT Track (gitignore)

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

Never Do

• Push to GitHub or any public repository
• Commit API keys, OAuth tokens, passwords
• Commit anything from ~/.openclaw/
• Share raw chat dumps with sensitive content

Memory Workflow

1. During sessions: Write notable things to memory/YYYY-MM-DD.md
2. Periodically: Review daily files, distill insights to MEMORY.md
3. On session start: Read today + yesterday's daily files
4. In main session: Also read MEMORY.md
5. In group chats: Do NOT read MEMORY.md (security)

Automatic Memory Flush (Pre-Compaction)

OpenClaw automatically triggers a silent agent turn before context compaction:

• Fires when session approaches ~180k tokens (configurable via compaction.reserveTokensFloor + softThresholdTokens)
• Agent receives system prompt: "Session nearing compaction. Store durable memories now."
• Agent should write lasting notes to memory/YYYY-MM-DD.md, then reply NO_REPLY
• One flush per compaction cycle (tracked in sessions.json)

Config (agents.defaults.compaction.memoryFlush):

{
  enabled: true,
  softThresholdTokens: 4000,
  systemPrompt: "Session nearing compaction. Store durable memories now.",
  prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
}

Vector Search

Only MEMORY.md and memory/**/*.md are indexed by default.

Extra paths: To index files outside memory/, add them to config:

agents: {
  defaults: {
    memorySearch: {
      extraPaths: ["../team-docs", "/srv/shared-notes"]
    }
  }
}

Session memory (experimental): Enable memorySearch.experimental.sessionMemory = true to also index session transcripts. This allows memory_search to recall conversations.

See Memory docs for full details on vector search, hybrid search, and session memory.

Skill Conventions

• Workspace skills in <workspace>/skills/ override managed skills
• Each skill needs SKILL.md with frontmatter (name, description)
• Keep SKILL.md lean (< 500 lines)
• Use references/ for detailed docs
• Use scripts/ for executable code
• Use assets/ for templates/files used in output

Common Anti-Patterns

1. Scope creep — File grows beyond its purpose
2. Duplication — Same info in multiple files
3. Wrong location — Memories in SOUL.md, instructions in IDENTITY.md
4. Bloat — Bootstrap files too large (loaded every session)
5. Rogue files — README.md, NOTES.md that duplicate bootstrap purposes
6. Secrets in workspace — API keys should be in ~/.openclaw/credentials/
7. Stale daily files — Never reviewed, insights never curated