Lesson 879 of 2116
Your First Soul: A Ten-Minute Hello World
A minimal soul, a personality, a first message, a peek at memory. The point is not the soul — the point is feeling how OpenClaw thinks. Step 1 — Define the soul A soul lives in a folder, typically under `souls/`, and is defined by a small file that names it, gives it a persona, and points at the model it should use.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1What we are about to build
- 2soul definition
- 3persona
- 4memory inspection
Concept cluster
Terms to connect while reading
Section 1
What we are about to build
A soul named Ada whose only job is to be a thoughtful, slightly skeptical reading companion. We will give her a persona, send her one message, look at what landed in her memory, send a second message that references the first, and confirm she remembers. Total time: under ten minutes. Total code: about thirty lines.
Step 1 — Define the soul
A soul lives in a folder, typically under `souls/`, and is defined by a small file that names it, gives it a persona, and points at the model it should use. The persona becomes the system prompt at every turn. Keep the first one short — three or four sentences — because long personas mostly confuse small models.
A complete soul file — name, role, model, persona, memory shape. The defaults handle everything else.
# souls/ada.yaml — the simplest soul that does anything interesting
name: Ada
role: Reading companion
model: qwen3:8b
persona: |
You are Ada, a thoughtful, slightly skeptical reading companion.
You ask one good follow-up question per turn.
You never summarize back to the user; you press on what is unclear.
You remember what the user has been reading across sessions.
memory:
short_term: rolling-window
long_term: vector-store
retention: 30dStep 2 — Send the first message
Single command, single turn. The soul stays loaded; the memory is now non-empty.
# Load the soul and send a first turn
openclaw chat ada "I just started reading 'The Power Broker'."
# Ada replies — likely with a question, since that is her persona.
# Behind the scenes, OpenClaw has stored the user message and her
# response into Ada's long-term memory.Step 3 — Inspect the memory
This is the part most agentic frameworks hide. OpenClaw makes it cheap to look at what your soul actually remembers, which is the only way to debug behavior later.
Memory is data, not magic. Read it, search it, eventually edit it — the same way you would a database.
# Show recent memory entries for this soul
openclaw memory ada --tail 10
# Output is roughly:
# [user] I just started reading 'The Power Broker'.
# [ada] What pulled you toward Caro after all these years?
# [system-note] Topic: 'The Power Broker' (Caro). Established 2026-04-27.
# Search memory by keyword
openclaw memory ada --search "Caro"Step 4 — Confirm she remembers
The proof that souls earn their name: state survives across processes.
# Quit the chat. Wait. Open a new terminal. Run again.
openclaw chat ada "What were we just talking about?"
# Ada should reference 'The Power Broker' without being told again.
# That is persistence — the part Ollama-alone cannot do.Try it: build your own ten-minute soul
- 1Pick a role you actually want a companion for — code reviewer, writing partner, research note-taker, gym log analyst
- 2Write a persona in under five sentences; describe the tone, not the worldview
- 3Save it as `souls/<name>.yaml` and run `openclaw chat <name>`
- 4Send three messages on three different days
- 5Run `openclaw memory <name> --tail 20` and look at what landed — adjust the persona if the memory pattern is wrong
Key terms in this lesson
The big idea: a soul is just a YAML file plus a persona plus memory you can actually see. Once you have shipped one, every later soul is a variation on the same shape.
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “Your First Soul: A Ten-Minute Hello World”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 10 min
Spaces: Building Team Knowledge Bases In Perplexity
Spaces are Perplexity's project containers — system prompts, files, and shared chat history. They turn the search engine into a research workspace.
Creators · 10 min
The CLAUDE.md File: Project Persona And Rules
CLAUDE.md is how you tell Claude Code what your project values, what your team's conventions are, and what it should never do. It is the single highest-leverage config you write.
Creators · 9 min
What Perplexity Is: Search-Augmented LLM, Not A Chatbot
Perplexity is built around the idea that every answer should cite its sources. Treating it like ChatGPT misses the point — and the reliability gap that comes with it.