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:

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.

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.

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.

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:

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

Layer 3 — Protocols

How the agent behaves reliably. Learned from mistakes.

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: