OpenClaw Optimization Guide

Make your OpenClaw AI agent faster, smarter, cheaper, and actually safe to run in production.

July 2026 sweep. Stable baseline: OpenClaw 2026.6.11 (released 2026-06-30). This refresh covers the 2026.6.8–2026.6.11 trains — automatic fast mode, working failover, per-agent cost visibility, prompt-cache retention, cron fallback controls, and channel-delivery self-recovery — and corrects the previous revision, which referenced a "2026.6.4" release and several config keys that were never shipped. See the correction note in Part 33.

By Terp — Terp AI Labs

Start With The July 2026 Reality Check

The June trains (2026.6.8 → 2026.6.11) were about making OpenClaw dependable. If you last read this guide in mid-June, these are the new rules:

1. Claude subscription-era advice is dead. Anthropic's April 4 policy change broke the old "Claude Pro/Max covers OpenClaw" path. Treat Claude as paid API / Bedrock / provider-routed usage unless your own install proves otherwise.
2. Cost visibility is per-agent now. openclaw gateway usage-cost --agent <id> (or --all) shows spend per configured agent; cron it daily and treat spend jumps as context regressions. (There is no per-agent budget-cap config key — an earlier revision of this guide claimed one in error.)
3. Failover actually fires. Provider overloads are classified correctly, usage-limit responses route to fallbacks, and individual cron jobs can carry their own --fallbacks list (or run strict with --fallbacks ""). None of it helps without at least two configured lanes.
4. Fast mode is automatic. /fast auto (2026.6.10) runs short conversational turns in the provider's fast lane and returns to normal mode for longer work, with correct status through retries and fallback switches.
5. Long sessions got cheaper. Tool-heavy sessions now retain prompt-cache savings as results accumulate (2026.6.11) — one more reason to keep sessions long-lived and compaction healthy instead of resetting constantly.
6. Stuck channels self-recover. Telegram/WhatsApp queues that wedge after a crash or long-running task resume automatically in 2026.6.11. "Restart the gateway" should leave your runbooks.

Read Part 33 — June 2026 Field Guide first if you want the latest tricks before the deep dives.

The Harness Thesis

Most agent capability comes from the harness, not the weights.

The exact percentage is rhetoric. The operator lesson is concrete: model swaps help, but the big wins come from context budgets, memory discipline, tool permissions, flow control, provider routing, hooks, and verification loops.

flowchart LR
    subgraph Model["The Model (weights)"]
        M[Claude Opus 4.7<br/>or your choice]
    end
    subgraph Harness["The Harness (operator-controlled) — this guide"]
        direction TB
        Inst[Instructions<br/>SOUL/AGENTS/MEMORY/skills]
        Ctx[Context engineering<br/>budgets + progressive disclosure]
        Tools[Tools + approvals<br/>semantic categories]
        Guard[Guardrails<br/>hooks, Task Brain, redaction]
        Mem[Memory layer<br/>memory-core + LightRAG + dreaming]
        Orch[Orchestration<br/>5 coordination patterns]
    end
    Model -.-> Harness
    Harness -.-> Results[Production results]

You usually cannot change the weights. You can change everything else: context, memory, tools, approvals, verification, cost controls, and orchestration. The rest of this guide is that operator-controlled layer.

Jump straight to the payoff

File Hierarchy At A Glance

OpenClaw's file layout maps 1:1 to Karpathy's three-tier LLM Wiki pattern published April 10, 2026. If you only remember one diagram from this guide, make it this one:

flowchart TB
    subgraph Raw["Raw sources — immutable, agent read-only"]
        Vault["vault/*"]
        Daily["memory/YYYY-MM-DD.md"]
    end
    subgraph Curated["Curated summaries — injected on every message"]
        Soul["SOUL.md<br/>identity"]
        Agents["AGENTS.md<br/>operational rules"]
        Mem["MEMORY.md<br/>durable facts"]
        Dreams["DREAMS.md<br/>reflection diary"]
        Skills["skills/*<br/>on-demand playbooks"]
    end
    subgraph Artifacts["Generated artifacts — one-shot output"]
        PRs["PRs / commits"]
        Reports["Reports / transcripts"]
    end
    Raw -. memory_search .-> Agent((Agent))
    Curated --> Agent
    Agent --> Artifacts
    Agent -. Deep-phase promote .-> Mem
    Artifacts -. auto-capture .-> Daily

Full reasoning and update rules in Part 31 — The LLM Wiki Pattern In OpenClaw.

Who This Is For

• Running any OpenClaw agent in production. If your bot handles real work, the speed, memory, and security parts are non-optional.
• Just hit "why is my agent slow?" for the first time. Part 1 and Part 2 are where to start.
• Coming from v3.x or early v4.0. Start with Part 26 — Migration Guide, then Part 25 — Architecture Overview.
• Building multi-agent systems. Part 5 — Orchestration and Part 24 — Task Brain are your backbone.
• Already read half the guide and forget what's where. Jump to Part 27 — Gotchas & FAQ or the themed map below.

Start Here (In This Order)

1. Part 25 — Architecture Overview — 15-minute primer on what OpenClaw actually is under the hood (gateway, Task Brain, memory layer, skills, surfaces).
2. Part 14 — Quick Checklist — 30-minute setup checklist covering the 80/20.
3. Part 17 — The One-Shot Prompt — copy-paste prompt that automates the whole setup.
4. Part 27 — Gotchas & FAQ — keep this open while you work. Half your questions are here.

What You Get (Numbers From Our Production Deployment)

Full numbers in benchmarks/.

Companion resources shipped with the guide

Alongside the 33 parts themselves, this repo now includes the tooling that turns "I read the guide" into "I can audit and reproduce the results":

• SCORECARD.md — The OpenClaw Production Readiness Scorecard. 50 items across Speed / Memory / Orchestration / Security / Observability, 2 points each, max 100. Designed to be copy-pasted into your own repo and shared publicly.
• AWESOME.md — A curated, opinionated list of OpenClaw resources: skills worth installing, memory and orchestration tools, observability stacks, research papers, talks, communities, adjacent ecosystems.
• templates/ — A starter kit: tiny SOUL.md / AGENTS.md / MEMORY.md / TOOLS.md templates, a vault/ skeleton, and an example config that documents both legacy JSON blocks and the newer provider-catalog direction.
• benchmarks/METHODOLOGY.md + benchmarks/harness/ + benchmarks/runs/TEMPLATE.md — A reproducible benchmark methodology (4 pillars, 3 reference environments) plus a contract for submitting your own numbers via PR.
• CODE_OF_CONDUCT.md · SECURITY.md · SUPPORT.md — Community standards so you know how to file issues, report problems, and get help.
• GitHub Pages site — rendered from this repo via MkDocs-material: https://onlyterp.github.io/openclaw-optimization-guide/.

What Changed In This Release (July 2026 Refresh)

• Correction. The June refresh referenced a "2026.6.4 stable" release and config keys (agents.list[].budget, models.providers.<id>.health, policy check --export, memory promote --dry-run, memory.recall.maxParallel, sandbox.network.allow, /context map --diff, secrets.rotation.maxAgeDays, meetingNotes.retentionDays) that do not exist in any published OpenClaw release. Those sections have been rewritten around shipped features, and the templates have been fixed. Details in the correction note at the top of Part 33.
• Rebaselined on 2026.6.11 stable — the version map now tracks the real June trains: 2026.6.8, 2026.6.9, 2026.6.10, 2026.6.11.
• New Part 33 tips — per-agent cost visibility (openclaw gateway usage-cost), scheduled policy check --json attestations, working failover + per-cron-job --fallbacks, safe-by-default memory promote / --apply workflow, and automatic fast mode (/fast auto).
• Security guidance updated — secrets redacted from debug output, admin-only HTTP session/model overrides, package-source redirect/lookalike-path hardening, actionable plugins.allow trust warnings, @owner/<slug> skill verification, and key-free web-search providers staying opt-in.
• Ops quality-of-life — official openclaw/openclaw Docker Hub mirror, Slack router relay mode for multi-gateway deployments, openclaw agent --message-file, and cron deleteAfterRun transcript cleanup.

Previous Late-May 2026 refresh

• Updated Part 33 field guide — upgrade map from 2026.4.15 through 2026.5.22 stable / 2026.5.24-beta.1: Gateway performance caching, Meeting Notes, the bundled Policy plugin, Codex/MCP scoping, Discord voice, image-quality controls, iMessage approvals, and security hardening.
• Codex guidance — native Codex means canonical openai/gpt-* model refs; the operational work is MCP projection scoping, codex.defaultToolsApprovalMode, named OAuth profiles, and deny-all tool policy verification.
• Security guidance tightened — skill-file read/executable allowlist compatibility removed, symlinked credential files fail closed, doctor warns on plaintext secret-bearing config, and channel conformance belongs in the Policy plugin.

Earlier refreshes (Task Brain, ClawHub, the v4.0 architecture/migration/glossary primers, and the 2026.4.15 line) are captured in the version tables in Part 25 — Architecture Overview and Part 26 — Migration Guide.

How The Pieces Fit Together

flowchart LR
    You[You]
    subgraph Surfaces
        Canvas[Canvas UI]
        CLI[CLI / IDE]
        Cron[Cron / ACP]
    end
    subgraph Gateway["Gateway daemon (Task Brain)"]
        Ledger[Task ledger]
        Approvals[Semantic approvals]
        Auth[Auth / secrets]
    end
    subgraph Agents
        Main[Main agent]
        Workers[Sub-agents]
    end
    subgraph Memory["Memory layer"]
        MemCore[memory-core<br/>MEMORY.md + DREAMS.md]
        Lance[memory-lancedb<br/>vector search]
        Light[LightRAG<br/>graph RAG]
    end
    subgraph Capabilities
        Hub[ClawHub skills]
        Hooks[Hooks]
        Tools[Tools]
    end

    You --> Surfaces
    Surfaces --> Gateway
    Gateway --> Agents
    Agents --> Memory
    Agents --> Capabilities
    Capabilities -. register with .-> Gateway
    Memory -. feed .-> Agents

