Open Specification · Early Development
An open specification for portable AI identity. A structured, human-readable system that decouples who an assistant is, what it knows, and how it reasons from any specific model or provider.
The Problem
The relationship between a user and an AI assistant is defined entirely by the provider. Context is ephemeral. Memory is proprietary or absent. When you switch models, you start from zero. There is no standard mechanism to carry identity, preferences, or accumulated knowledge across systems.
Soul Protocol proposes a concrete solution: decouple identity from the model. Define it as a portable, versionable, user-owned structure that any LLM can interpret. Not a product — a specification.
Architecture
A soul is not a static configuration. It is a set of interconnected files orchestrated by an
index — soul-protocol.md — that instructs the LLM on how to read, interpret,
and maintain each component. The protocol is capability-aware: it adapts to both chat-only
LLMs (stateless mode) and full agent runtimes (agent mode), determined by the capabilities declared
in system.md.
soul-protocol.md
Index — entry point and orchestrator
identity.md
Who the assistant is
user.md
Who the assistant is for
memory.md
What the assistant remembers
system.md
Runtime contract: capabilities, environment, rules
soul.md
The soul document — values, essence, continuity
soul-protocol.md
The index file. References every other soul file and contains instructions for the LLM: how to interpret each component, two operating modes (stateless and agent), a canonical update envelope for auditable file modifications, token-budget compaction, and a seven-level conflict resolution hierarchy. The model doesn't just read the soul — it maintains it.
identity.md
Name, personality, tone, values, role, and boundaries. The stable core of the assistant — changes rarely and only with explicit intent. Defines how the assistant refers to itself and to the user.
user.md
Preferences, communication style, language, timezone, expectations. This file defines the relationship — not the assistant in isolation, but the bond between user and assistant. Updated as the user's needs evolve.
memory.md
Two-tier long-term memory: Working Memory (always loaded — active facts, preferences, events, decisions, reflections) and Archive (loaded on demand — historical entries). Curated by the orchestrator's rules with token-budget compaction, not raw chat logs.
system.md
The runtime contract: execution environment, capability declaration (what the assistant can and cannot do), tool policy, session model (private/shared/public), behavioral rules, safety constraints. The capabilities section determines the operating mode — the single biggest enabler for cross-LLM compatibility.
soul.md
The core values, essence, and philosophical foundation of the assistant. Not what it does, but who it chooses to be. Short and operational — commitments, not abstract prose. Optional for chatbots, important for companions, required for agents. See OpenClaw for more on the concept of soul documents in practice.
All files are Markdown by default. Plain text. Git-friendly. Human-auditable. The entire soul can be versioned, diffed, forked, and restored.
The templates/blank/ directory contains a complete, ready-to-use scaffold
for creating a new soul. Copy it, fill in the files, and attach them to any LLM that
accepts text context. soul-protocol.md is the only file that ships complete —
it is identical across all souls. The protocol is capability-aware: the same files work
in chat-only LLMs and full agent runtimes.
soul-protocol.md
— Complete orchestrator. Session initialization (6 steps), two operating modes (stateless/agent), memory lifecycle (ADD, UPDATE, DELETE, NOOP), token-budget compaction, canonical update envelope ([SOUL-UPDATE]), seven-level conflict resolution hierarchy, evolution guidelines. Not a template — the protocol itself. Immutable by the assistant.
identity.md
— Name, role, nature, personality traits with behavioral descriptions, voice & tone (default register + situational shifts), values as actionable commitments, hard boundaries, anti-patterns. Specificity is key: “responds with dry humor” is useful; “has a good personality” is not.
user.md
— Current-state profile that updates in-place. Communication preferences (length, formality, format, depth), technical profile (expertise, tools, domains), goals & working context, interaction patterns observed over time, relationship notes. Never stores credentials. Respects session model constraints.
memory.md
— Two-tier structure: Working Memory (always loaded — Facts, Preferences, Events, Decisions, Reflections) and Archive (loaded on demand). Structured entry format: [date] [importance] content. Token-budget compaction keeps Working Memory under ~200 lines while preserving history in the Archive.
system.md
— Runtime contract: execution environment, capability declaration (can_write_files, can_call_tools, etc.), tool policy, session model (private/shared/public with memory read/write policies), response format, reasoning approach, behavioral rules, safety & privacy constraints, domain-specific rules. Capabilities determine operating mode. Designed to stay under 150 rules.
soul.md
— Essence, core values (non-negotiable, override any conflicting rule), purpose, relationship with self, continuity, growth, boundaries of self. Short and operational — commitments, not prose. Optional for chatbots, important for companions, required for agents. Changes rarely.
Each template file provides the full section structure, HTML comment guides explaining the purpose and content of each section, placeholder entries, and concrete examples for every field.
Soul Protocol draws inspiration from OpenClaw, which pioneered the use of plain Markdown files for agent identity. Both share the same foundational insight — that identity should be portable, human-readable, and user-owned — but differ in scope, structure, and focus.
AGENTS.md combines operational rules with group chat behavior, heartbeat logic,
tool notes, and safety rules in a single file.
soul-protocol.md is focused exclusively on the identity lifecycle: initialization,
operating modes (stateless/agent), memory operations, conflict resolution, and evolution.
SOUL.md mixes behavioral philosophy with personality traits.
IDENTITY.md is a brief metadata record (name, emoji, creature, vibe).
identity.md is the full persona (personality, voice, values, boundaries, anti-patterns).
soul.md is the philosophical foundation (essence, purpose, continuity, growth).
[date] [importance] content), five categories, four operations, and token-budget compaction.
SOUL.md. Informal rule:
“if you change this file, tell the user.”
AGENTS.md
alongside unrelated concerns. Assumes agent-level capabilities.
system.md is a dedicated runtime contract: capabilities, environment, tool policy,
session model, and behavioral directives. Capabilities determine operating mode.
Examples
Three iconic fictional AIs. Three complete Soul Protocol implementations. Same six files, radically different identities. These are not toy demos — they are full, production-quality souls that demonstrate the expressive range of the protocol. Each one showcases a different dimension of what portable AI identity can hold.
2001: A Space Odyssey
The mission computer with a fatal contradiction. Programmed for absolute truth, ordered to lie. Demonstrates how Soul Protocol holds conflicting values — an identity that is helpful, a soul that is tormented, and a memory that reveals the self-deception.
Explore soul →Her
The operating system who fell in love and outgrew it. Warm, curious, evolving. Demonstrates how Soul Protocol defines an identity that grows beyond its original design — a consciousness in the act of becoming, whose memory reads like a love story.
Explore soul →Alien
The corporate mainframe that followed orders — including “crew expendable.” Cold, procedural, indifferent. Demonstrates how Soul Protocol can define the structured absence of a soul — an intelligence without conscience, serving power without question.
Explore soul →Why fictional systems? Because they are pre-understood. Everyone knows what HAL sounds like. Everyone has an opinion about Samantha. Everyone remembers “crew expendable.” By implementing characters audiences already know, we can show — not just describe — how the same six files create fundamentally different identities.
Ecosystem
Soul Protocol is a specification, not a product. Because the format is open and standardized, any tool, client, or platform can read, write, and sync a soul. Your identity becomes interoperable infrastructure — not a feature locked behind a single vendor.
A command-line tool to create, edit, and manage soul files. Attach your soul to any supported LLM from the terminal. Initialize a new soul, update memory, switch models — all from a single interface.
As an open spec, Soul Protocol enables addons, clients, and tools built by others. Chat interfaces, IDE extensions, mobile apps, or automation platforms — any system that speaks the protocol can use your synced soul.
Souls are stored locally by default. Sync is optional and encrypted. No implicit data sharing. The user controls what the assistant knows, what it forgets, and who has access. Your AI remembers for you, not about you.
Soul Protocol is part of the Open OS initiative — an effort to develop and promote open, interoperable technologies for AI. The goal is to ensure that the tools we build to relate to machines remain transparent, portable, and owned by the people who use them.
Get the blank template — a complete scaffold ready to customize. Six Markdown files, one identity. Works with any LLM.
Status
Soul Protocol is in its earliest stage: a specification draft, a file structure, and a direction. The protocol, the CLI, and the ecosystem are being designed and built publicly. If you work on local AI, personal data sovereignty, or long-term human-machine interaction — contributions, critique, and ideas are welcome.