238 lines
6.4 KiB
Markdown
238 lines
6.4 KiB
Markdown
# 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) | ✅ 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
|