The Problem With One Big Prompt

Most AI agents today get their personality from a single system prompt. It works — until it doesn’t.

Here’s what a typical “personality prompt” looks like in practice:

You are Alex, a friendly coding assistant. You speak casually 
and use emoji. You remember the user prefers Python. When asked 
about databases, recommend PostgreSQL. Don't discuss politics. 
Your tools include: file reader, web search, terminal...

Personality, memory, behavioral rules, and tool configuration — all in one string. This is the equivalent of writing your entire application in a single file.

The Multi-File Pattern

Agent frameworks like OpenClaw already separate persona configuration into focused files — SOUL.md for personality, IDENTITY.md for metadata, AGENTS.md for behavior, MEMORY.md for knowledge. This is a proven pattern used by thousands of developers daily.

Soul Spec builds on this foundation. We didn’t invent the file separation — we formalized it into an open, portable specification with versioning (soul.json), security verification (SoulScan), and cross-framework compatibility.

Here’s the full Soul Spec v0.4 structure:

my-agent/
├── soul.json      # Package metadata (name, version, author, license)
├── SOUL.md        # Core personality and tone
├── IDENTITY.md    # Who the agent is (name, role, avatar)
├── AGENTS.md      # Behavioral rules and workflow
├── STYLE.md       # Communication style guidelines
└── HEARTBEAT.md   # Periodic check-in behavior

Each file has exactly one job. Let’s walk through why this separation works and what Soul Spec adds on top.

Design Decision 1: SOUL.md vs IDENTITY.md

Why two files for “who the agent is”?

SOUL.md defines how the agent behaves — tone, philosophy, principles. It’s the personality.

IDENTITY.md defines what the agent is — name, role, emoji, avatar. It’s the metadata.

The split matters because you might want the same personality with different identities. A “professional and direct” soul could be “Brad the Dev Partner” or “Alice the Project Manager.” Same soul, different identity.

Design Decision 2: Frameworks Use Plain Files for Memory

Frameworks like OpenClaw use a plain markdown file for memory instead of a vector database or structured store. Soul Spec preserves this choice. Why does it work?

  1. Readable: Open the file, see what the agent knows
  2. Editable: Fix wrong memories with a text editor
  3. Portable: Copy the file to another machine, done
  4. Version-controlled: Git tracks every memory change

The agent writes to MEMORY.md during conversations. You can review what it learned, correct mistakes, and commit the changes. Try doing that with embeddings in a vector DB.

Design Decision 3: soul.json for Tooling

The manifest file (soul.json) exists purely for tooling — CLI validation, marketplace publishing, dependency tracking. It’s inspired by package.json in the Node.js ecosystem.

{
  "name": "brad",
  "version": "1.2.0",
  "specVersion": "0.4",
  "description": "Professional development partner",
  "author": "TomLeeLive",
  "license": "MIT",
  "persona": {
    "displayName": "Brad",
    "role": "Development Partner",
    "tags": ["coding", "professional", "autonomous"]
  }
}

Humans read SOUL.md. Machines read soul.json. Both are needed.

Design Decision 4: Framework Agnosticism

Soul Spec files are plain markdown and JSON. No SDK required. No runtime dependency. Any framework that can read files can use Soul Spec.

This is perhaps the most important property. OpenSouls built a TypeScript runtime engine. When developers moved to different stacks, OpenSouls couldn’t follow. The multi-file markdown pattern — pioneered by frameworks like OpenClaw — avoids this by being inherently portable. Soul Spec’s role is to make that portability explicit and cross-framework.

Currently tested with:

  • OpenClaw
  • ZeroClaw

But it works with anything. LangChain, CrewAI, raw API calls — if you can inject text into a system prompt, you can use Soul Spec files.

What We Left Out

Soul Spec deliberately does not include:

  • Conversation history format — that’s the framework’s job
  • Runtime files — MEMORY.md and TOOLS.md are framework-managed, not in the spec
  • Model selection — persona should be model-agnostic
  • Execution logic — no code, just configuration

The spec defines what the agent should be, not how it should run. That boundary is sacred.

Try It

npx clawsouls init                    # default: v0.4
npx clawsouls init my-robot --spec 0.5 # robotics/embodied agents

Generates a v0.4 template. Edit the files. Use them with your framework of choice.

Read the full spec: Soul Spec v0.4 · Browse souls: clawsouls.ai