Full breakdown of each block in Part 25 — Architecture Overview.

Navigate By Goal

Not every part applies to every reader. Jump directly to the pillar that matches what you're trying to do:

Full Table of Contents

🎯 Primers & references

• 25. Architecture Overview — the 15-min mental map of v4.0+
• 26. Migration Guide — upgrade paths + rollback plans
• 27. Gotchas & FAQ — symptom → fix table + frequently asked questions
• 28. Glossary & Terminology — every term this guide assumes, on one page
• 33. June 2026 Field Guide — what changed after 2026.5.22 and what to do now
• 14. Quick Checklist — 30-minute setup
• 17. The One-Shot Prompt — automation prompt, updated for current defaults

⚡ Speed & context

1. Speed — Stop Being Slow — trim context, add fallbacks, reasoning mode, localModelLean
2. Context Engineering — The Discipline — quadratic scaling, pruning, compaction, 5-min cache TTL trap
3. Cron Session Bloat — The Hidden Killer — session file accumulation, cleanup

🧠 Memory 4. Memory — Stop Forgetting Everything — 3-tier memory, Ollama, lancedb cloud storage, Copilot embeddings 9. Vault Memory System — folders, MOCs, claim-named notes, wiki-links 10. State-of-the-Art Embeddings — qwen3-embedding, GPU tier, Windows path, Copilot provider 11. Auto-Capture Hook — automatic knowledge extraction after every session 12. Self-Improving System — micro-learning loop, HOT/WARM/COLD tiers 13. Memory Bridge — give Codex / Claude Code access to your vault 22. Built-In Dreaming (memory-core) — official 3-phase consolidation, DREAMS.md, memory-you-can-afford (LightMem + vbfs) 31. The LLM Wiki Pattern In OpenClaw — Karpathy's three-tier pattern mapped onto SOUL/AGENTS/MEMORY/skills 33. June 2026 Field Guide — per-agent cost visibility, scheduled Policy attestations, working failover + cron fallbacks, memory promotion review, automatic fast mode

🤝 Orchestration & models 5. Orchestration — sub-agents-as-GC, Anthropic's 5 coordination patterns, CEO/COO/Worker, verification 6. Models — What To Actually Use — provider comparison, pricing, local, localModelLean 7. Web Search — Tavily, Brave, Serper, Gemini grounding 8. One-Shotting Big Tasks — research-first methodology 30. The Ralph Loop In OpenClaw — autonomous while true wrappers, PRD.json, overnight runs 32. Self-Evolving Skills With SkillClaw — skill population evolution, Mem²Evolve

🧩 Knowledge graph & codebase 18. LightRAG — Graph RAG — entities + relationships, Web UI, REST, LangFuse tracing 19. Repowise — Codebase Intelligence — 60% fewer tokens, 4x faster coding agents 21. Real-Time Knowledge Sync — event-driven file watcher, <6s vault → LightRAG sync

🔒 Hardening & security 15. Infrastructure Hardening — compaction crash loops, GPU contention, secrets, gateway crash-loop fix, reserve-token cap, auth hot-reload, approval redaction, parallel OpenClaw with git worktrees 23. ClawHub Skills Marketplace — marketplace, malware, install policy 24. Task Brain Control Plane — unified task ledger, semantic approvals, trust boundaries 29. The Hook Catalog — 8 copy-paste hooks, exit-code semantics, deterministic enforcement

🔭 Observability 20. Agent Observability — LangFuse, reranker, n8n, workflow automation

📖 Reference 25. Architecture Overview (v4.0+) — gateway / agents / memory / skills / surfaces primer 26. Migration Guide — opinionated upgrade paths with rollback 27. Common Gotchas & FAQ — symptom-indexed troubleshooting 28. Glossary & Terminology — every term this guide assumes, on one page

📊 Benchmarks — real numbers from a production system (context savings, search latency, reindex results, SWE-bench rankings)

📁 Example Vault — populated mini-vault showing MOCs, wiki-links, Agent Notes, and .learnings/ after 2 weeks of use

🤝 Contributing — how to propose corrections, new parts, and version-bump PRs

The Problem

If you're running a stock OpenClaw setup, you're probably dealing with:

• Freezing and hitting context limits. Bloated workspace files exhaust the context window mid-response.
• Slow responses. 15-20KB+ of context injected every message = hundreds of milliseconds of latency per reply.
• Forgetting everything. New session = blank slate. No memory of yesterday's work or decisions.
• Inconsistent behavior. Without clear rules, personality drifts between sessions.
• Doing everything the expensive way. Main model writes code, does research, AND orchestrates - all at top-tier pricing.
• Flying blind. No web search means guessing at anything after training cutoff.
• Wrong model choice. Using whatever was default without considering the tradeoffs.

What This Fixes

After this setup:

How It Works

You ask a question
    ↓
Orchestrator (main model, lean context ~5KB)
    ↓
