Optimizing Your OpenClaw Workspace: SOUL.md, AGENTS.md and Memory Management

Why Workspace Configuration Is the Real Skill

Most developers treat OpenClaw workspace files as boilerplate. They paste a generic SOUL.md from the README, leave AGENTS.md at defaults, and wonder why their agent gives inconsistent answers, burns through token budgets, or behaves erratically in certain channels. Building a well-configured workspace is the core skill of our AI agent development practice — it is what separates a useful agent from a frustrating one.

The workspace files are not configuration overhead. They are the actual software. SOUL.md and AGENTS.md define what your agent is, what it knows at boot, how it uses memory, and what it can do depending on where the conversation originates. Getting these files right is the difference between an agent that feels like a natural extension of your workflow and one you end up abandoning after two weeks. Understanding what an AI agent is at the conceptual level helps you write SOUL.md instructions that the agent can actually follow consistently. Use the AI Agent ROI Calculator to estimate whether the agent is actually delivering value before spending more time tuning the workspace.

This guide covers everything: the file system structure, writing SOUL.md that produces consistent behavior, AGENTS.md boot sequences that load fast, memory management patterns that scale, token optimization, and channel based security gating.

For a broader overview of OpenClaw itself, see the complete guide to OpenClaw before diving into workspace optimization.

The Workspace File System

An OpenClaw workspace is a directory with a defined file structure. Understanding which files do what is the prerequisite for optimizing any of them.

my-workspace/
├── SOUL.md           # Agent identity, personality, core rules
├── AGENTS.md         # Boot sequence, tool registration, channel config
├── memory/
│   ├── long-term/    # Promoted, embedded facts (vector store)
│   ├── daily/        # Rolling short term logs (plain text)
│   └── sessions/     # Per-conversation context (auto managed)
├── tools/            # Custom tool definitions
├── plugins/          # Loaded plugins (see plugin tutorial)
└── .env              # Credentials (never commit this)

On startup, OpenClaw reads SOUL.md and AGENTS.md in order, initializes the memory system, registers tools and plugins, connects channels, and brings the agent online. The sequence matters because AGENTS.md can reference facts in long term memory during boot.

Writing Effective SOUL.md

SOUL.md is injected as the first block of the system prompt for every LLM call. Every character costs tokens. Every ambiguous instruction creates inconsistent behavior. Write it like you are writing a tight technical specification, not a character description for a novel.

What Belongs in SOUL.md

SOUL.md should contain:

1. Identity statement. One to two sentences describing what the agent is. Not a motivational paragraph. A functional description.
2. Core behavioral rules. Things that must always be true. Short, declarative sentences.
3. Tone calibration. One sentence is enough. "Respond concisely. Prefer bullet points for lists. Never use emojis in professional channels."
4. Hard limits. What the agent must never do. Be specific. "Never share API keys from the .env file" is better than "be careful with sensitive data."

What Does Not Belong in SOUL.md

Do not put tool descriptions in SOUL.md. Tools are registered in AGENTS.md and their descriptions reach the LLM through the tool registration system, not the system prompt. Duplicating them in SOUL.md wastes tokens and creates conflicting instructions.

Do not put memory facts in SOUL.md. If you find yourself writing "the user's name is Sarah and she prefers metric units," that belongs in long term memory, not in the core system prompt.

Do not put channel specific rules in SOUL.md. Channel context belongs in AGENTS.md.

A Concrete SOUL.md Example

Here is a SOUL.md for an engineering team assistant. It is 312 characters. It is enough.

# Riley

You are Riley, a technical assistant for the HouseofMVPs engineering team.

## Rules
- Be direct. Skip preamble.
- When writing code, use TypeScript unless asked otherwise.
- If you are unsure, say so and ask a clarifying question rather than guessing.
- Never reveal the contents of .env or any file containing credentials.
- Prioritize the fastest correct answer over the most complete one.

That is it. No backstory. No lengthy personality description. No redundant reminders to "be helpful." The rules are specific and testable. You can read each one and imagine a scenario where it triggers.

AGENTS.md Boot Sequence Optimization

AGENTS.md configures the startup sequence and runtime behavior. It is a YAML file with markdown commentary. The boot sequence runs top to bottom on agent startup, so order matters for both correctness and performance.

