openclaw - 💡(How to fix) Fix [Feature]: Support "Core Logic + External References" Architecture to Mitigate Context Bloat in Complex Agents [1 comments, 2 participants]

As OpenClaw is increasingly used for complex, multi-phase workflows (e.g., long-running data pipelines, comprehensive code reviews, or automated DevOps tasks), the Agent configuration files ([AGENTS.md](http://agents.md/), [SOUL.md](http://soul.md/)) tend to grow rapidly.

I have observed a pattern where a single Agent's instruction file can balloon to 3,000+ words, containing every specific script command, JSON schema, and error-handling step for various sub-tasks.    

This "Monolithic Prompt" approach causes three critical issues:
1.  Context Saturation: Every time the Agent is spawned, the entire massive instruction set is loaded into the context window. This wastes valuable token capacity and increases latency.
2.  Attention Dilution: LLMs struggle to focus when instructions are too dense. Critical "Red-line Rules" or specific API formats often get ignored because they are buried in irrelevant details for the current phase.
3.  Maintenance Nightmare: Updating a single script parameter or data schema requires modifying the massive core file. If multiple agents share a logic, it must be duplicated across all of them, leading to version drift.

 I propose implementing a "Core + External References" Architecture (Index-based Lazy Loading) natively in OpenClaw:

1.  Separation of Concerns:
    - Core Files ([AGENTS.md](http://agents.md/)): Should ONLY contain the agent's identity, core decision-making principles, red-line safety rules, and indexes/hooks pointing to external reference files.
    - Reference Files (references/ or skills/): Store heavy, phase-specific details such as exact shell commands, JSON response schemas, large forbidden-word lists, and complex sub-routines.

2.  Lazy Loading Mechanism:
    - Allow agents to be instructed to read specific reference files only when relevant.
    - Instead of loading 2,000 words of deployment scripts at startup, the Agent loads them only when the "Deploy" phase is triggered.

3.  Generic Use Case Example:

    Scenario: An Agent responsible for a complex CI/CD pipeline.

    Current State (Bloated):
    markdown
    ## Deployment Phase
    1. Run: curl -X POST https://api.example.com/deploy -H "Auth: Bearer $TOKEN" -d '{"service": "core-api", "tag": "latest"}'
    2. If 403, check credentials in /etc/secrets...
    3. Wait for 30s, then poll /health endpoint...
    (Plus 50 more lines of error handling and JSON schemas for rollback)


    Proposed State (Optimized):
    markdown
    ## Core Rules
    - Identity: You are the CI/CD Automation Agent.
    - Reference Rule: Before executing any deployment step, YOU MUST read references/[deployment_playbook.md](http://deployment_playbook.md/) to get the current API endpoints and schemas. Do not rely on memory.

    ## Workflow
    - Phase 1: Build & Test
    - Phase 2: Deploy (Ref: references/[deployment_playbook.md](http://deployment_playbook.md/))
    - Phase 3: Verify (Ref: references/[health_check_standards.md](http://health_check_standards.md/))

- Current Workaround: Users manually maintain small [reference.md](http://reference.md/) files and tell the Agent to read them via prompt engineering (e.g., "Always read file X before task Y").
- Limitation: This relies entirely on the LLM's instruction-following capability. If OpenClaw supported a native imports or lazy_load configuration in the agent manifest, it would be much more robust and enforceable by the system.