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

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