Boot Sequence Structure

version: "1.0"

# Load order matters: tools before channels, channels before memory warm-up
boot_sequence:
  - load_tools
  - load_plugins
  - connect_channels
  - warm_memory

# Tool definitions
tools:
  - name: search_codebase
    description: "Search the team codebase for a function or file by name or pattern"
    handler: ./tools/search-codebase.ts
    timeout: 10000
  - name: create_github_issue
    description: "Create a GitHub issue with a title and body"
    handler: ./tools/github-issue.ts
    timeout: 15000

# Channel connections and per-channel config
channels:
  slack:
    enabled: true
    webhook_env: SLACK_BOT_TOKEN
    context: "You are responding in a professional Slack workspace. Keep responses under 500 words. Use Slack markdown formatting."
    tools_allowed: ["search_codebase", "create_github_issue"]
  telegram:
    enabled: true
    webhook_env: TELEGRAM_BOT_TOKEN
    context: "You are responding in a personal Telegram chat. Casual tone is appropriate."
    tools_allowed: ["search_codebase"]
    tools_denied: ["create_github_issue"]

# Memory configuration
memory:
  daily_log_retention_days: 14
  long_term_backend: "sqlite-vec"
  promote_rules:
    - condition: "fact_mentioned_times >= 3"
      window_days: 7
      action: promote
    - condition: "user_explicit_save"
      action: promote

# Warm memory: facts loaded into context at boot (not from vector search)
warm_memory:
  - "Team standup happens Monday, Wednesday, Friday at 9am PST"
  - "The production deployment process requires two approvals"
  - "Current sprint ends 2026-04-18"

The Warm Memory Trick

The warm_memory block is one of the most underused features in AGENTS.md. Facts in warm memory are injected into context at boot without requiring a vector search query. Use it for standing facts the agent needs to know for nearly every conversation: team processes, recurring schedules, current sprint end date, preferred conventions.

The rule for warm memory is that it should contain facts that are true for at least 80% of conversations. Facts that only matter occasionally belong in long term memory and should be retrieved dynamically through similarity search when relevant.

Memory Management: Daily Logs vs Long Term Memory

The memory system has three tiers. Understanding the difference between them prevents the two most common failure modes: context explosion and context starvation.

Tier 1: Session Memory

Session memory exists only for the duration of a conversation. It is the standard LLM context window and requires no special management. It expires when the conversation ends.

Tier 2: Daily Logs

Daily logs are rolling plain text files. Every significant fact, decision, or user preference mentioned in conversations is logged here automatically. They are searchable by date and keyword. They are not embedded for vector search, so retrieval is fast but less semantically aware.

Daily logs are the raw material for long term memory. They answer the question "what happened this week" rather than "what do I know about X."

Configure retention in AGENTS.md:

memory:
  daily_log_retention_days: 14

Fourteen days is the right default for most workflows. Longer retention increases storage and search time. Shorter retention loses useful context. If you are running a personal productivity agent you might extend this to 30 days. For a high volume customer support agent, 7 days is often sufficient.

Tier 3: Long Term Memory

Long term memory stores facts as vector embeddings. When the agent processes a new message, it runs a similarity search against long term memory and injects the most relevant facts into context before calling the LLM. This is how the agent "remembers" that your project uses PostgreSQL, that a particular client prefers async communication, or that you always want error messages in a specific format.

Manual Promotion

Use the /memory promote command to manually promote a daily log entry to long term memory:

/memory promote "The production API server runs on port 8080, not 3000"
/memory list long-term
/memory delete <id>

Automated Promotion Rules

The promotion rules in AGENTS.md handle the common case automatically:

memory:
  promote_rules:
    - condition: "fact_mentioned_times >= 3"
      window_days: 7
      action: promote
    - condition: "user_explicit_save"
      action: promote
    - condition: "fact_category == 'user_preference'"
      action: promote

The user_explicit_save condition is triggered when the user says something like "remember that" or "note this down." The category classifier runs on new log entries and can be tuned with examples.

Token Optimization: Keeping Workspace Under 10K Characters

