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)	🔄 Partial	memory/items/, Projects/*/memory/
Ephemeral Context (Layer 3)	✅ Built-in	Session transcript
Preprocessing Pipeline	🔄 In Progress	architecture/pipeline.js
Workflow Router	❌ Not Started	workflows/
Validation Layer	❌ Not Started	architecture/validator.js
Memory Write Policy	🔄 Documented	This file + MEMORY.md
Format Locking	❌ Not Started	templates/

---

Next Steps

1. Implement preprocessing pipeline
2. Create workflow router with 5 core workflows
3. Build validation layer
4. Add format templates
5. Migrate memory system to enforce write policy