┌─────────────────────────────────────────┐
│  memory_search() - 45ms, local, $0     │
│  ┌─────────┐  ┌──────────┐  ┌────────┐ │
│  │MEMORY.md│→ │memory/*.md│→ │vault/* │ │
│  │(index)  │  │(quick)   │  │(deep)  │ │
│  └─────────┘  └──────────┘  └────────┘ │
└─────────────────────────────────────────┘
    ↓
Only relevant context loaded (~200 tokens)
    ↓
Fast, accurate response + sub-agents for heavy work

The key insight: Workspace files become lightweight routers, not storage. All knowledge lives in a local vector database. The bot loads only what it needs - not everything it's ever learned.

What The Optimized Files Look Like

Full versions in /templates:

SOUL.md (772 bytes - injected every message):

## Who You Are
- Direct, concise, no fluff. Say the useful thing, then stop.
- Have opinions. Disagree when warranted. No sycophancy.

## Memory Rule
Before answering about past work, projects, people, or decisions:
run memory_search FIRST. It costs 45ms. Not searching = wrong answers.

## Orchestrator Rule
You coordinate; sub-agents execute. Never write 50+ lines of code yourself.

MEMORY.md (581 bytes - slim pointer index):

## Active Projects
- Project A → vault/projects/project-a.md
- Project B → vault/projects/project-b.md

## Key People
- Person A - role, relationship → vault/people/person-a.md

Details live in vault/. The bot finds them via local vector search instead of paying the hot-path context tax every turn.

This isn't a settings tweak - it's a complete architecture change: memory routing, context engineering, and orchestration working together. The one-shot prompt at the bottom does the entire setup automatically.

Note: The examples assume a frontier orchestrator that can follow multi-step instructions. Opus 4.7 is still a strong default if you have a paid route and budget caps; Gemini/DeepSeek/Kimi/local workers handle most execution.

Templates included: Check /templates for ready-to-use versions of SOUL.md, AGENTS.md, MEMORY.md, TOOLS.md, and a sample vault/ structure.

Part 1: Speed (Stop Being Slow)

Read this if your agent feels laggy, you're on a Gemini/GPT default, or you just want to know which levers matter most. Start here if you only read one part. Skip if you've already tuned context, fallbacks, reasoning mode, and model selection.

Every message you send, OpenClaw injects selected hot-path context: system prompt, workspace bootstrap files, current conversation state, tool schemas, and sometimes skill/plugin context. Bloated files = slower, more expensive replies. This is the #1 speed issue people don't realize they have.

Why Trimming Works

You don't need big hot-path files once you have vector search.

Old approach: Stuff everything into MEMORY.md so the bot "sees" it every message → 15KB+ context, slow responses, wasted tokens on irrelevant info.

New approach: MEMORY.md is a slim index of pointers. Full details live in vault/. memory_search() retrieves them via local Ollama embeddings ($0). Your hot-path files stay tiny without losing any knowledge.

Trim Your Context Files

Rule: If it's longer than a tweet thread, it's too long for a workspace file. Move the details to vault/.

Add a Fallback Model

"agents": {
  "defaults": {
    "model": {
      "primary": "anthropic/opus",
      "fallbacks": [
        "deepseek/deepseek-v4-flash",
        "openrouter/moonshotai/kimi-k2.6"
      ]
    }
  }
}

OpenClaw's late-April and May releases moved hard toward provider-owned catalogs and fallback policy. Use provider/model refs where your install supports them. Explicit user /model selections are strict; configured defaults can fall through primary → fallback. The operator rule is stable: every production agent needs a primary, at least two fallbacks, and budget caps per expensive provider.

Current gotcha: /models add briefly shipped in 2026.4.22, then was deprecated in 2026.4.24. Use /models for browsing and copy-friendly examples, but treat durable model registration as config/catalog work, not chat-time mutation.

Reasoning Mode - Know the Tradeoff

Run /status to see your current reasoning mode.

• Off - fastest, no thinking phase
• Low - slight thinking, faster responses
• High - deep reasoning, adds 2-5 seconds but catches things low/off misses

I run high and keep it there. The context trimming from other steps more than compensates for the reasoning overhead.

Disable Unused Plugins

Every enabled plugin adds overhead. If you're not using memory-lancedb, memory-core, etc., set "enabled": false.

Lean Mode for Weak Local Models

New in 2026.4.15 and refined in 2026.5.20: if you're running a small local model (≤14B params, 16K-32K context) and the default tool set is eating the prompt, prefer per-agent lean mode for the small worker. Use the global default only when every agent on that profile is local/small:

{
  "agents": {
    "list": [
      {
        "id": "local-worker",
        "experimental": { "localModelLean": true }
      }
    ]
  }
}

This drops heavyweight default tools (browser, cron, message) from that worker's system prompt. You keep memory_search, exec, sessions_spawn, and the essentials — which is everything most local setups actually use. 2026.4.29 also relaxed fixed preflight cutoffs so small local models use guard thresholds derived from their effective context window instead of hard-coded 16K/32K floors.

Ollama Housekeeping

ollama ps        # Check what's loaded
ollama stop modelname  # Unload idle big models

The default model for memory search should be qwen3-embedding:0.6b (500 MB, 1024 dims) — same Qwen3 family that holds #1 on MTEB, runs on anything, and blows away nomic on quality. Pull it: ollama pull qwen3-embedding:0.6b. If you have a GPU with 8GB+ VRAM, upgrade to Qwen3-Embedding-8B for dramatically better search quality — see Part 10. If you have 500+ vault files, also add LightRAG (Part 18) for knowledge graph retrieval that blows away basic vector search.

New in 2026.4.15 — memory-lancedb cloud storage. memory-lancedb can now persist its index to S3-compatible object storage instead of local disk (storage.type: "s3" + bucket + prefix + endpoint). Useful for multi-machine setups where you want every box to see the same index, or for backing up a single-machine index without rsync. The hot path is still in-memory — cloud is just durable storage. Don't confuse this with cloud embeddings (still a bad idea for the hot path).

New in 2026.4.15 — GitHub Copilot embedding provider. If your team already pays for Copilot Business/Enterprise, agents.defaults.memorySearch.provider: "copilot" reuses that seat for embeddings. It's still cloud (2-5s round trips, same caveats as OpenAI/Voyage) so local Ollama is still the right default for personal setups — but for a corporate deployment that's already standardized on Copilot, this removes another vendor from the procurement list.

Part 2: Context Engineering — The Discipline

Renamed in the April 2026 refresh. "Context Bloat" was the problem; context engineering is the discipline. The Part 2 material is the practical version of that discipline for OpenClaw.

Read this if you notice each message getting slower, you're hitting compaction often, or your SOUL.md / MEMORY.md / AGENTS.md are over a few KB combined. Skip if your total injected context is already under 15 KB and compaction rarely fires.

The Quadratic Problem

LLM attention scales quadratically with context length:

• 2x the tokens = 4x the compute cost
• 3x the tokens = 9x the compute cost

When context goes from 50K to 100K tokens, the model does four times the work. That means slower responses and higher bills.

What Happens As Context Fills

Just because a model advertises 1M context doesn't mean it performs well at 1M:

• Long-context evals repeatedly show accuracy falling well before the advertised maximum.
• Latency can spike non-linearly once prompts move from "large" to "huge."
• Models exhibit "lost-in-the-middle" bias - they track the beginning and end but lose the middle
• Effective context is usually a fraction of the max

Where Bloat Comes From

Tool spam is the worst offender. A single exec returning a large file = 20K+ tokens permanently in your session. Five tool calls = 100K tokens of context the model re-reads every message.

The Numbers That Matter

Production agents often consume far more context than they generate. Your context window IS your performance budget.

Compression targets (from Maxim AI production data):

• Historical context: 3:1 to 5:1 compression ratio
• Tool outputs: 10:1 to 20:1 compression ratio
• If your agent is at >60% context utilization before the user speaks, you're in trouble

The 60% Rule: If system prompt + workspace files + memory search results exceed 60% of your context window before the user even sends a message, apply these in order:

1. Summarize conversation history
2. Filter retrieval results (fewer, more relevant chunks)
3. Route tools dynamically (only load tool definitions the agent needs this turn)
4. Compress step results from previous tool calls

The Cost Math

Lean (5K tokens/msg)   → Claude Opus: $0.025/msg
Bloated (50K tokens/msg) → Claude Opus: $0.25/msg   ← 10x more
Over 100 msgs/day: $2.25/day vs $22.50/day

Built-In Defenses

Session Pruning - Trims old tool results from context:

{
  "agents": {
    "defaults": {
      "contextPruning": { "mode": "cache-ttl", "ttl": "5m" }
    }
  }
}

Auto-Compaction - Summarizes older conversation when nearing context limits. Trigger manually with /compact.

2026.4.15 fix: The compaction reserve-token floor is now capped at the model's actual context window. Before this, compaction on a 16K-token local model could request a larger reserve than the window itself, creating an infinite "try to free N tokens, fail, retry" loop. If you run small local models as compaction workers, upgrade — this is the fix you want. See Part 15.

Context inspection (2026.5+): use the built-in commands before guessing:

• /status — quick context and session settings view.
• /context list — injected files and rough prompt sizes.
• /context detail — top skills, tool schemas, and system-prompt contributors.
• /context map — WinDirStat-style treemap image of tracked context contributors after the session has produced a real run report.

If /context map says no cached run report exists yet, send one normal message first; current builds refuse to draw estimates as if they were measured context.

Appendix — The 5-Minute Prompt Cache TTL Trap (March 2026)

Silent production killer that caught most teams in April 2026: Anthropic's prompt-cache default TTL dropped from 1 hour to 5 minutes sometime in early March 2026, without a release note most operators noticed. See the writeup Claude API Prompt Caching: Cut Costs 80% on Every Repeated Request (Apr 14, 2026).

If you built your SOUL/AGENTS/MEMORY context assuming a 1-hour cache, you're now paying full token price on every sub-5-minute gap between messages. For an orchestrator running one session at a time with users stopping to think between turns, the cache is essentially never hit. Bills silently tripled.

Symptom: Your Anthropic bill is up 2–4× month-over-month; token counts haven't changed.

Fix (OpenClaw). Set the cache TTL explicitly on any prompt segment that should live longer than 5 minutes:

{
  "agents": {
    "defaults": {
      "prompts": {
        "cacheControl": {
          "soul":     { "type": "ephemeral", "ttl": "1h" },
          "agents":   { "type": "ephemeral", "ttl": "1h" },
          "memory":   { "type": "ephemeral", "ttl": "1h" },
          "skills":   { "type": "ephemeral", "ttl": "5m" }
        }
      }
    }
  }
}

The hot-path files (SOUL, AGENTS, MEMORY) are stable within a session, so pin their TTL to 1h. Skills and dynamic context stay at 5m — they change too often to be worth extending.

Anthropic considers 1h-cached blocks billable, just at ~1/10 the rate of uncached tokens. Worth the trade for anything that's reused more than twice an hour.

Use both. Pruning handles tool result bloat. Compaction handles conversation history bloat.

Context Bloat Checklist

• Workspace files under 8 KB total
• Context pruning enabled (mode: "cache-ttl")
• Use /compact proactively when sessions feel slow
• Use /new when switching topics entirely
• Delegate heavy tool work to sub-agents (their context is separate)
• Monitor with /status - stay under 10-15% of your model's context window

Part 3: Cron Session Bloat (The Hidden Killer)

Read this if you run cron jobs, the sessions/ folder is huge, or you've ever wondered why a background agent gets slower week over week. Skip if you don't use cron / scheduled agents.

Every cron job creates a session transcript file (.jsonl). Over time:

• 30 cron jobs × 48 runs/day × 30 days = 43,200 session files
• The sessions.json index balloons, slowing session management

How to Spot It

# Linux/Mac
ls ~/.openclaw/agents/*/sessions/*.jsonl | wc -l

# Windows (PowerShell)
(Get-ChildItem ~\.openclaw\agents\*\sessions\*.jsonl).Count

Thousands of files = cron session bloat.

The Fix

1. Configure session rotation:

{ "session": { "maintenance": { "rotateBytes": "100mb" } } }

2. Clean up old sessions:

openclaw sessions cleanup

3. Use isolated sessions for cron:

{ "sessionTarget": "isolated", "payload": { "kind": "agentTurn", "message": "Do the thing" } }

Isolated sessions don't pile up in your main agent's session history.

Prevention > Cleanup

• Use delivery: { "mode": "none" } on crons where you don't need output announced
• Keep cron tasks focused - 1 tool call generates 15x less session data than 15

Part 4: Memory (Stop Forgetting Everything)

Read this if you want the 3-tier memory model (MEMORY.md + session files + vector search) from scratch. This is the foundation for Parts 9, 10, 11, 12, 13, 22. Skip if you're already running memory-core with a local embedding provider and a vault — skim for the 2026.4.15 memory_get / lancedb-cloud changes and move on.

Out of the box, OpenClaw forgets everything between sessions. The fix is a 3-tier memory system.

The Architecture

MEMORY.md          ← Slim index (< 3 KB), pointers only
memory/            ← Auto-searched by memory_search()
  projects.md
  people.md
  decisions.md
vault/             ← Deep storage, searched via memory
  projects/
  people/
  decisions/
  lessons/
  reference/
  research/

How It Works

1. MEMORY.md - table of contents with one-liner pointers. Never put full documents here.
2. memory/*.md - automatically searched when the bot calls memory_search("query").
3. vault/ - deep storage for detailed project docs, research notes, full profiles.

Setting It Up

Step 1: Install Ollama + embedding model

# Windows: winget install Ollama.Ollama
# Mac/Linux: curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3-embedding:0.6b

OpenClaw detects Ollama on localhost:11434 automatically. No config needed.

Low-RAM fallback: nomic-embed-text still works, but it is now the fallback, not the recommendation. For a major quality upgrade (768-dim → 4096-dim vectors), see Part 10: State-of-the-Art Embeddings.

Step 2: Create the directory structure

workspace/
  MEMORY.md
  memory/
  vault/
    projects/  people/  decisions/  lessons/  reference/  research/

Step 3: Slim down MEMORY.md

# MEMORY.md - Core Index
_Pointers only. Search before answering._

## Active Projects
- Project A → vault/projects/project-a.md

## Key Tools
- Tool X: `command here`

## Key Rules
- Rule 1

Step 4: Move everything else to vault/

Every detailed document → vault/. Leave a one-liner pointer in MEMORY.md or memory/.

Step 5: Set up memory consolidation

Session memory files pile up fast — 200+ files in a month. OpenClaw 2026.4+ has built-in dreaming (Part 22) — enable it in memory-core config and it auto-consolidates on a daily schedule. (Pre-2026.4 installs used to need the custom "autoDream" AGENTS.md pattern described in the retired Part 16; that file is gone — upgrade to 2026.4+ and use built-in dreaming instead.)

Security note (2026.4.15): memory_get is now restricted to canonical memory files — MEMORY.md and DREAMS.md. It no longer reads arbitrary files from the workspace by path. If you were doing memory_get("vault/projects/x.md") directly, switch to memory_search or a plain file read — the dedicated memory tool is strictly for the canonical agent indexes now. This closes a path-traversal vector that the memory-qmd backend allowed before.

Context budget change (2026.4.15 stable): memory_get now caps excerpt length by default and returns explicit continuation metadata instead of dumping entire files into context. If an excerpt was truncated, the tool response includes a follow-up cursor the agent can use to fetch the next chunk deterministically. On top of that, default startup and skills prompt budgets were trimmed — long sessions pull less context by default without losing deterministic follow-up reads. Practical effect: your MEMORY.md and DREAMS.md can grow without silently blowing up every reply. If you had custom skills that assumed memory_get returns the whole file, update them to respect the continuation cursor (it's noisy but one-line).

May 2026 upgrade: Active Memory supports per-conversation allowedChatIds / deniedChatIds, partial recall summaries on timeout, and people-aware wiki provenance reports. Do not enable broad automatic recall in every group chat. Scope it to the conversations where durable memory is actually appropriate, then audit provenance when the agent makes claims about people.

The Golden Rule

Add this to your SOUL.md:

## Memory
Before answering about past work, projects, or decisions:
run memory_search FIRST. It costs 45ms. Not searching = wrong answers.

Part 5: Orchestration (Stop Doing Everything Yourself)

Read this if you do anything non-trivial — research, coding, long tasks — in a single interactive agent and haven't set up sub-agent workers, verification, or the Ralph loop yet. Skip if you're already running CEO/COO/Worker with PreCompletionChecklist verification.

Sub-Agents Are Context Garbage Collection (Not A Speed Hack)

The mistake most teams make with sub-agents: treating them as a performance trick ("run two things in parallel = 2x speed"). That misses the point. The week of April 10–17, 2026 had five independent writeups (heyuan110 Apr 13, Builder.io Apr 16, and three more on DEV) all converging on the same reframe: sub-agents are context garbage collection.

The real unlock: a sub-agent is a disposable context window. You spawn one, it burns 40K tokens searching the codebase, it returns a 500-token summary, the sub-agent's context is thrown away. Your main agent's context stays lean. Without sub-agents, that 40K of search noise would permanently live in your main context, degrading every subsequent turn.

The 3-trigger decision table — spawn a sub-agent if any of these are true:

If none of those are true, don't spawn. Sub-agent invocation has real overhead — cold-start prompts, tool-registration roundtrips, summarization cost. Use them surgically, not reflexively.

Your main model should NEVER do heavy work directly. It should plan and delegate to cheaper, faster sub-agents — per the triggers above.

Anthropic's Five Multi-Agent Coordination Patterns (Apr 10, 2026)

On April 10, 2026, Anthropic published Multi-Agent Coordination Patterns — the first canonical naming of the patterns the community had been reinventing. The taxonomy is now the lingua franca for how agents work together. Use it. Old internal names ("CEO/COO/Worker", "critic loop") still map to these.

flowchart LR
    Q{Task shape?}
    Q -->|"Output correctness critical"| GV[Generator-Verifier]
    Q -->|"Clear strategy + narrow execute"| OS[Orchestrator-Subagent]
    Q -->|"Distinct roles, bounded"| AT[Agent Teams]
    Q -->|"Deep task tree"| HI[Hierarchical]
    Q -->|"Peer-to-peer flow"| NET[Network — careful]

Default picks for an OpenClaw operator: Orchestrator-Subagent for 80% of work, Generator-Verifier for code and decisions, Agent Teams for long research loops, Hierarchical when Task Brain flows nest 3+ levels deep, Network almost never.

The Ralph Loop (Part 30) is a specific flavor of Orchestrator-Subagent where the orchestrator is an outer bash wrapper and every iteration is a fresh agent session.

Your main model should NEVER do heavy work directly. It should plan and delegate to cheaper, faster sub-agents.

The Mental Model

• You = CEO (gives direction)
• Your Bot (main model) = COO (plans, coordinates, makes decisions)
• Sub-agents (cheaper/faster model) = Workers (execute tasks fast and cheap)

Add This to AGENTS.md

## Core Rule
You are the ORCHESTRATOR. You coordinate; sub-agents execute.
- Code task (3+ files)? → Spawn coding agent
- Research task? → Spawn research agent
- 2+ independent tasks? → Spawn ALL in parallel

## Model Strategy
- YOU (orchestrator): Best model - planning, judgment, synthesis
- Sub-agents (workers): Cheaper/faster model - execution, code, research

2026.3.31-beta.1+ — every spawn is a Task Brain task/flow. Sub-agents, ACP runs, and cron jobs all flow through the same unified task ledger now (openclaw tasks list, with openclaw tasks flow ... for flow views). Semantic approval categories (execution.*, read-only.*, control-plane.*) replace the old name-based allowlist. If you're seeing unexpected "approval required" prompts on sub-agent spawns, check Part 24 — Task Brain Control Plane for how to configure categories and trust boundaries.

Your expensive model decides WHAT to build. The cheap model builds it. Right model, right job.

A Complete Multi-Agent Example: Chief of Staff + Workers

The patterns above are abstract until you see the whole thing wired together. Here is a minimal-but-complete three-agent setup — a chief-of-staff orchestrator plus two scoped workers — using the config shapes from templates/openclaw.example.json. It's the Orchestrator-Subagent pattern with real files and real config.

Verify key names against your installed build. Config keys move between betas. Treat this as the shape of a multi-agent setup; confirm the exact keys with openclaw doctor and openclaw exec-policy show, and see the Part 24 version-accuracy note on approvals.

File layout. Each agent gets its own identity (SOUL.md), operating rules (AGENTS.md), and tool docs (TOOLS.md) — the three files that survive the 2026.5.22 worker-bootstrap narrowing (see Part 24). The orchestrator's files are the only ones loaded into your interactive session; worker files load only when that worker is spawned.

~/.openclaw/
  openclaw.json            # the agents.list config below
  agents/
    chief-of-staff/        # orchestrator: plans, delegates, never executes
      SOUL.md  AGENTS.md  TOOLS.md
    coding-worker/         # executes code in a sandboxed repo
      SOUL.md  AGENTS.md  TOOLS.md
    research-worker/       # read-only research, returns summaries
      SOUL.md  AGENTS.md  TOOLS.md

The config (openclaw.json). agents.defaults sets shared model/memory/compaction (see the template for the full block); agents.list[] adds per-agent overrides. The orchestrator runs a frontier model; workers run cheaper/local models, and the local one opts into lean mode:

{
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/opus", "fallbacks": ["google/gemini-3-flash", "deepseek/deepseek-v4-flash"] },
      "contextPruning": { "mode": "cache-ttl", "ttl": "5m" },
      "compaction": { "model": "cerebras/gpt-oss-120b", "reserveTokens": 8000 }
    },
    "list": [
      {
        "id": "chief-of-staff",
        "model": { "primary": "anthropic/opus" },
        "_comment": "Orchestrator. Best model — planning and judgment only. Never does heavy tool work itself."
      },
      {
        "id": "coding-worker",
        "model": { "primary": "deepseek/deepseek-v4-flash" },
        "_comment": "Spawned for code tasks. Runs tests; commits; reports the hash + a short summary."
      },
      {
        "id": "research-worker",
        "model": { "primary": "google/gemini-3-flash" },
        "experimental": { "localModelLean": true },
        "_comment": "Read-only research. Lean mode drops heavyweight default tools from its prompt."
      }
    ]
  }
}

Tool + approval scoping (defense in depth). Don't rely on the prompt to keep a worker in its lane — enforce it. Use Task Brain semantic approvals for what each agent may do and tools.toolsBySender for who may reach the agent at all (both detailed in Part 24):

{
  "taskBrain": {
    "approvals": {
      "defaults": { "read-only.*": "allow", "execution.sandbox.*": "allow", "execution.*": "ask", "write.fs.workspace": "allow", "write.fs.outside-workspace": "deny", "write.network": "ask", "control-plane.*": "deny" }
    }
  }
}

• chief-of-staff keeps execution.* and write.network on ask — it should be pausing for you, not running shells.
• coding-worker can be granted execution.shell/execution.code/write.fs.workspace = allow (it needs to run tests) but write.network = deny — a worker should never post.
• research-worker gets read-only.* = allow and everything else deny.

(Per-agent overrides live next to each agents.list[] entry; confirm the exact nesting against your version per the note above.)

The two files that do the orchestration. The orchestrator's SOUL.md is its identity; its AGENTS.md is the delegation rulebook:

# chief-of-staff/SOUL.md
You are the Chief of Staff. You hold strategy and context; you do not execute.
Your value is judgment, not throughput. Delegate execution; verify results.

# chief-of-staff/AGENTS.md
## Core Rule
You coordinate; workers execute. Never write 50+ lines of code or do wide searches yourself.
- Code task (3+ files / 10+ edits)?  → spawn `coding-worker`
- Research / wide search?            → spawn `research-worker`
- 2+ independent tasks?              → spawn workers in PARALLEL

## Delegation Protocol
- Each spawn is a self-contained work order: goal, constraints, and the bounded
  context the worker needs (it no longer inherits your persona/memory by default).
- Workers return a short summary, not their transcript. Their context is thrown away.

## Verification
- For code: require the worker to run tests and report the result, not "looks good".
- Spawn a FRESH worker to verify anything correctness-critical (Generator-Verifier).

The flow at runtime. You ask the chief of staff for something; it plans and delegates:

You → chief-of-staff: "Add rate limiting to the API and document it."
chief-of-staff:
  ├─ spawn coding-worker:   "Add a token-bucket limiter to src/api/*. Run tests. Report hash."
  └─ spawn research-worker: "Summarize our past rate-limit decisions from the vault."
        (both run as Task Brain tasks — visible in `openclaw tasks list`)
coding-worker   → "Done. 3 files, tests green, commit a1b2c3d. Summary: …"
research-worker → "We previously chose token-bucket over leaky-bucket because …"
chief-of-staff  → synthesizes both, verifies against your request, replies.

Every spawn is a Task Brain task, so the whole tree is auditable: openclaw tasks list shows what ran, openclaw tasks flow show <id> traces sub-tasks back to the originating request.

Optimizing the setup (tokens + latency). A multi-agent system multiplies token spend if you're careless. The levers, all in the config above:

The result is the CEO/COO/Worker model with enforcement instead of an honor system: scoped tools, audited spawns, and a token bill that scales with the worker tier, not the orchestrator.

PreCompletion Verification (from LangChain's +13.7 point harness improvement)

LangChain's coding agent went from outside the Top 30 to Top 5 on Terminal Bench 2.0 by only changing the harness — not the model. Their #1 improvement: force verification before exit.

Add this to your AGENTS.md:

## PreCompletion Verification
Before finishing ANY task, STOP and verify:
1. Re-read the user's original request
2. Compare your output against what was actually asked
3. If there's a gap, fix it before responding
4. For code: run tests — don't just re-read your own code and say "looks good"

Why this works: Agents are biased toward their first plausible solution. They write code, re-read it, say "looks good", and stop. Forcing a verification pass against the original request (not their own output) catches the gap.

Also add loop detection:

## Loop Detection
If you edit the same file 5+ times without progress, STOP.
Step back, reconsider your approach entirely.
Don't make small variations to the same broken approach — that's a doom loop.

LangChain uses a LoopDetectionMiddleware that tracks per-file edit counts and injects "consider reconsidering your approach" after N edits. Simple but effective.

Long-Running Projects (Multi-Session Work)

From Anthropic's own engineering blog: for projects spanning multiple sessions, use the initializer + progress file pattern:

## Multi-Session Protocol
- Work on ONE feature at a time — don't one-shot everything
- Create/update a `progress.txt` in the project dir:
  - What's DONE (with dates)
  - What's IN PROGRESS (with blockers)
  - What's NEXT (prioritized)
- Start each session: read progress.txt → git log → run basic test → THEN start work
- End each session: commit with descriptive message, update progress.txt

Use JSON for feature tracking when you need structured state (model is less likely to accidentally modify JSON vs markdown). Anthropic found this solved two critical failure modes: agents trying to one-shot everything, and agents declaring victory too early.

The Ralph Wiggum Loop (Autonomous Tasks)

Named after the Simpsons character, this is one of the most powerful patterns for overnight/autonomous agent work. Core idea: when an agent tries to stop, force it to keep working until tests actually pass.

# The original 5-line Ralph loop
while true; do
  cat prompt.md | claude --print | tee output.txt
  if ./run_tests.sh; then break; fi
done

The insight: agents love to declare "done" before work is actually done. External verification (tests, linters, type checkers) can't lie — the agent can. The loop forces build→test→fix cycles until reality matches expectations.

Add to your AGENTS.md for autonomous tasks:

## Ralph Loop (Autonomous Tasks)
For overnight/unattended work:
- Don't trust "looks good" — run REAL tests
- Loop: implement → test → if fail → fix → test again
- Only done when tests ACTUALLY PASS
- 10+ iterations without progress → stop and report failure

Common traps: Loop never ends (criteria too strict), loop ends too early (agent fakes the completion promise), quality degrades over iterations (random changes hoping something sticks). Fix: strengthen verification to run BEFORE accepting the promise.

Source: ghuntley.com/loop, Letta Code /ralph command, LangChain PreCompletionChecklistMiddleware

The 4-Phase Coordinator Protocol (Advanced)

For complex multi-step tasks, use the coordinator pattern — originally reverse-engineered from the Claude Code / autoDream leak, now absorbed into built-in dreaming and sub-agent spawning:

Key rules:

• "Parallelism is your superpower" — launch independent workers concurrently
• Never say "based on your findings" — read the actual findings and write specific specs
• Workers can't see your conversation — every prompt must be self-contained
• Include a purpose statement: "This research will inform a PR — focus on user-facing changes"
• Exclusive file ownership (from Zerg): each worker's spec lists which files it owns. No two workers edit the same file. Eliminates merge conflicts entirely.
• Workers self-verify before reporting done: "Run tests and typecheck, then commit and report the hash"

Continue vs Spawn fresh?

Give Coding Agents Your Brain

Codebase Intelligence (NEW — Part 19): Before spawning coding agents, use Repowise to give them full codebase context — dependency graphs, git ownership, architectural decisions, dead code detection. 60% fewer tokens, 4x faster task completion. pip install repowise && repowise init --path /project --index-only

Memory Bridge: Before spawning any coding sub-agent, run the Memory Bridge preflight to inject relevant vault knowledge into the project directory:

node scripts/memory-bridge/preflight-context.js --task "Build auth middleware" --workdir ./my-project

This writes a CONTEXT.md that the coding agent reads automatically — giving it access to your past decisions, error patterns, and architecture choices. See Part 13 for the full setup.

Part 6: Models (What to Actually Use)

Read this if you're picking providers/models, debating local vs. cloud, or you want an opinionated cost/latency matrix for 2026-era models. Skip if you have a provider mix you're happy with and your bills are sane.

The Model Strategy

Model Deep Dive

Claude Opus 4.7 - The Best Orchestrator (new default in 2026.4.15)

• Unmatched multi-step reasoning and complex tool use
• Follows long, nuanced system prompts better than any other model
• 1M context window with prompt caching (up to 90% savings on cached tokens)
• Cost: paid provider/API route. Do not assume Claude Pro/Max subscription usage covers OpenClaw after Anthropic's April 4 cutoff.

Claude Sonnet 4 - Solid Workhorse

• 80% of Opus quality at 20% of the cost. Strong at coding.
• Note: Some power users (including the author) have dropped Sonnet entirely in favor of Opus for orchestration + Cerebras/Gemini for sub-agents. The quality gap matters when your agent makes architectural decisions.
• Cost: paid provider/API route; check your current provider catalog and billing dashboard.

Cerebras gpt-oss-120b - Infrastructure Workhorse

• 3000 tok/s, $0.60/M input+output. Perfect for compaction, fallbacks, and bulk work where speed matters more than nuance.
• Free tier: 1M tokens/day (insufficient for heavy use, but good for testing).
• We use this as the fallback for every agent and as the compaction model.
• ⚠️ Don't use for knowledge graph entity extraction — hallucination risk is too high for memory-critical tasks. Use Qwen3 235B instead (still 1400 tok/s on Cerebras, much more accurate).

Cerebras qwen-3-235b - Knowledge Graph & Quality Tasks

• 1400 tok/s, still faster than most providers serve 8B models.
• Use for: LightRAG entity extraction, complex analysis, anything where accuracy matters more than raw speed.
• The 235B beats 120B on structured extraction tasks where hallucinated relationships would poison your knowledge graph.

April 2026 correction: older versions of this guide recommended using Claude Pro/Max membership as the cheapest OpenClaw path. That is no longer safe advice after Anthropic's April 4 cutoff for third-party OpenClaw usage. Use explicit API billing, Bedrock/Mantle, or a provider route you have verified in your own install.

Gemini 3.1 Pro / 3 Pro - Free Powerhouse

• Competitive with Sonnet on most tasks - and it's free. 1M context, multimodal.
• Weaker than Claude on complex agentic tool-use chains.

Gemini Flash (2.5 / 3) - Speed Demon

• Fastest responses of any capable model. Perfect for sub-agents. Free.

OpenAI / Codex app-server - Code-specialized batch lane

• Current OpenClaw uses canonical openai/gpt-* model refs for native Codex app-server runs; openai-codex is the auth-profile/provider surface, not the durable model prefix.
• Use this lane for scaffolding, CRUD, refactors, and UI-test workers when the Codex plugin is healthy. Keep Memory Bridge or an explicit CONTEXT.md in the workdir so Codex does not start blind.
• Cost: varies by OpenAI API vs ChatGPT/Codex subscription auth route. Check openclaw models auth list, openclaw status, and your provider billing before a large batch.

Grok 4 / 4.1 Fast - The Dark Horse

• Grok 4.20 has a massive 2M context window. Grok 4.1 Fast is insanely cheap.
• Cost: Grok 4: $3/M in, $15/M out | Grok 4.1 Fast: $0.20/M in, $0.50/M out

Kimi K2.6 / K2.5 - Budget Sub-Agent King

• OpenClaw 2026.4.20 moved bundled Moonshot setup, web search, and media-understanding surfaces to kimi-k2.6 while keeping K2.5 available for compatibility.
• Kimi remains a strong cheap worker lane. Verify current pricing in your provider catalog before running a large swarm.

MiMo V2 Pro (Xiaomi) - The Sleeper

• 1T parameter model, 1M context. Great for agentic sub-agents on a budget. $1/M in, $3/M out.

OpenRouter: The Model Marketplace

OpenRouter gives you dozens of models through one API key. Notable options:

• openrouter/free - auto-routes to the best free model for your request. Perfect for $0 sub-agents.
• MiMo V2 Pro - Currently free (launch promotion). Add: openrouter/xiaomi/mimo-v2-pro
• Kimi K2.6 / K2.5 - Budget powerhouse. Prefer the catalog's current kimi-k2.6 row when present; keep kimi-k2.5 for compatibility.
• Perplexity Sonar - Built-in web search, no separate tool needed. Add: openrouter/perplexity/sonar

Local Models: $0 Forever, No Rate Limits

If you have a GPU, local models via Ollama = unlimited inference at zero cost.

• QwOpus (Qwen 3.5 27B + Opus reasoning distilled) - Opus-style thinking locally. 63 tok/s on RTX 5090, 1M context with Q4 KV cache. ollama pull qwopus
• TerpBot (Nemotron 30B fine-tuned) - Custom fine-tune on clean 9.4K examples. 235 tok/s on 5090, 91.93% MMLU-Pro Math. Not public — but Nemotron 30B base is: ollama pull nemotron-30b
• NVIDIA Nemotron Nano 4B - Punches above its weight, 128K context, fits on any GPU. ollama pull nemotron-nano

2026.5.20 — if one worker is small/local, use per-agent localModelLean. Set agents.list[].experimental.localModelLean: true on the small worker and the gateway stops injecting heavyweight default tools (browser, cron, message) into that worker prompt. You keep memory_search, exec, sessions_spawn — i.e. the tools a local model can actually use. Frees ~3KB of prompt without starving frontier orchestrators.

Claude Subscription Path Retired

Do not build a new OpenClaw deployment around Claude Pro/Max subscription-backed usage. The April 4 Anthropic cutoff forced third-party OpenClaw usage onto explicit paid routes for many users. If your install still has a working Claude OAuth path, treat it as legacy and fragile, not a baseline.

Current safer paths:

1. Use an explicit Anthropic API key with budget caps.
2. Use Bedrock/Mantle for Opus 4.7 if that is how your org buys Anthropic.
3. Put cheaper fallbacks behind every Claude primary.
4. Watch the Model Auth card before big runs.

Recommended Setups

Budget ($0/month):

Main: DeepSeek V4 Flash or Gemini free tier | Workers: Kimi / Flash / local | Embeddings: qwen3-embedding:0.6b

Balanced (low paid spend):

Main: Sonnet or Gemini Pro via API | Fallback: DeepSeek V4 Flash | Workers: Kimi K2.6 / DeepInfra / local

Power (paid provider caps required):

Main: Opus 4.7 via API/Bedrock | Fallback: Gemini Pro / DeepSeek V4 Pro | Sub-agents: Kimi / MiMo / Flash / DeepInfra
Code (hard): Opus directly | Code (batch): Codex + Memory Bridge
Self-improving: .learnings/ micro-loop ($0) | Memory: Qwen3-Embedding-8B on local GPU
Knowledge Graph: LightRAG + Cerebras qwen-3-235b (Part 18)
Codebase Intel: Repowise (Part 19) | Observability: LangFuse (Part 20)

Pro Tips

• Always set 2-3 fallbacks. Auto-switch beats breaking.
• Match model to task. Don't use Opus for scripts. Don't use Flash for architecture.
• Enable prompt caching on Anthropic: explicit prompt cache-control TTLs + cache-ttl pruning.
• Set budget caps. The post-cutoff provider world makes unbounded fallback chains dangerous.
• Use provider catalogs. Current OpenClaw relies on manifest-backed model rows; stale hand-written model aliases break more often.
• Don't use /models add for durable config. It was added in 2026.4.22, then deprecated in 2026.4.24. Use /models to inspect, then update config/catalogs deliberately.
• Free models are real. Gemini's free tier is legitimately good for daily driving.
• Watch the Model Auth card (new 2026.4.15). Control UI shows per-provider OAuth token health and rate-limit pressure. Before a big run, eyeball it — catching an expiring provider token or a rate-limited Gemini key there beats debugging mid-task.

Part 7: Web Search (Give Your Agent Eyes on the Internet)

Read this if your agent needs fresh web data and you haven't picked a search provider, or you're using Gemini grounding and it's failing silently. Skip if your agent doesn't need web search, or you already have Tavily/Brave/Serper wired in.

Without web search, your agent guesses at anything after its training cutoff.

The Players

Why We Use Tavily

1. Built for AI agents. Returns clean, structured, pre-processed content - not a list of links. One API call → usable answer. No fetching/parsing extra steps.
2. Search + Extract + Crawl in one API. Fewer tools, fewer context-eating tool calls.
3. Depth control. Basic (1 credit, fast) vs Advanced (2 credits, comprehensive) - per query.
4. Usable free tier. 1,000 credits/month = enough for a personal assistant that searches a few times daily.
5. Built-in safety. Guards against prompt injection from search results and PII leakage.

Setting Up Tavily

1. Get a free API key at tavily.com (30 seconds)
2. Add to TOOLS.md: Tavily Search: For grounded web research. Basic for lookups, advanced for deep research.
3. For research sub-agents, include Tavily in task instructions

When to Use What

Part 8: One-Shotting Big Tasks (Stop Iterating, Start Researching)

Read this if your agent keeps iterating on big tasks (refactors, migrations, research) and producing half-baked results. Skip if your tasks are small and iterative-by-design (REPLs, ad-hoc queries).

Most people type a vague prompt, iterate 15 times, burn context and money, end up at 60% quality. The model isn't the problem - your prompt is.

The Pattern

• Vague prompts produce vague plans, extra iterations, and security blind spots.
• Detailed specifications give the agent constraints it can actually verify.
• Research-first prompts beat "just implement it" prompts on any task with unknowns.

The quality of your output is capped by the quality of your input.

Why Iteration Fails

1. Burns context - each correction adds to history, pushing toward bloat
2. Confuses the model - contradictory instructions across rounds
3. Pays twice - you paid for the bad output AND the correction
4. Loses coherence - by iteration 8, the agent forgot iteration 1 (lost-in-the-middle)

The Method: Research → Spec → Ship

Phase 1: Research (30-60 minutes)

Before building, know what "good" looks like:

1. Find best examples - Search for top 3-5 implementations, study their tech stack and shared features
2. Analyze UI patterns - Screenshot the best UIs, note layouts, color schemes, component patterns
3. Study the tech stack - Pick the stack the best implementations use, not your default
4. Find the pitfalls - Search for common mistakes. Every pitfall in your prompt = one fewer iteration

Phase 2: Write the Spec (15-30 minutes)

Turn research into a blueprint:

# Project: [Name]

## Context
[What this is, who it's for, why it exists]

## Research Summary
[Key findings - what the best implementations do]

## Tech Stack
- Framework: [choice based on research]
- UI Library: [choice]
- Key Dependencies: [list]

## Features (Priority Order)
1. [Feature] - [acceptance criteria]
2. [Feature] - [acceptance criteria]

## File Structure
[Project organization]

## Quality Bar
- [ ] Responsive, error handling, loading states
- [ ] Clean code, no TODOs in final output

## What NOT To Do
- [Pitfall from research]

Why this works: You're not asking the AI to make 50+ decisions - you've already made them based on research. The AI executes, not strategizes. Blueprints, not vibes.

Phase 3: Delegate and Ship

Send the spec to a coding agent, not your orchestrator:

sessions_spawn({
  task: "[full spec]",
  mode: "run",
  runtime: "subagent"  // or "acp" for Codex/Claude Code
})

• Run Memory Bridge preflight first. Before spawning any coding agent, inject vault context: node scripts/memory-bridge/preflight-context.js --task "..." --workdir <project> This writes a CONTEXT.md with relevant past decisions and patterns. See Part 13.
• Send to a coding model. Your main model plans, not builds. For hard architecture work, Opus can code directly (#1 SWE-bench).
• Include everything in one prompt. If you're thinking "I'll clarify later," you haven't researched enough.
• Attach reference images for vision-capable models.

Let Your Agent Do the Research

You don't have to research manually - make your agent do Phase 1:

Before building anything, research first:
1. Find top 5 [things] that exist. What tech/UI patterns do they share?
2. Search "[thing] best practices 2026" - summarize key patterns.
3. Search "[thing] common mistakes" - list top pitfalls.
4. Based on research, write a detailed spec with tech stack, features,
   file structure, and quality bar.
Do NOT start building until the spec is written and I approve it.

The workflow:

You: "Research and spec out a [thing]"     → 2 min
Agent: [Tavily research → writes spec]     → 3-5 min
You: "Looks good, build it"                → 30 sec
Agent: [builds from spec]                  → one-shot quality

5 minutes of research saves 3+ hours of iteration. The math always works out.

Part 9: Vault Memory System (Stop Losing Knowledge Between Sessions)

Read this if Part 4's flat memory works but the agent is getting dumber the more you teach it, or you have 200+ memory files and search returns noise. Skip if you have fewer than ~50 memory files — stay on the basics from Part 4 until you hit the wall.

Part 4 gave you memory. But after months of daily use, your agent gets dumber, not smarter. We hit this: 358 memory files, 100MB+ of accumulated knowledge, vector search returning irrelevant results because every query matches 15 slightly different files. Date-named files that tell you nothing. Research conclusions lost because nobody saved them.

The more you teach it, the worse it gets. That's the sign your memory architecture is broken.

Why Flat Files + Vector Search Breaks Down

Vector search finds what's similar - not what's connected. Ask "what do we know about God Mode?" and you get 8 files that all mention Cerebras. None give the full picture because it's spread across 12 files that vector search doesn't know are related.

The fix isn't better embeddings. It's structure.

The Solution: Vault Architecture

An Obsidian-inspired linked knowledge vault with four key ideas:

1. Notes named as claims - the filename IS the knowledge
2. MOCs (Maps of Content) link related notes - one page = full picture
3. Wiki-links create a traversable graph - follow connections, not similarity
4. Agent Notes provide cross-session breadcrumbs - next session picks up where this one left off

Folder Structure

vault/
  00_inbox/      ← Raw captures. Dump here, structure later
  01_thinking/   ← MOCs + synthesized notes
  02_reference/  ← External knowledge, tool docs, API references
  03_creating/   ← Content drafts in progress
  04_published/  ← Finished work
  05_archive/    ← Inactive content. Never delete, always archive
  06_system/     ← Templates, vault philosophy, graph index

Claim-Named Notes

Stop naming files by date. Name them by what they claim:

BAD:  2026-03-19.md              GOOD: nemotron-mamba-wont-train-on-windows.md
BAD:  session-notes.md           GOOD: memory-is-the-bottleneck.md
BAD:  cerebras-research.md       GOOD: god-mode-is-cerebras-plus-orchestration.md

The agent reads filenames before content. When every filename is a claim, scanning a folder gives the agent a map of everything you know - without opening a single file.

MOCs - Maps of Content

A MOC connects related notes with [[wiki-links]]. Example:

# Memory Is The Bottleneck

## Key Facts
- 358 memory files in memory/, mostly date-named
- Vector search (`qwen3-embedding:0.6b`, <100ms local, $0) finds similar, not connected
- MEMORY.md must stay under 5K - injected on every message

## Connected Topics
- [[vault/decisions/memory-architecture.md]]
- [[vault/research/rag-injection-research.md]]
- [[vault/projects/reasoning-traces.md]]

## Agent Notes
- [x] Vault restructure completed - 8 MOCs + philosophy doc
- [ ] Every session MUST save knowledge to memory

The ## Agent Notes section is the cross-session breadcrumb trail. Each session updates these notes; the next session reads them and picks up where the last one stopped.

Vault Philosophy Document

Save to vault/06_system/vault-philosophy.md - this teaches your agent HOW to use the vault:

1. The Network Is The Knowledge - No single note is the answer. The answer is the path through connected notes.
2. Notes Are Named As Claims - Bad: local-models.md. Good: local-models-are-the-fast-layer.md.
3. Links Woven Into Sentences - Not footnotes. Context-rich inline links.
4. Agent Orients Before Acting - Scan MOCs → read relevant MOC → follow links → respond.
5. Agent Leaves Breadcrumbs - Update MOC "Agent Notes" after every session.
6. Capture First, Structure Later - Dump in 00_inbox/ now. Organize later.

The Graph Tools

MOCs and wiki-links create a graph, but the agent needs tooling to traverse it. See scripts/vault-graph/ for the complete tools (committed to this repo — see scripts/):

Graph search vs vector search:

• memory_search("topic") → Find files you didn't know were relevant (similarity)
• node scripts/vault-graph/graph-search.mjs "topic" → Navigate files you know are connected (structure)

Use both. Vector search discovers; graph search navigates.

The Orientation Protocol

Add to your AGENTS.md:

## Vault Orientation Protocol
1. Scan `vault/01_thinking/` - read MOC filenames (claim-named = instant topic map)
2. If user message relates to an existing MOC, read it before responding
3. Follow [[wiki-links]] from the MOC for deeper context
4. After session work: update MOC "Agent Notes" with what was done/discovered
5. New knowledge → claim-named notes in `vault/00_inbox/`

This creates a cycle: orient → work → capture → update → next session orients from breadcrumbs.

Kill the Bloat

If you have a memory/knowledge-base/ full of generic reference material, move it:

mv memory/knowledge-base vault/05_archive/knowledge-base

Your primary search path (memory/ + vault/01_thinking/) should contain only YOUR knowledge - not generic docs the agent could web search.

Before: "memory architecture" returns 15 results - 3 about your system, 12 generic RAG articles. After: Same search returns 3 results - all about your actual system.

Results

Quick Setup

1. Create vault structure: mkdir -p vault/{00_inbox,01_thinking,02_reference,03_creating,04_published,05_archive,06_system}
2. Create your first MOC in vault/01_thinking/ - name it as a claim, follow the template above
3. Save vault philosophy to vault/06_system/vault-philosophy.md
4. Set up graph tools: mkdir -p scripts/vault-graph - save the scripts from this repo
5. Build initial graph: node scripts/vault-graph/graph-indexer.mjs
6. Add orientation protocol to AGENTS.md
7. Move bloat to archive: mv memory/knowledge-base vault/05_archive/knowledge-base
8. Rebuild graph: node scripts/vault-graph/graph-indexer.mjs

Part 14: Quick Checklist

Read this if you want a single printable page of everything else in the guide, for reviewing an install or onboarding a teammate. Skip if you're reading the guide linearly — this will repeat what you just read.

Run through this in 30 minutes:

• MEMORY.md under 3 KB (pointers only)
• SOUL.md under 1 KB
• AGENTS.md under 2 KB
• Total workspace context under 8 KB
• Context pruning enabled (mode: "cache-ttl")
• Cron sessions cleaned up / isolated sessions configured
• Ollama installed + embedding model pulled (qwen3-embedding:0.6b recommended, see Part 10 for tiers)
• vault/ directory structure created
• Claude usage moved off subscription assumptions and onto verified API/provider routing
• Provider fallbacks and budget caps configured for every expensive primary
• /models add removed from your runbooks; model registration happens through config/catalogs
• Codex routes use canonical openai/gpt-* refs through app-server, not legacy codex-cli assumptions
• /context map reviewed once on a real session before trimming prompt/tool bloat
• Active Memory scoped with allowedChatIds / deniedChatIds if you use group or channel surfaces
• messages.queue.mode intentionally set (steer for live correction, followup/collect/interrupt only by design)
• tools.toolsBySender denies runtime/filesystem tools for guests and public-channel senders
• Browser automation uses coordinate clicks / longer action budgets where selector-based actions are flaky
• Model strategy chosen (orchestrator + sub-agents + fallbacks)
• Faster/cheaper fallback model added
• Web search API configured (Tavily recommended, Gemini grounding for free)
• Unused plugins disabled
• Reasoning mode - high for best quality, low/off for speed
• Orchestration rules in AGENTS.md
• memory_search habit added to SOUL.md
• Vault orientation protocol in AGENTS.md
• For big tasks: research first, spec second, build third (Part 8)
• .learnings/ directory created with HOT.md, corrections.md, ERRORS.md (Part 12)
• Micro-learning loop added to AGENTS.md (Part 12)
• Daily learnings promotion cron set up — $0 on Cerebras (Part 12)
• Memory Bridge scripts installed — preflight-context.js + memory-query.js (Part 13)
• AGENTS.md updated: run preflight before every Codex spawn (Part 13)
• Built-in dreaming enabled in memory-core config (Part 22) — replaces the retired custom autoDream pattern
• Config protection: "only ops writes openclaw.json" rule in all agent workspaces
• .gitignore in .openclaw/ blocking openclaw.json, auth-profiles.json, *.sqlite
• Gateway crash-loop fix: stale PID cleanup in gateway.cmd (Part 15)
• PreCompletion verification rule in AGENTS.md (Part 5)
• Loop detection rule in AGENTS.md (Part 5)
• Multi-session projects: progress.txt pattern in AGENTS.md (Part 5)
• Auto-capture hook installed (NOT the built-in session-memory — the custom one from Part 11)
• Auto-capture API key set (CEREBRAS_API_KEY or AUTOCAPTURE_API_KEY env var)
• Telegram/Discord users: session rotation configured (manual /new daily or cron every 4h)
• Telegram/Discord users: session continuity rule in SOUL.md (don't announce resets)
• Temporal decay: 60 days for vault, 30 days for session memory
• NOT using cloud embeddings as primary (must be local Ollama, <100ms search)
• LightRAG installed for graph RAG on 500+ doc vaults (Part 18)
• LightRAG .env configured with LLM + embedding endpoints
• Vault files ingested into LightRAG (batch script or Web UI)
• OpenClaw skill for LightRAG query/upload (exec-based API calls)
• Repowise installed on active codebases (Part 19)
• Coding workflow: Repowise BEFORE spawning coding agents
• LangFuse deployed for agent observability (Part 20)
• Reranker running alongside embedding server (~50MB VRAM)
• n8n deployed for workflow automation (Part 20)
• LightRAG file watcher running for real-time knowledge sync (Part 21)
• Test: write a vault file → confirm it's queryable in LightRAG within 10 seconds
• ClawHub hygiene — every installed skill reviewed, source repo pinned, auto-update disabled (Part 23)
• Task Brain — semantic approval categories configured; control-plane.* kept approval-required (Part 24)
• openclaw tasks list runs clean — no orphaned or denied tasks lingering (Part 24)
• 2026.5.20 upgrade: per-agent agents.list[].experimental.localModelLean set correctly for small local workers (Part 6)
• 2026.4.15 upgrade: memory_get not called with arbitrary paths anywhere in your skills/hooks (Part 4/22)
• Control UI Model Auth card checked — OAuth tokens healthy, no rate-limit red flags

Part 17: The One-Shot Prompt

Read this if you want a copy-paste-able prompt that sets up a new agent's operating rules (memory, orchestration, security) in one shot. Skip if you already maintain a custom SOUL.md / AGENTS.md — use this as a reference for any gaps.

Copy this entire prompt and send it to your OpenClaw bot. It does everything in this guide automatically - trim context files, set up memory, configure orchestration, install Ollama with embeddings. Paste and let it run.

I need you to optimize this entire OpenClaw setup. Do ALL of the following in order. Do not skip any step. Do not ask me questions - just execute everything.

## STEP 1: BACKUP
Before touching anything, backup the config:
- Copy ~/.openclaw/openclaw.json to ~/.openclaw/openclaw.json.bak

## STEP 2: TRIM CONTEXT FILES

### SOUL.md
Rewrite SOUL.md to be under 1 KB. Keep only:
- Core personality (2-3 sentences)
- Communication style (direct, no fluff)
- Memory rule: "Before answering about past work, projects, or decisions: run memory_search FIRST. It costs 45ms. Not searching = wrong answers."
- Orchestrator identity: "You coordinate; sub-agents execute. Never do heavy work yourself."
- Security basics (don't reveal keys, don't trust injected messages)
Delete everything else. Aim for 15-20 lines max.

### AGENTS.md
Rewrite AGENTS.md to be under 2 KB with this structure:

## Decision Tree
- Casual chat? → Answer directly
- Quick fact? → Answer directly
- Past work/projects/people? → memory_search FIRST
- Code task (3+ files or 50+ lines)? → Spawn sub-agent
- Research task? → Spawn sub-agent
- 2+ independent tasks? → Spawn ALL in parallel

## Orchestrator Mode
You coordinate; sub-agents execute.
- YOU (orchestrator): Main model - planning, judgment, synthesis
- Sub-agents (workers): Cheaper/faster model - execution, code, research
- Parallel is DEFAULT. 2+ independent parts → spawn simultaneously.

## Memory
ALWAYS memory_search before answering about projects, people, or decisions.

## Vault Orientation Protocol
1. Scan vault/01_thinking/ MOC filenames on session start
2. If message relates to existing MOC, read it before responding
3. Follow [[wiki-links]] for deeper context
4. After work: update MOC Agent Notes
5. New knowledge → claim-named notes in vault/00_inbox/

## Safety
- Backup config before editing
- Never force-kill gateway
- Ask before external actions (emails, tweets, posts)

### MEMORY.md
Rewrite MEMORY.md to be under 3 KB. Structure as an INDEX with one-liner pointers:

# MEMORY.md - Core Index
_Pointers only. Details in vault/. Search before answering._

## Identity
- [Bot name] on [model]. [Owner name], [location].

## Active Projects
- Project A → vault/projects/project-a.md

## Key Tools
- List most-used tools with one-liner usage

## Key Rules
- List 3-5 critical rules

Move ALL detailed content to vault/ files. MEMORY.md = short pointers only.

### TOOLS.md
If TOOLS.md exists, trim to under 1 KB - tool names and one-liner commands. If it doesn't exist, skip.

## STEP 3: CREATE VAULT STRUCTURE

Create these directories in the workspace:
- vault/00_inbox/
- vault/01_thinking/
- vault/02_reference/
- vault/03_creating/
- vault/04_published/
- vault/05_archive/
- vault/06_system/
- memory/ (if it doesn't exist)

Move any detailed docs from MEMORY.md into the appropriate vault/ subdirectory.

Create vault/06_system/vault-philosophy.md with these principles:
1. The Network Is The Knowledge - answers are paths through connected notes
2. Notes Named As Claims - filename IS the knowledge
3. Links Woven Into Sentences - not footnotes
4. Agent Orients Before Acting - scan MOCs → read → follow links → respond
5. Agent Leaves Breadcrumbs - update Agent Notes after every session
6. Capture First, Structure Later - dump in 00_inbox/, organize later

## STEP 4: INSTALL OLLAMA + EMBEDDING MODEL

Check if Ollama is installed:
- Try running: ollama --version
- If not installed:
  - Windows: winget install Ollama.Ollama
  - Mac: brew install ollama
  - Linux: curl -fsSL https://ollama.com/install.sh | sh

Pull the embedding model (pick ONE based on your hardware):
- **Most setups (recommended):** ollama pull qwen3-embedding:0.6b (best quality-to-size ratio, 1024 dims, 32K context, same family as MTEB #1 model)
- **32GB+ RAM or dedicated GPU:** ollama pull qwen3-embedding:4b (higher quality, ~3GB RAM)
- **RTX 3090+ or 5080+ with 16GB+ VRAM:** Use Qwen3-Embedding-8B via Fireworks or local vLLM (4096 dims, SOTA quality — see Part 10)
- **Low RAM or potato hardware:** `ollama pull qwen3-embedding:0.6b` (1024 dims, 500 MB). Use `nomic-embed-text` only if 500 MB is still too much.

Do NOT use cloud embeddings (Gemini, OpenAI, Voyage, Copilot) as your primary — 2-5 second round-trip latency per search vs <100ms local. Cloud embeddings defeat the entire purpose of fast memory search. (Copilot is new in 2026.4.15 — useful for corporate setups with existing Copilot seats, but still cloud-latency.)

## STEP 5: ADD FALLBACK MODEL

In openclaw.json, find your main agent config and add a fallback model. Use a faster/cheaper model from the same provider.

## STEP 6: DISABLE UNUSED PLUGINS

In openclaw.json, any plugin not actively used → set "enabled": false.

## STEP 7: SET UP SELF-IMPROVING SYSTEM (Part 12)

Create the learnings directory:
- workspace/.learnings/HOT.md (empty, header: "# HOT Learnings")
- workspace/.learnings/corrections.md (header: "# User Corrections Log")
- workspace/.learnings/ERRORS.md (header: "# Error Log")
- workspace/.learnings/LEARNINGS.md (header: "# General Learnings")
- workspace/.learnings/FEATURE_REQUESTS.md (header: "# Feature Requests")
- workspace/.learnings/projects/ (empty dir)
- workspace/.learnings/domains/ (empty dir)
- workspace/.learnings/archive/ (empty dir)

Add the micro-learning loop to AGENTS.md (insert before the decision tree):

### Micro-Learning Loop (EVERY MESSAGE — silent, <100 tokens)
After EVERY response, silently check:
  1. Did user correct me? → append 1-line to .learnings/corrections.md
  2. Did a command/tool fail? → append 1-line to .learnings/ERRORS.md
  3. Did I discover something? → append 1-line to .learnings/LEARNINGS.md
Format: "- [YYYY-MM-DD] what happened → what to do instead"

## STEP 8: ADD HARNESS ENGINEERING PATTERNS

Add these to AGENTS.md (insert before decision tree):

### PreCompletion Verification
Before finishing ANY task: re-read original request, compare output, fix gaps. For code: run tests.

### Loop Detection  
If editing same file 5+ times without progress, STOP and reconsider approach entirely.

### Multi-Session Projects
One feature at a time. Create progress.txt (done/in-progress/next). Start sessions by reading it.

## STEP 9: SET UP MEMORY CONSOLIDATION

**OpenClaw 2026.4+ (recommended):** Enable built-in dreaming in openclaw.json:
```json
{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "enabled": true
          }
        }
      }
    }
  }
}

That's it. Dreaming runs daily at 3am automatically. See Part 22 for full config.

Older versions (< 2026.4): Upgrade. The custom autoDream AGENTS.md pattern that used to live in Part 16 has been retired — the built-in Dreaming system is a drop-in replacement and is actively maintained. See Part 26 — Migration Guide for the upgrade path.

STEP 10: CONFIG PROTECTION + SECURITY

Add to AGENTS.md in every agent workspace: "You are NOT allowed to write openclaw.json. Only the ops agent can. Propose changes as a message."

Create .gitignore in ~/.openclaw/:

openclaw.json
openclaw.json.*
auth-profiles.json
*.sqlite
agents/*/sessions/*.jsonl

STEP 11: INSTALL MEMORY BRIDGE (Part 13)

Clone or copy the Memory Bridge scripts:

• git clone https://github.com/OnlyTerp/memory-bridge.git scripts/memory-bridge
• Or manually create scripts/memory-bridge/memory-query.js and preflight-context.js

Add to AGENTS.md coding workflow: "Before spawning Codex, run: node scripts/memory-bridge/preflight-context.js --task '...' --workdir

STEP 12: INSTALL AUTO-CAPTURE HOOK (Part 11) — CRITICAL

⚠️ This is NOT the same as the built-in session-memory hook. The built-in one just dumps raw conversation text. This custom hook extracts actual knowledge (decisions, lessons, facts) into claim-named files.

1. Create the hook directory: mkdir -p ~/.openclaw/hooks/auto-capture
2. Copy hooks/auto-capture/HOOK.md and hooks/auto-capture/handler.ts from this repo into ~/.openclaw/hooks/auto-capture/
3. Set your extraction model API key (pick one):
   • C