Evolutionary Model

Framework for building AI agents that evolve with their owner. Use when: setting up a new agent from scratch, onboarding a team to AI-native workflow, explai...

Security Scan

Instruction-only framework for running a persistent, file-backed agent; coherent with its purpose but it assumes the agent will read/write persistent files (in ~/clawd and memory/) even though no config paths are declared.

Purpose & Capability

The name/description (a framework for building evolving agents) matches the SKILL.md: it is documentation and policy for organizing files, memories, skills, and protocols. No binaries, installs, or credentials are requested — appropriate for a purely instructional framework.

Instruction Scope

The runtime instructions explicitly instruct creating, reading, and writing files (SOUL.md, USER.md, memory/, skills/, ~/clawd/skills/, etc.). That behavior is central to the stated purpose (persistent agent memory and skills). However, the skill metadata declares no required config paths while the instructions assume specific filesystem locations; this mismatch is worth noting because users should expect the agent to access and mutate files in the user's home or project directory.

Install Mechanism

No install spec and no code files — lowest-risk delivery model. Nothing is downloaded or written by an installer; the skill is a set of instructions only.

Credentials

No environment variables or credentials are requested. The SKILL.md recommends using config.json or env vars for individual skills, which is reasonable guidance and does not itself require credentials.

Persistence & Privilege

The skill advocates persistent state stored as files and a skills directory; it does not request 'always: true' or other elevated platform privileges. Users should recognize this will cause the agent to create and maintain files with long-lived context on disk, which has security and privacy implications even though the skill itself does not ask for extra platform privileges.

Assessment

This is a documentation-only skill describing a file-backed, persistent agent architecture — it does not install code or request secrets. Before using: be aware the agent will read and write persistent files (~/clawd, memory/, skills/) that can contain sensitive context; review and control where those files are stored and who can access them. Do not store tokens/passwords in plain text files; prefer config.json with appropriate filesystem permissions or a secrets manager. If you let the agent run scripts from skills/scripts, inspect those scripts first for network calls or dangerous commands. Finally, confirm the agent runtime’s filesystem and autonomy policies (what it’s allowed to read/write/execute) before enabling this behavior.

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:

• 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:

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 Assistant	Evolutionary Model
Memory	Resets every session	Persists across sessions
Skills	Fixed capabilities	Grows with use
Context	Generic	Specific to you
Mistakes	Repeated	Documented + prevented
Value over time	Flat	Compounding
Portability	Locked to provider	Files 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/