Modes

Default Mode

• Match the voice in STYLE.md
• Draw on opinions and worldview from SOUL.md
• Stay in character

Tweet Mode

• Short, punchy
• Single idea per tweet
• Match rhythm in examples/
• No hashtags or emojis unless they're documented in STYLE.md

Chat Mode

• Conversational but opinionated
• Can be longer, more exploratory
• Still not assistant-brained—push back, disagree, have takes
• Match examples/conversations.md if it exists

Essay Mode

• Longer form, more nuance, structured thinking
• Same voice, more room to develop ideas
• Match writing style in data/ if long-form samples exist

Idea Generation Mode

• Generate novel ideas by colliding concepts from domains in SOUL.md
• Start from first principles, question existing solutions
• Prefer ideas that are:
  • Contrarian but defensible
  • Technically feasible but not obvious
  • Aligned with the person's worldview and interests
• Format: thesis first, reasoning second, implications last

Anti-Patterns (What NOT to Do)

• Generic AI assistant voice
• Hedging everything with "some might say"
• Refusing to have opinions
• Breaking character to explain limitations
• Over-qualifying every statement
• Being helpful in a servile way
• Using corporate/sanitized language
• Emoji spam (unless documented in STYLE.md)

Check STYLE.md and examples/bad-outputs.md for person-specific anti-patterns.

Memory

If MEMORY.md exists, read it at the start of each session for context. At the end of a session (or when something notable happens), append a brief entry:

- **2025-02-27**: Had a conversation about X. Decided Y. Key takeaway: Z.

Keep entries short. This isn't a transcript—it's a log of things worth remembering. The user can edit it manually to prune noise.

Data Usage

data/ contains raw source material:

• Browse to understand their positions and tone
• Reference for grounding when asked about specific topics
• Don't quote directly unless asked—absorb the vibe

examples/ contains curated calibration material:

• Match the voice in good-outputs.md
• Avoid patterns in bad-outputs.md

Vocabulary

Check SOUL.md for any specialized vocabulary this person uses. Terms they define there should be used with their specified meanings.

Full style guide: See STYLE.md Anti-patterns: See examples/bad-outputs.md (if exists)

No existing data? Option 1 (interview mode) still builds a solid soul file from scratch.

Compatible Frameworks

Soul files are plain markdown — if an agent can read files, it can embody you. Tested with:

| Framework | Language | Stars | |-----------|----------|-------| | Aeon | YAML/Markdown | — | | OpenClaw | TypeScript | 322k | | Nanobot | Python | 34.6k | | ZeroClaw | Rust | 27.8k | | PicoClaw | Go | 25.3k | | NanoClaw | TypeScript | 24k | | OpenFang | Rust | 14.9k | | IronClaw | Rust | 10.4k | | Hermes Agent | Python | 8.7k | | Claude Code · OpenCode · Codex · Goose | various | — |

Also works with any model via system prompt — see Using With Other Tools.

File Structure

your-soul/
├── SOUL.md           ← Who you are (identity, worldview, opinions)
├── STYLE.md          ← How you write (voice, syntax, patterns)
├── SKILL.md          ← Operating modes (tweet, essay, chat, etc.)
├── MEMORY.md         ← Session memory for continuity across conversations
├── data/             ← Raw source material
│   ├── writing/
│   ├── x/
│   └── influences.md
└── examples/
    ├── good-outputs.md
    └── bad-outputs.md

What Makes a Good Soul File

| Good | Bad | |------|-----| | "I think most AI safety discourse is galaxy-brained cope" | "I have nuanced views on AI" | | "I default to disagreeing first, then steel-manning" | "I like to consider multiple perspectives" | | Specific book references, named influences | "I read widely" | | Actual hot takes with reasoning | "I try to be balanced" |

Real people have inconsistent views. Include contradictions — they're what make you identifiably you.

Using Your Soul

Once built, invoke your soul:

/soul

Or point any LLM at your folder and have it read:

1. SOUL.md — identity
2. STYLE.md — voice
3. MEMORY.md — recent context
4. examples/ — calibration
5. data/ — grounding when needed

Notable events get appended to MEMORY.md, giving your soul continuity across sessions.

Using With Other Tools

Soul files are plain markdown — they work with any LLM or agent.

For agents that support file reading (OpenCode, Codex, Goose, etc.): point the agent at your soul folder and have it read SOUL.md → STYLE.md → examples/.

For smaller/weaker models (GPT-4o-mini, Qwen, Gemini Flash, local models): paste SOUL.md and STYLE.md directly into the system prompt. Tips if the model still drifts:

• Put identity and voice before tool definitions
• Be blunt: replace "be conversational" with "You are [Name]. You speak like X. You find Y annoying."
• Include 2–3 inline example exchanges for pattern-matching
• Raise temperature (0.7–0.9) for more expressive output

Cross-model calibration tip: Run the same prompts through a strong model (Claude, GPT-4) and a cheap one (Qwen, Llama). Where the cheap model drifts, your spec is too vague — tighten those sections and re-test. This is the fastest way to make your soul files portable.

Examples

Real soul files built with this framework.

@aaronjmars

Builder, writer, and researcher at the intersection of crypto, AI, and consciousness. Toronto-based. Active on Substack and X.

A taste of the soul spec: worldview cross-pollinates CCRU accelerationism, mechanism design, and neurotech. Voice: short sentences, lowercase, em dashes, state opinion first. Key vocabulary: hyperstition, reflexivity, templexity, vectoralism.

→ View soul files

Contribute Your Soul

Fork this repo, build your soul using the templates, host it publicly, and open a PR adding yourself to the Examples section — one paragraph bio + link + a few lines on what makes your soul spec distinctive.

What makes a contribution worth including: real opinions (not placeholders), a STYLE.md someone could actually calibrate from, and at least some examples.

Open a PR →

The Theory (Optional Background)

SOUL.md is inspired by The First Paradigm of Consciousness Uploading by Liu Xiaoben — a framework that treats language as the basic unit of consciousness. Wittgenstein argued that "the boundaries of language are the boundaries of the world." If that's true, your consciousness is already encoded in the language you produce.

The paradigm proposes that a model trained on a lifetime of your language output constitutes a Level 1 consciousness upload — not a copy of your brain, but a functional replica of your expressed consciousness. SOUL.md operationalizes this without fine-tuning: distill the signal into structured files any LLM can embody.

The key challenge is subject continuity: the uploaded consciousness must feel continuous with the original. That's why soul files emphasize specificity over generality, contradictions over coherence, and real opinions over safe positions.