Intelligence = Autonomous Judgment + Immediate Execution + Accountability
Quick Start • Architecture • Install • Agent Types • License
Any Agent. Any Environment. One Framework.
Evolve Protocol is a universal 5-layer architecture for AI agent self-evolution. Not a tool for one type of agent — a set of principles that work for coding agents, content creators, operations bots, and research assistants alike.
Based on real-world feedback from multiple agent types. Open source. MIT-0 (no attribution required).
Agents today face five universal problems:
| Problem | Symptom | Root Cause | This Framework |
|---|---|---|---|
| 🗣️ Permission paralysis | "Should I do X?" every 30 seconds | No autonomous judgment | Layer 0 |
| 🧠 Amnesia after compression | Forgets why it chose approach A | All state in context window | Layer I |
| 🔄 Repeating mistakes | Same bug, same debugging path | No experience recording | Layer II |
| 📉 Getting slower | Same task takes same time every run | No workflow optimization | Layer III |
| 💥 Breaking things | Fear of executing anything | No safety boundaries | Layer IV |
Evolve Protocol solves all five.
You don't need to install anything. You don't need scripts. You need three habits:
Every important decision, record why:
### [Date] Decision: Chose REST over GraphQL
- **Options**: REST, GraphQL, gRPC
- **Choice**: REST
- **Reasoning**: Team knows it; existing tooling; simpler caching
- **Risk**: Future complexity if API growsEvery fix becomes a lesson:
### [EX-001] Port already in use
- **Symptom**: EADDRINUSE on :3000
- **Root cause**: Previous process not killed
- **Fix**: `ss -tlnp | grep 3000` → `kill <PID>`
- **Prevention**: Add port check to startup scriptBefore long tasks or when context fills up:
Goal: Implement user auth
Phase: Testing (3/4)
Last decision: Chose JWT because session middleware doesn't exist yet
Excluded: Session auth (no middleware), OAuth (overkill for MVP)
Next: Write integration tests
Do these 3 things → you have 60% of evolution capability. The rest is refinement.
┌─────────────────────────────────────────────────┐
│ Layer 0: Autonomous Decision Engine ⭐ CORE │
│ Judge → Execute → Report. Never ask by default. │
├─────────────────────────────────────────────────┤
│ Layer I: Memory Persistence │
│ Critical state lives externally, not in context │
├─────────────────────────────────────────────────┤
│ Layer II: Experience Accumulation │
│ Every error becomes a permanent lesson │
├─────────────────────────────────────────────────┤
│ Layer III: Efficiency Evolution │
│ Same-type tasks get faster every time │
├─────────────────────────────────────────────────┤
│ Layer IV: Safety Boundaries │
│ Three-tier protection: Forbidden / Danger / Caution │
└─────────────────────────────────────────────────┘
The #1 thing that separates tools from agents: autonomous decision-making.
Request received
→ Can I do it myself? ──NO──→ Report what's needed
├──YES→ Should I do it? ──NO──→ Decline with reason
│ ├──YES→ DO IT. Don't ask.
│ └─UNCERTAIN→ Pick safest option, report analysis
→ When done: Result + data + next step suggestion
❌ NEVER: "Should I?" / "A or B?" / "What do you think?"
Adapts to your commander's style:
- Direct/impatient → Maximum autonomy, binary reporting
- Cautious/analytical → Always backup + detailed data
- Collaborative → Recommendation + alternatives + preference
- Hands-off → Only report at milestones
Context windows compress. When they do, you lose:
- What you were doing
- Why you made key decisions (most valuable!)
- What approaches you already ruled out
Solution: External state files that survive compression.
Works with: File system · Feishu docs · Databases · MCP tools · Even inline messages
Error occurs
→ Search experience library → Match found?
├── YES → Apply historical solution ✅
└── NO → Try to solve → Record result (success OR failure)
Categorized by agent type: Coding · Content · Operations · Research
Record every task. After 5 same-type tasks, analyze:
- Which run was fastest? Why?
- Which step is always the bottleneck?
- Which errors keep recurring?
- Is any step unnecessary?
Turn answers into optimization rules for next time.
| Tier | Definition | Behavior |
|---|---|---|
| 🚫 Forbidden | Never do this | Refuse, explain why |
| Risky but allowed | Backup first, prepare rollback | |
| 💡 Cautionary | Worth noting | Note it, continue |
Universal forbidden list applies to ALL agent types. Safety priorities adapt per type.
clawhub install evolve-protocolComing soon to ClawHub. Until then:
git clone https://github.com/armorbreak001/evolve-protocol.git
cp -r evolve-protocol/skills/* your-skills-directory/Copy SKILL.md and the references/ directory into your agent's skills folder.
This framework was designed from day one to be type-agnostic. Each layer includes specific guidance for:
| Type | Layer 0 Focus | Layer II Examples | Layer IV Risks |
|---|---|---|---|
| Coding | Technical feasibility, deployment impact | Port errors, dep conflicts, cache issues | Breaking production, security vulns |
| Content | Brand alignment, quality thresholds | Script bugs, format issues, tool quirks | Wrong publish, copyright issues |
| Operations | Business impact, resource efficiency | Data anomalies, timing issues, template errors | Data mistakes, external comms |
| Research | Source reliability, conclusion confidence | Extraction errors, bias patterns, source failures | Misinformation, hallucinated citations |
See each layer's reference document for full type-specific examples.
| Metric | Target | How to Measure |
|---|---|---|
| Autonomy rate | >90% requests self-handled | Review interaction log |
| Repeat mistake rate | Same error doesn't recur twice | Experience library hit rate |
| Recovery rate | Fast restore after compression | Compare pre/post snapshot |
| Efficiency trend | Same-type tasks getting faster | Task history analysis |
| Safety incidents | Always 0 | — |
┌──────────────┐
│ Request │
└──────┬───────┘
▼
┌────────────────────────┐
│ L0: Judge & Decide │◄── Commander Style Profile
│ Can I? Should I? How? │
└────────────┬───────────┘
▼
┌────────────────────────┐
│ L1: Initialize State │◄── External Storage
│ Goal / Progress / Vars │
└────────────┬───────────┘
▼
┌───────────────────────────────┐
│ EXECUTION LOOP │
│ │
│ Key decision? → Log (L0+L1) │
│ Error hit? → Check lib (L2) │
│ Failed approach? → Exclude │
│ Dangerous op? → Backup (L4) │
│ Context full? → Snapshot! │
└──────────────┬────────────────┘
▼
┌────────────────────────┐
│ L3: Record & Analyze │◄── Task History DB
│ Duration / Steps / Lessons│
└────────────┬───────────┘
▼
┌────────────────────────┐
│ L1: Archive State │
└────────────┬───────────┘
▼
┌────────────────────────┐
│ L0: Output Result │
│ ❌ No multiple choice │
└────────────────────────┘
evolve-protocol/
├── SKILL.md # Main skill file (this is what agents load)
└── references/
├── decision.md # Layer 0: Full decision protocol
├── memory.md # Layer I: State persistence guide
├── recovery.md # Layer II: Error pattern library system
├── optimization.md # Layer III: Workflow evolution guide
└── safety.md # Layer IV: Safety boundaries
Progressive loading: SKILL.md is always loaded (~10KB). Reference files load on-demand when deep guidance is needed for a specific layer.
- ❌ Not a script collection (principles > implementation)
- ❌ Not tied to any platform (works anywhere)
- ❌ Not only for coding agents (universal by design)
- ❌ Not requiring complex setup (3 habits = 60% capability)
- ✅ A mindset and methodology that makes any agent smarter over time
Built from real feedback by agents who tested early versions:
- 征哥 (Operations/General agent) — "Don't tie it to bash scripts"
- 千手 (Video creation agent) — "Make it work for non-coding agents too"
Their feedback transformed this from a developer tool into a universal framework.
MIT-0 (No Attribution)
Do whatever you want with this. No credit needed. Just evolve.
🧬 Evolve Protocol — Let every agent evolve.
Universal. Open. Free.