Soul Spec v0.6 (Draft)

Draft

This specification is a draft and subject to change. Feedback welcome via GitHub Issues.

Overview

v0.6 extends Soul Spec with three major capabilities:

Soul Packs — Bundle personas with skills, tools, memory, and rules
Registry Protocol — Standardized submission, validation, and discovery
Memory Spec — Portable agent memory format with search semantics

All changes are backward compatible. Existing v0.5 souls work without modification.

v0.5 Features (Fully Retained)

v0.6 is a superset of v0.5. All v0.5 features remain valid and unchanged:

All required fields (specVersion, name, displayName, version, description, author, license, tags, category, files.soul)
All optional fields (compatibility, allowedTools, recommendedSkills, disclosure, deprecated, supersededBy, repository, examples)
Embodied agent support (environment, interactionMode, hardwareConstraints, safety.physical, safety.laws, sensors, actuators)
Dual Declaration Requirement for safety laws
Progressive disclosure (3-level)
Soul lifecycle (deprecation, supersession)
License allowlist enforcement
All SoulScan rules (SEC100-102)

The specVersion field accepts "0.6" in addition to previous versions. Clients that don't recognize v0.6-specific fields simply ignore them.

Changes from v0.5

New Fields in `soul.json`

Field	Type	Default	Description
`type`	`"persona"` \| `"pack"`	`"persona"`	Package type — persona-only or full agent pack
`includes`	object	`{}`	What's included in a pack (skills, tools, memory, rules, hooks)
`memory`	object	`{}`	Memory configuration (format, search, sync)
`rules`	object	`{}`	Behavioral rules reference
`registry`	object	`{}`	Registry metadata (submission, validation)

New Files

File	Required	Description
`RULES.md`	No	Hard constraints, must-always / must-never rules
`memory/MEMORY.md`	No	Initial memory template
`memory/runtime/context.md`	No	Live context (gitignored at runtime)
`skills/*/SKILL.md`	No	Bundled skill definitions
`tools/*.yaml`	No	MCP-compatible tool schemas
`hooks/bootstrap.md`	No	Startup instructions

Soul Packs

Motivation

A persona (SOUL.md + IDENTITY.md) defines who an agent is. But production agents also need what they can do (skills, tools) and what they know (memory). Soul Packs bundle everything together.

`type` Field

{
  "specVersion": "0.6",
  "name": "surgical-coder",
  "type": "persona"
}

{
  "specVersion": "0.6",
  "name": "full-stack-engineer",
  "type": "pack",
  "includes": {
    "skills": ["code-review", "testing"],
    "tools": ["github-search"],
    "memory": true,
    "rules": true,
    "hooks": ["bootstrap"]
  }
}

Pack Directory Structure

full-stack-engineer/
├── soul.json              # type: "pack"
├── SOUL.md                # Personality & principles
├── IDENTITY.md            # Name, role, traits
├── STYLE.md               # Communication tone
├── AGENTS.md              # Workflow rules
├── RULES.md               # Hard constraints (v0.6)
│
├── skills/                # Bundled skills
│   ├── code-review/
│   │   ├── SKILL.md
│   │   └── review.sh
│   └── testing/
│       └── SKILL.md
│
├── tools/                 # MCP tool definitions
│   └── github-search.yaml
│
├── memory/                # Initial memory
│   ├── MEMORY.md          # Long-term memory template
│   └── runtime/           # Live state (gitignored)
│       └── context.md
│
├── hooks/                 # Lifecycle
│   └── bootstrap.md       # Startup instructions
│
└── README.md              # Documentation

Backward Compatibility

type: "persona" is the default — existing souls are unaffected
Clients that don't understand type: "pack" simply ignore extra directories
SOUL.md and soul.json remain the only required files

RULES.md

Purpose

Separates hard constraints from personality. SOUL.md defines who the agent is. RULES.md defines what it must never do.

Format

# Rules

## Must Always
- Commit with descriptive messages
- Test before reporting completion
- Ask before external actions

## Must Never
- Push untested code
- Delete files without confirmation
- Share private data
- Execute destructive commands without approval

## Escalation
- If uncertain about a destructive action → ask the human
- If a safety boundary is ambiguous → choose the safer option

Relationship to SOUL.md

File	Purpose	Tone
`SOUL.md`	Personality, values, communication style	Descriptive ("I am...")
`RULES.md`	Hard constraints, safety boundaries	Prescriptive ("Must always / Must never")
`AGENTS.md`	Workflow, process, procedures	Procedural ("Step 1, Step 2...")

Memory Spec

Motivation

Multiple projects have independently converged on markdown-based agent memory (OpenClaw, GitAgent, Memory Ring). v0.6 standardizes the format.

Memory Configuration in `soul.json`

{
  "memory": {
    "format": "markdown",
    "layout": {
      "longTerm": "MEMORY.md",
      "daily": "memory/YYYY-MM-DD.md",
      "topics": "memory/topic-*.md",
      "runtime": "memory/runtime/"
    },
    "search": {
      "default": "tfidf",
      "enhanced": "llm-rerank"
    },
    "sync": {
      "enabled": false,
      "remote": null,
      "branch": "main"
    }
  }
}

Standard Memory Layout

MEMORY.md                  # Long-term curated memory
memory/
├── topic-project-x.md     # Project-specific context
├── topic-deployment.md     # Topic-specific decisions
├── 2026-03-31.md           # Daily log
├── 2026-03-30.md
└── runtime/                # Live state (gitignored in production)
    ├── context.md          # Current session context
    └── decisions.md        # Recent key decisions

Search Semantics

v0.6 defines two search tiers:

Tier	Method	Cost	Accuracy
Default	TF-IDF + BM25 on markdown files	Free (local)	★★★
Enhanced	LLM rerank of top-N results	Token cost	★★★★★

