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:

```python
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
```markdown
## Summary
[What changed]

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

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

### Debug Reports
```markdown
## 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