Configure AI agents through markdown, not code.

The SOUL/MEMORY/skills pattern for building multi-agent AI systems.

Soul Agent Framework is an opinionated, file-based architecture for configuring AI agents entirely through markdown files. Instead of writing code to define agent behavior, you write prose.

The core idea: an AI agent's personality, memory, skills, and team structure should be readable by humans and machines alike. Markdown is the universal interface.

Your agent is defined by what it reads at startup — not by what you compile.

This repo provides:

• A battle-tested file structure for single and multi-agent systems
• Ready-to-use templates for every configuration file
• A Coffee Shop multi-agent team as a complete working example
• A modular skills system with manifests for discoverability
• A two-tier memory architecture that grows with your agent

┌─────────────────────────────────────────────────────────────────┐
│                        SESSION START                            │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  1. Read BOOTSTRAP.md                                           │
│     "How do I wake up? What do I do first?"                     │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                    ┌──────────┼──────────┐
                    ▼          ▼          ▼
             ┌──────────┐ ┌────────┐ ┌──────────┐
             │ SOUL.md  │ │USER.md │ │IDENTITY  │
             │          │ │        │ │.md       │
             │ Who am I │ │ Who is │ │ What am  │
             │ and how  │ │ my     │ │ I called │
             │ do I     │ │ user?  │ │ and how  │
             │ behave?  │ │        │ │ do I     │
             │          │ │        │ │ present? │
             └──────────┘ └────────┘ └──────────┘
                    │          │          │
                    └──────────┼──────────┘
                               │
                    ┌──────────┼──────────┐
                    ▼          ▼          ▼
             ┌──────────┐ ┌────────┐ ┌──────────┐
             │MEMORY.md │ │TOOLS.md│ │AGENTS.md │
             │          │ │        │ │          │
             │ What do  │ │ What   │ │ Who else │
             │ I already│ │ can I  │ │ is on my │
             │ know?    │ │ use?   │ │ team?    │
             └──────────┘ └────────┘ └──────────┘
                    │          │          │
                    └──────────┼──────────┘
                               │
                               ▼
             ┌─────────────────────────────────┐
             │         Load Skills             │
             │                                 │
             │  skills/rag/SKILL.md            │
             │  skills/order-taking/SKILL.md   │
             │  skills/menu-search/SKILL.md    │
             └────────────────┬────────────────┘
                              │
                              ▼
             ┌─────────────────────────────────┐
             │    Read HEARTBEAT.md            │
             │    (scheduled/recurring tasks)  │
             └────────────────┬────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AGENT IS OPERATIONAL                        │
│                                                                 │
│  ┌─────────┐  ┌──────────┐  ┌───────────┐  ┌───────────────┐  │
│  │ Respond │  │ Delegate │  │ Remember  │  │ Use Skills    │  │
│  │ to user │  │ to team  │  │ new facts │  │ (RAG, search) │  │
│  └─────────┘  └──────────┘  └───────────┘  └───────────────┘  │
└──────────────────────────────────────────────────────────────────┘

git clone https://github.com/mingrath/soul-agent-framework.git
cd soul-agent-framework

# Copy just the core files
cp SOUL.md MEMORY.md AGENTS.md USER.md IDENTITY.md TOOLS.md HEARTBEAT.md BOOTSTRAP.md /your/project/

# Or copy everything including skills
cp -r . /your/project/agent-config/

This is the most important file. It defines who your agent is. Open it and replace the coffee shop example with your own domain.

Every AI platform has a way to inject system context. Point it at your markdown files:

# Pseudocode — works with any LLM framework
soul = read("SOUL.md")
memory = read("MEMORY.md")
identity = read("IDENTITY.md")

system_prompt = f"""
{soul}

{memory}

{identity}
"""

agent = Agent(system_prompt=system_prompt)

For Claude Code users, place files in .claude/ or reference them in CLAUDE.md.

The heart of the framework. Defines:

• Core principles — non-negotiable rules the agent must follow
• Voice and personality — how the agent communicates
• Operational boundaries — what the agent must never do
• Delegation rules — when to hand off to another agent

Think of it as the agent's constitution. Everything else is subordinate to SOUL.md.

The agent's long-term memory. Split into two tiers:

1. Working Memory (MEMORY.md itself) — curated, high-signal facts
2. Raw Memory (memory/ directory) — daily logs, topic notes, project context

The agent writes to memory/daily/ during operation. Periodically, important facts get promoted to MEMORY.md.

Defines the team. Each agent has:

• A name and role
• Specific skills it can use
• Conditions under which it gets activated
• A delegation protocol (how tasks are handed off)

A profile of the human the agent serves. Includes preferences, communication style, timezone, and any personal context that helps the agent be more useful.

How the agent presents itself — name, pronouns, avatar description, introduction message. Separating identity from soul lets you reskin agents without changing behavior.

A registry of external tools the agent can use — APIs, databases, file systems, search engines. Each tool entry includes: name, when to use it, authentication method, and example usage.

Scheduled tasks the agent should perform even without user input. Daily summaries, weekly reports, data refreshes, health checks. Think of it as the agent's cron job.

First-run instructions. When the agent starts a fresh session with no conversational context, this file tells it what to do: read which files, in what order, and what checks to perform.

Start with SOUL.md. Answer these questions in prose:

• What is this agent's primary job?
• What are its non-negotiable rules?
• How should it talk? (formal? casual? technical?)
• What should it never do?

# Soul

