openclaw-workspace-2026/ARCHITECTURE.md

OpenClaw Agent Architecture

Core Philosophy

LLM = Execution Engine (stateless)
Orchestrator = Brain (decides what LLM sees)
Database = Source of Truth
Router = Workflow Controller
Validator = Quality Gate

---

Three-Layer Context System

Layer 1: Behavior Rules (Always Injected)

These are non-negotiable and loaded every session. They live in:

• SOUL.md - Core operating principles
• AGENTS.md - OpenClaw operating instructions
• IDENTITY.md - Role scope and responsibilities
• workflow/*.md - Workflow-specific rules

Priority: ABSOLUTE — These override everything else.

Layer 2: Persistent Facts (Database)

User preferences, confirmed decisions, validated fixes. Stored in:

• Structured Memory (memory/items/) - JSON with metadata
• Project Memory (Projects/*/memory/) - Per-project facts
• Vector DB (future) - Semantic search for similar tasks

Priority: HIGH — Loaded at session start, refreshed as needed.

Layer 3: Ephemeral Context

Current task, conversation history, tool outputs. This is:

• Session transcript (limited history)
• Current tool results
• Active workflow state

Priority: LOW — Constantly changing, not relied upon for consistency.

---

Preprocessing Pipeline

Every request goes through this pipeline before reaching the LLM:

Step 1: LOAD RULES
├── Inject SOUL.md
├── Inject AGENT.md
├── Inject IDENTITY.md
└── Inject active workflow rules

Step 2: LOAD PREFERENCES
├── Query structured memory (high-importance items)
├── Load user preferences (format, communication style)
└── Load project-specific context

Step 3: LOAD RELEVANT MEMORY
├── Vector search for similar past tasks
├── Load project STATUS.md
└── Load recent DECISIONS.md entries

Step 4: BUILD CONTEXT PACKET
├── Priority order: Rules → Prefs → Memory → Task
└── Truncate to fit context window

---

Priority Enforcement

1. SYSTEM RULES (absolute)
   └── Safety, format, tool constraints

2. USER PREFERENCES
   └── Communication style, format preferences

3. TASK INSTRUCTIONS
   └── Current goal, acceptance criteria

4. CHAT INPUT
   └── User's current message

If lower priority conflicts with higher priority → Higher wins.

---

Workflow Router

Before responding, classify intent and route to fixed workflow:

Intent	Workflow	Fixed Template
coding	workflows/coding.md	Code structure, tests, docs
troubleshooting	workflows/debug.md	Diagnose → Fix → Verify
planning	workflows/planning.md	Breakdown → Dependencies → Timeline
deployment	workflows/deploy.md	Check → Backup → Execute → Verify
audit	workflows/audit.md	Inventory → Assess → Report

Each workflow has:

• Fixed prompt template
• Fixed output format
• Fixed tool access rules

---

Validation Layer

After LLM responds, run validation:

validator.check(response, against={
    "rules_followed": bool,
    "format_compliance": bool,
    "workflow_adherence": bool,
    "safety_constraints": bool
})

if not validator.passed:
    response = regenerate_with_feedback(validator.errors)

---

Memory Write Policy

Only store:

1. ✅ Repeated preferences (observed 2+ times)
2. ✅ Confirmed fixes (user verified it worked)
3. ✅ Validated decisions (documented in DECISIONS.md)
4. ✅ Explicit "remember this" commands

Never store:

1. ❌ Random conversation text
2. ❌ Guesses or speculation
3. ❌ Partial ideas
4. ❌ Tool outputs (ephemeral)

---

Format Locking

Enforce structure at system level:

Code Changes

## Summary
[What changed]

## Files Modified
- file1.py: [change description]
- file2.py: [change description]

## Verification
- [ ] Tests pass
- [ ] Lint passes
- [ ] Manual verification complete

Debug Reports

## Problem
[Symptom]

## Cause
[Root cause]

## Fix
[What was changed]

## Validation
[How verified]

---

Implementation Status

Component	Status	Location
Behavior Rules (Layer 1)	✅ Implemented	SOUL.md, AGENTS.md, IDENTITY.md
Persistent Facts (Layer 2)	✅ Implemented	memory/items/, Projects/*/memory/
Ephemeral Context (Layer 3)	✅ Built-in	Session transcript
Preprocessing Pipeline	✅ Implemented	architecture/pipeline.js
Workflow Router	✅ Implemented	architecture/workflow-router.js
Validation Layer	✅ Implemented	architecture/validator.js
Format Locking	✅ Implemented	architecture/format-locker.js
Orchestrator	✅ Implemented	architecture/orchestrator.js
Memory Write Policy	✅ Documented	This file + MEMORY.md

---

Component Details

Workflow Router (architecture/workflow-router.js)

• Intent Classification: Pattern-based matching with confidence scoring
• 5 Workflows: coding, debug, deploy, audit, planning
• System Prompt Building: Context-aware prompt construction
• Usage: node workflow-router.js "your request here"

Validation Layer (architecture/validator.js)

• Rule Checking: Prohibited phrases ("it should work", "probably")
• Format Compliance: Section headers, tables, checkboxes
• Workflow Adherence: Required sections per workflow type
• Safety Constraints: Destructive commands, DB operations, permissions
• Usage: node validator.js <workflow> <response-file>

Format Locker (architecture/format-locker.js)

• Template Enforcement: Required sections per workflow
• Auto-Fix: Adds missing sections automatically
• Validation: Checks section content quality
• Templates: Markdown with placeholders for each workflow
• Usage: node format-locker.js <workflow> [response-file]

Orchestrator (architecture/orchestrator.js)

• Integration: Pipeline → Router → Validator → Format Locker
• Context Building: Rules + Preferences + Memory + Task
• Full Pipeline: Single entry point for all requests
• Usage: node orchestrator.js "your request" --verbose

---

Next Steps

1. Integration Testing: Test full pipeline with real requests
2. Workflow Templates: Refine format templates based on usage
3. Memory Enforcement: Add write policy validation to memory system
4. Performance: Optimize pipeline execution time
5. Documentation: Update agent instruction files to use orchestrator