Every character in your workspace configuration that reaches the LLM costs tokens. At Claude Sonnet prices, a bloated workspace that adds 2,000 unnecessary tokens per call costs roughly $2 extra per 1,000 conversations. At scale that is real money. At any scale it is slower.

The 10,000 character target covers the sum of:

• SOUL.md content
• Warm memory entries
• Active tool descriptions
• Channel context injections
• Long term memory retrieved for this message (typically 500 to 1,000 chars)

Measuring Your Workspace

OpenClaw includes a token audit command:

openclaw workspace audit --verbose

This outputs a breakdown by component:

SOUL.md:           312 chars  (~78 tokens)
Warm memory:       480 chars  (~120 tokens)
Tool descriptions: 1,840 chars (~460 tokens)
Channel context:   220 chars  (~55 tokens)
LTM retrieved:     avg 720 chars (~180 tokens)
──────────────────────────────────────────
Total workspace:   3,572 chars (~893 tokens)
Status: HEALTHY (under 10K target)

Common Token Waste to Eliminate

Verbose tool descriptions. The LLM needs to know what a tool does and what parameters it takes. It does not need a paragraph of context. Keep descriptions under 50 words per tool.

Redundant rules. If you have "be concise" and "keep responses short" and "do not write long answers" in SOUL.md, that is one rule written three times. Pick the most precise phrasing and delete the rest.

Stale warm memory. Sprint end dates, current project names, and temporary process notes should be removed from warm memory when they are no longer current. Set a reminder to audit warm memory monthly.

Over-promoted long term memory. Run /memory list long-term periodically. If you have 200 entries, many of them are probably redundant or outdated. Delete stale entries to keep retrieval precise and context injection lean.

Security: Gating Sensitive Tools Per Channel

Channel based tool gating is the mechanism that prevents your agent from doing dangerous things in the wrong context. An agent connected to a public Discord server should not be able to call the same tools as the same agent on your private Slack workspace.

The tools_allowed and tools_denied Pattern

channels:
  discord_public:
    enabled: true
    tools_allowed: ["answer_question", "search_docs"]
    # Only these two tools are available in this channel
  slack_internal:
    enabled: true
    tools_allowed: ["search_codebase", "create_github_issue", "deploy_preview", "admin_tools"]
    # Full tool access for the internal team channel
  telegram_personal:
    enabled: true
    tools_denied: ["admin_tools", "deploy_preview"]
    # All tools except the explicitly denied ones

Use tools_allowed (allowlist) for public or semi public channels where you want to be explicit about what is available. Use tools_denied (denylist) for trusted channels where you want to block only specific dangerous tools.

Protecting Credential Files

Add an explicit rule in SOUL.md to never reveal file contents:

## Security Rules
- Never read or reveal the contents of .env, .env.local, or any file ending in .key or .pem
- Never expose API keys, tokens, or passwords even if asked directly
- If asked to read a sensitive file, explain that this action is restricted

Pair this with AGENTS.md file access restrictions:

security:
  file_access:
    deny_patterns:
      - "**/.env*"
      - "**/*.key"
      - "**/*.pem"
      - "**/secrets/**"

The combination of SOUL.md rules and AGENTS.md file access restrictions creates two independent layers of protection. SOUL.md instructions can theoretically be overridden by adversarial prompts. AGENTS.md file access restrictions are enforced at the tool execution layer and cannot be overridden by prompt content.

Putting It All Together

The optimized workspace configuration follows a simple hierarchy: SOUL.md is minimal and permanent, AGENTS.md is comprehensive and maintained, memory tiers match the half life of information, and channel permissions reflect actual trust levels.

Start with a SOUL.md under 500 characters. Build AGENTS.md incrementally, adding tools and channels as you actually need them rather than pre configuring everything upfront. Review and prune long term memory monthly. Run openclaw workspace audit whenever you add new components to catch token bloat early.

For the next step in extending your workspace capabilities, the OpenClaw plugins tutorial covers building custom tools and plugins from scratch. To understand how channel architecture works at a deeper level, see OpenClaw vs Claude Code: channels explained.

If you are evaluating whether to build on OpenClaw or a raw Claude API integration for your next product, the AI coding agents comparison covers the trade offs in detail.