Workspace Review

Workspace Review

A self-audit process to verify workspace files follow OpenClaw conventions and haven't drifted into non-standard patterns.

When to Run

Periodically (weekly or after major changes) When asked to "review", "audit", or "check" workspace After bootstrap or significant reorganization During heartbeat maintenance cycles

1. Structure Check

Verify expected files exist in correct locations: ~/.openclaw/workspace/ ├── AGENTS.md ← Operating instructions (REQUIRED) ├── SOUL.md ← Persona/tone (REQUIRED) ├── USER.md ← User profile (REQUIRED) ├── IDENTITY.md ← Agent name/vibe/emoji (REQUIRED) ├── TOOLS.md ← Local tool notes (REQUIRED) ├── HEARTBEAT.md ← Heartbeat checklist (optional) ├── MEMORY.md ← Curated long-term memory (optional) ├── BOOT.md ← Runs on gateway restart (optional, boot-md hook) ├── BOOTSTRAP.md ← One-time first-run ritual (delete after use) ├── memory/ ← Daily logs + reference docs (vector-indexed) │ └── YYYY-MM-DD.md └── skills/ ← Workspace-specific skills (optional) Note on BOOT.md vs BOOTSTRAP.md: BOOT.md — Persistent; runs every gateway restart (if boot-md hook enabled) BOOTSTRAP.md — One-time; agent follows it on first run, then deletes it Check: Run ls -la on workspace root. Flag missing required files.

2. File Purpose Audit

Each file has ONE job. Check for scope creep: FileShould ContainShould NOT ContainAGENTS.mdOperating instructions, memory workflow, behavior rulesPersonal memories, daily logs, tool configsSOUL.mdPersona, tone, boundaries, identity philosophyTask lists, technical details, credentialsUSER.mdUser profile, preferences, how to address themAgent memories, system configIDENTITY.mdName, emoji, vibe, external identities (wallets, handles)Instructions, memoriesTOOLS.mdEnvironment-specific notes (camera names, SSH hosts, voices)Skill instructions, operating proceduresHEARTBEAT.mdShort checklist for periodic checksLong procedures, full documentationMEMORY.mdCurated lessons, key context, important people/projectsDaily logs, raw notesmemory/*.mdDaily logs, raw notes, session summariesLong-term curated memories Check: Skim each file. Flag content in wrong location.

3. Memory Hygiene

Daily files use YYYY-MM-DD.md or YYYY-MM-DD-slug.md format Hook-generated session files (session-memory hook creates YYYY-MM-DD-slug.md) reviewed periodically Reference docs use descriptive names (not dates): project-notes.md, api-guide.md MEMORY.md contains curated insights, not raw logs No duplicate information across MEMORY.md and daily files Old daily files reviewed and distilled to MEMORY.md periodically No sensitive data (API keys, passwords) in memory files Automatic Memory Flush: OpenClaw triggers a silent agent turn before session compaction to write durable memories. The agent receives a prompt to flush important context to memory/YYYY-MM-DD.md. This is automatic — no action needed, but be aware your context WILL be compacted after ~180k tokens.

4. Vector Search Alignment

Only MEMORY.md and memory/**/*.md are indexed by default Daily logs use YYYY-MM-DD.md; reference docs use descriptive names Files outside memory/ can be indexed via memorySearch.extraPaths in config Session Memory (Experimental): If memorySearch.experimental.sessionMemory = true, session transcripts are also indexed and searchable via memory_search.

5. Git Status

⚠️ This workspace is PRIVATE. Never push to GitHub or any public remote. cd ~/.openclaw/workspace && git status No remote configured (or only private backup) No untracked files that should be tracked No tracked files that should be gitignored No uncommitted changes lingering for days .gitignore excludes secrets (*.key, .pem, .env, secrets)

6. Rogue Files Check

Look for files that don't fit the standard layout: ls -la ~/.openclaw/workspace/ Flag anything that: Duplicates bootstrap file purposes (e.g., README.md alongside AGENTS.md) Stores credentials in workspace (should be in ~/.openclaw/credentials/) Creates non-standard directories without clear purpose Note: Only MEMORY.md and memory/**/*.md are vector-indexed. Files outside memory/ can be added via memorySearch.extraPaths in config.

7. Size Check

Bootstrap files should be lean (loaded every session): AGENTS.md: < 500 lines ideal, < 1000 max SOUL.md: < 200 lines ideal USER.md: < 100 lines ideal IDENTITY.md: < 50 lines ideal HEARTBEAT.md: < 100 lines (token burn concern) wc -l AGENTS.md SOUL.md USER.md IDENTITY.md HEARTBEAT.md TOOLS.md MEMORY.md 2>/dev/null

8. Skills Check

If skills/ exists: Each skill has SKILL.md with valid frontmatter (name, description) No duplicate skills (workspace vs managed) Skills follow progressive disclosure (lean SKILL.md, references for details)

Output Format

• After review, report:
• ## Workspace Review — YYYY-MM-DD
• ### ✅ Passing
• [list what's correct]
• ### ⚠️ Warnings
• [list minor issues]
• ### ❌ Issues
• [list things that need fixing]
• ### 📋 Recommendations
• [specific actions to take]

References

references/openclaw-conventions.md — Full workspace file specifications references/checklist.md — Quick-reference checklist