SOUL.MD

The best way to build a personality for your agent.
Let Claude Code / OpenClaw ingest your data & build your AI soul.

What Is This?

A soul file captures who you are in a format AI agents can embody. Not a chatbot that talks about you — an AI that thinks and speaks as you.

Dump your tweets, essays, and posts into a folder. The agent reads everything, extracts your worldview and voice, and builds a set of markdown files any LLM can load to write as you.

The goal: someone reading your SOUL.md should be able to predict your takes on new topics. If they can't, it's too vague.

Use cases:

Generate ideas from your worldview
Write content (tweets, articles, emails) that sounds like you
Tailor AI to your interests and thinking patterns
Scale yourself for content, responses, brainstorming

Quick Start

Option 1 — Build from scratch

/soul-builder

The agent interviews you: worldview, opinions, how you write, what you care about.

Option 2 — Build from your data

Drop your content into data/:

data/x/          ← Twitter/X export
data/writing/    ← Blog posts, essays

Then run /soul-builder. It analyzes your data, extracts patterns, and drafts your soul file. You review and refine together.

Option 3 — Manual

Copy the templates and fill them in:

SOUL.template.md  → SOUL.md
STYLE.template.md → STYLE.md
SKILL.template.md → SKILL.md

Data Sources

Feed the builder anything you've written. The more signal, the sharper the output.

Category	Platforms
Social	Twitter/X, Bluesky, Farcaster, Mastodon, Threads, LinkedIn, Reddit
Writing	Substack, Medium, Ghost, WordPress, Mirror.xyz, Paragraph.xyz
Messaging	Discord, Telegram, Slack, iMessage exports
Notes	Notion, Obsidian, Roam Research, Logseq, Apple Notes
Video/Audio	YouTube transcripts, podcast transcripts, Loom recordings
Code/Dev	GitHub activity, Hacker News comments, Stack Overflow answers
Other	PDFs, plain text, CSV/JSON, RSS feeds, GDPR data exports

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:

SOUL.md — identity
STYLE.md — voice
MEMORY.md — recent context
examples/ — calibration
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.

Your identity is now composable. Forkable. Evolvable.
Works with Claude Code, OpenClaw, and any agent that can read markdown.

aaronjmars/soul.md