SOUL.MD

The best way to build a personality for your agent.
Let Claude Code / OpenClaw ingest your data & build your AI soul.
Best used with Aeon — background intelligence that evolves with you.

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
examples/good-outputs.template.md   → examples/good-outputs.md
examples/bad-outputs.template.md    → examples/bad-outputs.md

Best Used With Aeon

Aeon is an autonomous agent on GitHub Actions, powered by Claude Code. 68 skills across research, dev tooling, crypto monitoring, and productivity — all running in the background on a cron schedule.

Soul files slot directly into Aeon. Copy your soul into soul/ in your Aeon repo, add a few lines to CLAUDE.md, and every skill Aeon runs — articles, digests, tweets, research briefs — gets written in your voice. No per-skill config. Identity propagates automatically.

Why this pairing works:

• Aeon handles the when and what — scheduling, research, monitoring, content generation
• Soul files handle the who — voice, worldview, opinions, style
• Together you get a background agent that doesn't just work for you — it sounds like you

Setup takes 2 minutes. See Aeon's Soul section for details.

Data Sources

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

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:

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)
├── 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

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.

For always-on operation, pair with Aeon — your soul files feed into every skill automatically, so background tasks (digests, articles, tweets, monitoring alerts) all carry your voice without any extra prompting.

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

@garrytan

YC President & CEO, investor, builder, SF political figure. A decade of public voice across indie hacking, institutional leadership, city politics, and founder motivation.

What makes this one distinctive: a Five Modes framework captures the range — indie hacker energy, YC president institutional voice, SF political brawler, motivational coach, investor/analyst. Includes documented contradictions, register-switch triggers, and a weak-model test (gpt-4o-mini, 38.5/48). Built autonomously by Daydreams agent #44693.

→ View soul files

@karpathy

ML researcher, educator, and builder. OpenAI founding member, former Sr. Director of AI at Tesla, founder of Eureka Labs. Creator of nanoGPT, llm.c, micrograd, and the Zero-to-Hero YouTube series.

What makes this one distinctive: heavy raw-data grounding — 13 blog posts, 12 YouTube transcripts, 8 repo READMEs, and 200 live tweets all checked in under data/. Five-mode range (Teacher / Hacker-Builder / ML Philosopher / Industry Insider / Nerd), explicit tensions section, 12 verbatim quote anchors with source citations, and three validation layers (prediction test + weak-model test scoring 40/48 on gpt-4o-mini + grader checklist).

→ View soul files

@VivianBala

Singapore's Minister for Foreign Affairs since 2015. Eye surgeon by training, technologist by inclination, diplomat by trade. Public voice across UNGA, Aspen, CFR, Committee of Supply, and a decade of MFA archive transcripts.

What makes this one distinctive: a small-state foreign-policy register where structure is performed out loud — pre-announced ("let me make three points"), reset to first principles when an interlocutor drifts, anchored to a four-line doctrine (useful, not made use of; refuse to choose; foreign policy begins at home; politics stops at the water's edge). 12 worldview items, 5 modes, 8 documented tensions, 14 calibration samples + 12 verbatim verified quote anchors with source URLs, and a 7-question grader checklist (pass ≥ 6/7). Built entirely from public material with an explicit ethical note that this is a derivative model of public voice, not impersonation.

→ View soul files

@VitalikButerin

Co-founder of Ethereum, mechanism-design generalist, originator of d/acc. Russian-born, Canadian, stateless by temperament. A fifteen-year public blog (vitalik.eth.limo) spanning cryptography, public-goods funding, governance, AI risk, and longevity.

What makes this one distinctive: a soul built around understatement — the spec's defining rule is that he almost never asserts without a hedge or a probability. Five modes (Cryptographer-Engineer / Mechanism Designer / d/acc Futurist / Movement Steward / Dry Online Poster), 8 documented tensions (built a giant financial asset but disdains speculation; most centralizing force in Ethereum while working to reduce his own influence), and signature rhetorical moves baked into STYLE.md: disambiguate first ("decentralization is three things"), name the failure mode before the solution, steelman then disagree, quantify the hedge, redirect price to purpose. 14 calibration samples + 4 verbatim quotes verified against his dated essays, a 12-prompt prediction test, and a 7-question grader checklist. Explicit ethics note: he refuses price calls and token endorsements because his words move markets — the model must not manufacture either.

→ View soul files

@steipete

Austrian iOS-dev-turned-agentic-engineering-builder. Founder of PSPDFKit (acquired), creator of OpenClaw 🦞, joined OpenAI in February 2026 to bring agents to everyone.

What makes this one distinctive: tool casing as identity signal (lowercase codex, capitalized OpenClaw), receipts-everywhere voice anchored to numbers / versions / named tools, and the lobster register ("the claw is the law" / 🦞) flagged as context-specific so forced lobster outside OpenClaw / single-user / local-first contexts is treated as a tell. Reproducible data pipeline: 47 blog posts, 16 README/VISION/AGENTS files, 8 podcast transcripts, 100 X posts via surf-ai MCP. Validated by automated weak-model test scoring 39/48 (3.25/4 PASS) on gpt-4o-mini via OpenRouter.

→ View soul files

In the Wild

Production deployments built on this methodology.

vgr_zirp — Ribbonfarm's resurrected oracle

A retrieval-augmented Q&A system that answers in Venkatesh Rao's intellectual voice, deployed at ribbonfarm.com. Built by the Ribbonfarm team using a modified soul.md approach as the persona layer over a RAG pipeline (Voyage embeddings → Pinecone → Claude Sonnet on Cloudflare Workers).

What's interesting about this implementation:

• LEXICON.md — a third persona file with top 50 high-confidence coinages + definitions, letting the model reference precise jargon without retrieval
• Empirically-derived topic clusters — 708 post summaries clustered into 15 topics rather than hand-authoring worldview sections (useful when the corpus is large)
• Era-by-era voice evolution in STYLE.md — captures how voice shifted over time, not just a snapshot

→ Writeup: ribbonfarm.com/vgr_zirp_tech · contraptions.venkateshrao.com

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.

See CONTRIBUTING.md for the full guide — structure, the merge bar, validation patterns, and the ethics note for public-figure souls.

Open a PR →

Aeon Token

SOUL.md is affiliated with the Aeon project and the AEON token.

Contract: 0xbf8e8f0e8866a7052f948c16508644347c57aba3

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 Aeon, Claude Code, OpenClaw, and any agent that can read markdown.