Initial backup 2026-02-17

2026-02-17 15:50:53 +00:00
commit 8902a93add
941 changed files with 131420 additions and 0 deletions
--- a/skills/workspace-review/references/checklist.md
+++ b/skills/workspace-review/references/checklist.md
@@ -0,0 +1,82 @@
+# Workspace Review Checklist
+
+Quick-reference for periodic audits.
+
+## Structure (Required Files)
+
+- [ ] `AGENTS.md` exists
+- [ ] `SOUL.md` exists
+- [ ] `USER.md` exists
+- [ ] `IDENTITY.md` exists
+- [ ] `TOOLS.md` exists
+- [ ] `memory/` directory exists
+
+## Structure (Optional Files)
+
+- [ ] `HEARTBEAT.md` — if using heartbeats
+- [ ] `MEMORY.md` — if maintaining long-term memory
+- [ ] `BOOT.md` — if using boot-md hook (runs every gateway restart)
+- [ ] `BOOTSTRAP.md` — one-time first run (delete after)
+- [ ] `skills/` — if using workspace skills
+
+## File Purpose (No Scope Creep)
+
+- [ ] AGENTS.md: Only operating instructions, no memories
+- [ ] SOUL.md: Only persona/tone, no tasks or tech details
+- [ ] USER.md: Only user info, no agent memories
+- [ ] IDENTITY.md: Only identity facts, no philosophy
+- [ ] TOOLS.md: Only environment notes, no procedures
+- [ ] HEARTBEAT.md: Short checklist only, no full docs
+- [ ] MEMORY.md: Curated insights only, no raw logs
+
+## File Sizes
+
+- [ ] AGENTS.md < 1000 lines
+- [ ] SOUL.md < 200 lines
+- [ ] USER.md < 100 lines
+- [ ] IDENTITY.md < 50 lines
+- [ ] HEARTBEAT.md < 100 lines
+
+## Memory Hygiene
+
+- [ ] Daily files use `YYYY-MM-DD.md` naming
+- [ ] Reference docs in `memory/` use descriptive names (not dates)
+- [ ] No duplicate content between MEMORY.md and daily files
+- [ ] Recent daily files reviewed and distilled
+- [ ] No API keys or passwords in memory files
+
+## Automatic Features (Awareness)
+
+- [ ] **Pre-compaction flush:** OpenClaw auto-triggers memory save before compaction
+- [ ] **Heartbeat response:** `HEARTBEAT_OK` stripped when nothing needs attention
+- [ ] **Empty HEARTBEAT.md:** Skipped entirely to save API calls
+
+## Vector Search Alignment
+
+- [ ] Only `MEMORY.md` and `memory/**/*.md` are indexed by default
+- [ ] `memorySearch.extraPaths` adds other paths if needed
+- [ ] `memorySearch.experimental.sessionMemory` indexes session transcripts if enabled
+
+## Git Status
+
+**⚠️ Workspace is PRIVATE — never push to GitHub**
+
+- [ ] No public remote configured
+- [ ] Working tree clean (or intentionally dirty)
+- [ ] No untracked files that should be tracked
+- [ ] .gitignore excludes secrets
+- [ ] No secrets committed
+
+## No Rogue Files
+
+- [ ] No README.md duplicating AGENTS.md purpose
+- [ ] No NOTES.md or similar duplicates
+- [ ] No credentials stored in workspace
+- [ ] No files that belong in ~/.openclaw/
+
+## Skills (if present)
+
+- [ ] Each skill has SKILL.md
+- [ ] Each SKILL.md has name + description frontmatter
+- [ ] SKILL.md files are lean (< 500 lines)
+- [ ] No duplicate skills vs managed/bundled
--- a/skills/workspace-review/references/openclaw-conventions.md
+++ b/skills/workspace-review/references/openclaw-conventions.md
@@ -0,0 +1,218 @@
+# 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)
+```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`):
+```json5
+{
+  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:
+```json5
+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](/concepts/memory) 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