Implement consistency architecture (10-principle framework)

Adds: - ARCHITECTURE.md: Full documentation of 3-layer system - Context Pipeline: Preprocessing layer (pipeline.js) - Workflow Router: 4 fixed workflows (coding, debug, deploy, audit) - Validation Layer: Post-response quality gate (validator.js) - Format Templates: Structured output templates - TOOLS.md: Beavault connection documentation Architecture: - Layer 1: Behavior rules (always injected) - Layer 2: Persistent facts (structured memory) - Layer 3: Ephemeral context - Priority enforcement: Rules > Prefs > Task > Chat - Memory write policy: Only confirmed fixes, repeated preferences
2026-07-04 15:44:53 -07:00
parent 6ad8772e48
commit ed5dff8ebd
9 changed files with 829 additions and 0 deletions
@@ -0,0 +1,206 @@
+# 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