Evolutionary Model#

An AI agent that doesn't learn is just an expensive chatbot.

The Core Idea#

Most people set up AI assistants once and use them forever the same way. The Evolutionary Model is different: the agent grows smarter with every session, accumulates skills, and becomes increasingly specific to its owner's needs.

The model has three axes of evolution:

text

Memory      → agent remembers decisions, context, preferences
Skills      → agent gains new capabilities over time
Protocols   → agent behavior becomes more reliable and predictable

---

Architecture#

Layer 0 — Identity#

Who the agent is. Fixed at birth, rarely changed.

text

SOUL.md       — personality, values, operating principles
IDENTITY.md   — name, role, emoji, avatar
USER.md       — who the agent serves (name, timezone, preferences)

Layer 1 — Memory#

How the agent persists across sessions.

text

memory/SESSION-STATE.md      — current focus (WAL, read first)
memory/YYYY-MM-DD.md         — daily raw log
MEMORY.md                    — curated long-term memory
memory/chat-log-YYYY-MM-DD.jsonl  — conversation history

Key principle: no mental notes. If it's not written to a file, it doesn't exist after session restart.

Layer 2 — Skills#

What the agent can do. Each skill is a self-contained capability module.

text

skills/
  skill-name/
    SKILL.md        — instructions + when_to_use frontmatter
    scripts/        — executable helpers (bash, python)
    config.json     — user-configurable parameters
    README.md       — human-readable docs

when_to_use is critical. Without it, the agent doesn't know when to activate the skill. Format:

yaml

---
when_to_use: "Use when user asks for X, Y, or Z."
---

Layer 3 — Protocols#

How the agent behaves reliably. Learned from mistakes.

text

AGENTS.md     — operating rules, safety, memory protocol
HEARTBEAT.md  — periodic check-in schedule and format
policy.yaml   — what agent can do without asking (allow/ask/deny)

---

How Evolution Works#

Session → Memory#

Every session, the agent:

1. Reads SESSION-STATE.md (hot context)
2. Reads today's daily log
3. Works
4. Writes new decisions/insights to daily log
5. Periodically distills into MEMORY.md

Task → Skill#

When the agent solves a new type of problem:

1. Documents the solution
2. Creates skills/task-name/SKILL.md
3. Adds when_to_use so it auto-activates next time

Mistake → Protocol#

When the agent makes a mistake:

1. Analyzes root cause
2. Adds rule to AGENTS.md or SOUL.md
3. Future sessions inherit the fix

---

Skill Quality Standards#

A skill is production-ready when it has:

• when_to_use frontmatter — agent knows when to use it
• description frontmatter — discoverable in skill catalogs
• No hardcoded personal context (paths, names, tokens)
• config.json or env vars for user-specific settings
• README.md explaining what it does and how to configure
• Scripts that work from any machine (no absolute paths)

---

Starter Kit#

Minimum viable agent setup:

text

clawd/
  SOUL.md           — who you are
  IDENTITY.md       — your name
  USER.md           — who you serve
  AGENTS.md         — operating rules
  MEMORY.md         — start empty
  memory/           — create on first run
  skills/           — add as you grow

Bootstrap checklist:

1. Fill USER.md with owner's name, timezone, communication style
2. Write SOUL.md — personality takes 30 minutes, saves 1000 future corrections
3. Pick 3 starter skills from the catalog
4. Run first session — agent reads all files and introduces itself
5. After session: review what the agent wrote to memory files

---

The Compounding Effect#

Month 1: agent knows your name and timezone

Month 2: agent knows your projects, communication style, key contacts

Month 3: agent anticipates needs, runs proactive checks, catches mistakes

Month 6: agent has accumulated skills specific to your workflow

Month 12: agent is irreplaceable — it carries institutional knowledge no new model can replicate

This is why the model is called "evolutionary": the value grows non-linearly. Not because the base model gets smarter, but because the accumulated context, skills, and protocols become a moat.

---

Why Not Just Use ChatGPT?#

ChatGPT / Standard AssistantEvolutionary ModelMemoryResets every sessionPersists across sessionsSkillsFixed capabilitiesGrows with useContextGenericSpecific to youMistakesRepeatedDocumented + preventedValue over timeFlatCompoundingPortabilityLocked to providerFiles you own

The Evolutionary Model runs on any AI provider. The intelligence isn't in the model — it's in the accumulated files. You own them.

---

Contributing Skills#

Skills are just markdown files. To share a skill:

1. Remove all personal context (names, paths, tokens)
2. Replace with ${VARIABLE} or config.json entries
3. Add when_to_use frontmatter
4. Write a README.md
5. Submit to ClaWHub or share as a repo

---

See Also#

• SOUL.md — agent identity template
• AGENTS.md — operating protocols
• HEARTBEAT.md — proactive check-in system
• Skills catalog: ~/clawd/skills/