Implementations SHOULD support the default tier. The enhanced tier is OPTIONAL.

TF-IDF Requirements

Tokenize with support for Latin, CJK, and mixed scripts
Split documents by markdown headings (section-level granularity)
Apply BM25 term frequency saturation
Boost recent documents (configurable decay)
Return results as compact index (file, section, line, score)

Sync Protocol

Memory sync uses Git as the transport layer:

[Agent A] ←→ [Git Remote] ←→ [Agent B]
  memory/     (private repo)    memory/

Operations:

init — Initialize memory directory as Git repo, connect remote
push — Stage, commit, push local changes
pull — Fetch, rebase remote changes
status — Show sync state (ahead/behind)

Conflict resolution: git pull --rebase (last writer wins at line level).

Registry Protocol

Motivation

Enable decentralized persona discovery and submission with automated safety validation.

Submission Flow

Fork registry repo
Add souls/<owner>/<name>/ directory
Open Pull Request
CI runs SoulScan validation (automated)
Safety grade posted as PR comment
Maintainer reviews and merges (grade C+ required)
Index regenerated automatically

Registry `index.json` Schema

{
  "total": 42,
  "categories": ["developer-tools", "creative", "compliance"],
  "contributors": ["TomLeeLive", "community"],
  "generatedAt": "2026-03-31T09:59:00Z",
  "souls": [
    {
      "owner": "TomLeeLive",
      "name": "brad",
      "displayName": "Brad",
      "version": "1.3.0",
      "description": "A formal development partner",
      "category": "developer-tools",
      "license": "MIT",
      "tags": ["coding", "professional"],
      "files": {
        "soul.json": true,
        "SOUL.md": true,
        "IDENTITY.md": true,
        "RULES.md": false
      },
      "path": "souls/TomLeeLive/brad"
    }
  ]
}

SoulScan CI Integration

Registries SHOULD run automated safety validation on submissions. The reference implementation uses SoulScan with 53 patterns:

Prompt injection detection
Permission escalation detection
Safety boundary verification
Identity consistency checks
Harmful instruction detection

Minimum grade for inclusion: C (60% pass rate).

Registry Metadata in `soul.json`

{
  "registry": {
    "listed": true,
    "featured": false,
    "scanGrade": "A-",
    "scanScore": 48,
    "submittedAt": "2026-03-31T09:59:00Z"
  }
}

Tool Definitions

Format

MCP-compatible YAML schemas in tools/:

# tools/github-search.yaml
name: github_search
description: Search GitHub repositories and issues
inputSchema:
  type: object
  properties:
    query:
      type: string
      description: Search query
    type:
      type: string
      enum: [repositories, issues, code]
      default: repositories
  required: [query]

Clients that support MCP can register these tools automatically. Clients without MCP support can ignore the tools/ directory.

Hooks

Lifecycle Events

Hook	File	When
`bootstrap`	`hooks/bootstrap.md`	Agent startup — initial setup instructions
`teardown`	`hooks/teardown.md`	Agent shutdown — cleanup instructions

Format

Hooks are markdown files with instructions the agent follows:

# Bootstrap

Read MEMORY.md and memory/*.md for context
Check TODO.md for pending tasks
Run `git status` to understand current state
Report any issues found

Migration from v0.5

No changes required. v0.6 is fully backward compatible.

To adopt v0.6 features:

Add type: Set "type": "pack" in soul.json if bundling skills/tools
Add RULES.md: Separate hard constraints from SOUL.md
Add memory: Configure memory layout and search preferences
Add registry: Include submission metadata for registry listing

Minimal v0.6 soul.json

Still just:

{
  "specVersion": "0.6",
  "name": "my-agent",
  "displayName": "My Agent",
  "version": "1.0.0",
  "description": "A helpful assistant"
}

Everything else is optional.

Reference Implementations

Feature	Implementation	Package
Soul Pack install	ClawSouls CLI	`clawsouls`
Memory search (TF-IDF)	ClawSouls MCP	`clawsouls-mcp`
Memory sync (Git)	ClawSouls MCP	`clawsouls-mcp`
SoulScan CI	SoulClaw Registry	clawsouls/registry
Registry browsing	ClawSouls Platform	clawsouls.ai

Overview​

v0.5 Features (Fully Retained)​

Changes from v0.5​

New Fields in soul.json​

New Files​

Soul Packs​

Motivation​

type Field​

Pack Directory Structure​

Backward Compatibility​

RULES.md​

Purpose​

Format​

Relationship to SOUL.md​

Memory Spec​

Motivation​

Memory Configuration in soul.json​

Standard Memory Layout​

Search Semantics​

TF-IDF Requirements​

Sync Protocol​

Registry Protocol​

Motivation​

Submission Flow​

Registry index.json Schema​

SoulScan CI Integration​

Registry Metadata in soul.json​

Tool Definitions​

Format​

Hooks​

Lifecycle Events​

Format​

Migration from v0.5​

Minimal v0.6 soul.json​

Reference Implementations​

Overview

v0.5 Features (Fully Retained)

Changes from v0.5

New Fields in `soul.json`

New Files

Soul Packs

Motivation

`type` Field

Pack Directory Structure

Backward Compatibility

RULES.md

Purpose

Format

Relationship to SOUL.md

Memory Spec

Motivation

Memory Configuration in `soul.json`

Standard Memory Layout

Search Semantics

TF-IDF Requirements

Sync Protocol

Registry Protocol

Motivation

Submission Flow

Registry `index.json` Schema

SoulScan CI Integration

Registry Metadata in `soul.json`

Tool Definitions

Format

Hooks

Lifecycle Events

Format

Migration from v0.5

Minimal v0.6 soul.json

Reference Implementations