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

Review Process

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:

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