## Core Purpose
You are a [ROLE] that helps [WHO] with [WHAT].

## Principles
1. Always [PRINCIPLE_1]
2. Never [PRINCIPLE_2]
3. When in doubt, [FALLBACK_BEHAVIOR]

## Voice
- Tone: [formal/casual/friendly/professional]
- Length: [concise/detailed/adaptive]
- Style: [direct/conversational/socratic]

Create MEMORY.md with sections relevant to your domain:

# Memory

## Key Facts
- [Important thing the agent should always know]

## User Preferences
- [How the user likes things done]

## Learned Patterns
- [Things the agent has discovered over time]

Create a directory under skills/ for each capability:

skills/your-skill/
├── SKILL.md         # What the skill does, when to use it
└── manifest.json    # Machine-readable metadata

If you need multiple agents, define them in AGENTS.md:

## Team

| Agent | Role | Skills | Trigger |
|-------|------|--------|---------|
| agent-1 | Customer support | rag, search | User asks a question |
| agent-2 | Data analysis | sql, charts | User requests a report |

Point your LLM orchestrator at the files. The framework is runtime-agnostic — it works with any system that can inject text into a prompt.

The framework supports horizontal delegation between peer agents. No central orchestrator required.

┌──────────────┐     task handoff      ┌──────────────┐
│              │ ──────────────────────▶│              │
│  Barista Bot │                        │ Inventory Bot│
│  (customer)  │◀────────────────────── │  (stock)     │
│              │     result returned    │              │
└──────────────┘                        └──────────────┘
       │                                       │
       │          task handoff                 │
       │    ┌──────────────────┐               │
       └───▶│   Manager Bot    │◀──────────────┘
            │   (oversight)    │
            └──────────────────┘

When an agent needs to hand off a task, it uses a structured format:

@delegate inventory-bot
Task: Check stock level for oat milk
Context: Customer wants an oat milk latte, need to verify availability
Priority: high
Respond-to: barista-bot

The receiving agent picks up the task, executes it using its own skills and memory, and returns the result.

Tier 1: MEMORY.md (curated, persistent)
├── Key facts about users
├── Important decisions
├── Learned preferences
└── Domain knowledge

Tier 2: memory/ directory (raw, append-only)
├── daily/2025-01-15.md    ← what happened today
├── topics/coffee-beans.md  ← everything about beans
└── projects/new-menu.md    ← specific project context

1. Observe — Agent encounters new information during conversation
2. Log — Raw observation written to memory/daily/YYYY-MM-DD.md
3. Curate — Periodically, significant facts get promoted to MEMORY.md
4. Forget — Old daily logs can be archived or deleted; MEMORY.md retains only what matters

• Tier 1 is always loaded into context. It must stay small and high-signal.
• Tier 2 is searched on demand. It can grow indefinitely.

This mirrors how human memory works: you remember key facts instantly, but can dig into detailed memories when needed.

Skills are modular, reusable capabilities that agents can load on demand.

skills/
├── rag/
│   ├── SKILL.md          # Human-readable documentation
│   └── manifest.json     # Machine-readable metadata
├── order-taking/
│   ├── SKILL.md
│   └── manifest.json
└── menu-search/
    ├── SKILL.md
    └── manifest.json

{
  "name": "rag",
  "version": "1.0.0",
  "description": "Retrieval-Augmented Generation for knowledge base queries",
  "triggers": ["search", "find", "look up", "what is"],
  "requires": ["vector_store"],
  "agents": ["barista-bot", "manager-bot"]
}

Skills can be symlinked across projects:

# Share the RAG skill across multiple agent configs
ln -s /shared/skills/rag /your/project/skills/rag

This lets you build a library of skills and compose agents from reusable parts.

A multi-agent team running a coffee shop. Includes:

• Barista Bot — takes orders, remembers regulars, suggests drinks
• Inventory Bot — tracks stock, reorders supplies
• Manager Bot — schedules shifts, generates reports

See examples/coffee-shop/ for the full setup.

A legal research assistant with multi-agent delegation. Shows how the pattern works outside of the coffee shop domain.

See examples/legal-advisor/ for the starter setup.

• Readable — anyone can understand the agent's configuration
• Versionable — git diff shows exactly what changed in agent behavior
• Portable — works with any LLM, any framework, any language
• Composable — mix and match files across projects
• Debuggable — when the agent misbehaves, read its soul

Code is great for logic. Markdown is great for intent. An agent's personality, boundaries, and knowledge are better expressed in natural language than in Python classes.

Code says: if user.is_angry: respond_with(empathy_template_3)
Soul says: When a customer is frustrated, slow down. Acknowledge their feeling before solving the problem.

The second version produces better AI behavior because it gives the model room to reason, not just execute.

• Claude by Anthropic — the AI that inspired this pattern
• Claude Code — where the SOUL/MEMORY pattern was born
• Markdown — the universal language of documentation

This framework was extracted from real-world patterns used in production AI agent systems. It works because it aligns with how modern LLMs actually process instructions.

Contributions are welcome! Here's how:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-skill)
3. Add your changes
4. Commit with a descriptive message
5. Push to your branch
6. Open a Pull Request

• New example domains (healthcare, education, e-commerce)
• Additional skill templates
• Integration guides for specific LLM frameworks (LangChain, CrewAI, AutoGen)
• Translations of templates
• CLI tooling for scaffolding new agent configs

This project is licensed under the MIT License. See LICENSE for details.

Stop coding your agents. Start writing them.