Introduction
# 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:
| File | Should Contain | Should NOT Contain | |------|----------------|-------------------| | AGENTS.md | Operating instructions, memory workflow, behavior rules | Personal memories, daily logs, tool configs | | SOUL.md | Persona, tone, boundaries, identity philosophy | Task lists, technical details, credentials | | USER.md | User profile, preferences, how to address them | Agent memories, system config | | IDENTITY.md | Name, emoji, vibe, external identities (wallets, handles) | Instructions, memories | | TOOLS.md | Environment-specific notes (camera names, SSH hosts, voices) | Skill instructions, operating procedures | | HEARTBEAT.md | Short checklist for periodic checks | Long procedures, full documentation | | MEMORY.md | Curated lessons, key context, important people/projects | Daily logs, raw notes | | memory/*.md | Daily logs, raw notes, session summaries | Long-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.**
```bash 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:
```bash 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)
```bash 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](references/openclaw-conventions.md) — Full workspace file specifications - [references/checklist.md](references/checklist.md) — Quick-reference checklist