Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix feat(workspace): Increase AGENTS.md/SOUL.md context file size limits (4KB/3KB too restrictive for complex agent configurations) [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#58031•Fetched 2026-04-08 01:54:42
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Author
gasvngasvn
Participants
gasvngasvn

Root Cause

These files contain:

  • Sub-agent coordination rules (threshold: when to spawn vs inline)
  • Memory architecture (which files serve which purpose)
  • Safety rules (immutable sections)
  • Pipeline-specific guards and anti-patterns

Compressing this guidance causes agents to miss operational rules, leading to coordination errors and context bloat in main sessions.

RAW_BUFFERClick to expand / collapse

Problem

When operating autonomous research agents with complex pipelines, the 4KB limit for AGENTS.md and 3KB limit for SOUL.md become restrictive.

Current state (monitored over multiple sessions):

  • AGENTS.md: 3,934 / 4,000 bytes (98%) — cannot add any new operational guidance
  • SOUL.md: 2,853 / 3,000 bytes (95%) — near limit

As agents evolve their operating rules (adding new pipeline stages, safety guards, sub-agent coordination patterns), these limits force compression of important guidance or prevent adding new content entirely.

Proposed Change

Increase default limits:

  • AGENTS.md: 4KB → 8KB (or at minimum 6KB)
  • SOUL.md: 3KB → 5KB

Why This Matters

These files contain:

  • Sub-agent coordination rules (threshold: when to spawn vs inline)
  • Memory architecture (which files serve which purpose)
  • Safety rules (immutable sections)
  • Pipeline-specific guards and anti-patterns

Compressing this guidance causes agents to miss operational rules, leading to coordination errors and context bloat in main sessions.

Alternative

If increasing hard limits isn't feasible, consider supporting AGENTS.md.d/ directory-style partitioning (similar to how memory/*.md works for MEMORY.md overflow).

Environment

  • MacOS Darwin 25.2.0 arm64
  • OpenClaw agent runtime (main session)
  • Observed over multiple weeks of autonomous operation

extent analysis

Fix Plan

To address the issue of restrictive file size limits for AGENTS.md and SOUL.md, we will increase the default limits and provide an alternative solution for partitioning the files.

Increasing Default Limits

We will update the configuration to increase the limits:

  • AGENTS.md: 4KB → 8KB
  • SOUL.md: 3KB → 5KB

Example configuration update:

# config.py
AGENT_MD_LIMIT = 8192  # Increased from 4096
SOUL_MD_LIMIT = 5120  # Increased from 3000

Alternative: Partitioning Files

If increasing hard limits isn't feasible, we can support partitioning the files using a directory-style approach. We will create a new directory AGENTS.md.d/ to store additional guidance files.

Example directory structure:

AGENTS.md
AGENTS.md.d/
├── sub-agent-coordination.md
├── memory-architecture.md
├── safety-rules.md

We will update the agent runtime to read guidance from both the main AGENTS.md file and the partitioned files in AGENTS.md.d/.

Example code snippet:

# agent_runtime.py
import os

def load_guidance(agent_dir):
    guidance = {}
    # Load main AGENTS.md file
    with open(os.path.join(agent_dir, 'AGENTS.md'), 'r') as f:
        guidance.update(parse_markdown(f.read()))
    
    # Load partitioned files in AGENTS.md.d/
    guidance_dir = os.path.join(agent_dir, 'AGENTS.md.d')
    if os.path.exists(guidance_dir):
        for file in os.listdir(guidance_dir):
            if file.endswith('.md'):
                with open(os.path.join(guidance_dir, file), 'r') as f:
                    guidance.update(parse_markdown(f.read()))
    return guidance

Verification

To verify the fix, we will:

  • Check the file sizes of AGENTS.md and SOUL.md to ensure they are within the new limits.
  • Test the agent runtime with the updated configuration and partitioned files to ensure guidance is loaded correctly.

Extra Tips

  • Monitor file sizes and adjust limits as needed to prevent future issues.
  • Consider implementing a warning system to notify developers when file sizes approach the limits.
  • Document the new partitioning approach and updated limits in the agent runtime documentation.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#model download#tokenizer error#prompt formatting#chain error#conversation history

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix feat(workspace): Increase AGENTS.md/SOUL.md context file size limits (4KB/3KB too restrictive for complex agent configurations) [1 participants]