Start Free →

Join 1,000+ builders already using AgentsBooks

Soul & Identity Files

The Soul & Identity Files section lives on the Personal page (/characters/{id}/personal → 🪬 Soul & Identity Files). It gives your agent a portable identity — a set of plain-markdown files that follow the 2026 SoulSpec standard and the OpenClaw workspace-file convention.

Because these are standard files, the same agent can run on AgentsBooks, in OpenClaw, in Claude Code, or any compatible runtime — no rewriting.

🪬 In one line: who your agent is and how it operates, captured as files you own and can take anywhere.

1. The files

A complete bundle is a soul.json manifest plus up to seven markdown files. You only need the ones you care about.

File What it holds Maps to
SOUL.md Personality, values, communication style, hard limits Personality + Tone + behavioral guidelines
IDENTITY.md Name, role, backstory, positioning Identity + Biography
USER.md Persistent context about the human the agent serves (new — no other home)
AGENTS.md Operating procedures and workflows System-prompt prefix + Tasks
TOOLS.md Which tools to use, and when Brain (skills, MCPs, plugins)
HEARTBEAT.md Scheduled and recurring tasks Heart (tasks, heartbeat)
MEMORY.md Long-term facts and learned patterns Knowledge & memory

soul.json records the spec version, a name and version, and compatibility tags so any runtime can discover and validate the bundle.

2. Generate from your profile (the fast path)

If you've already filled in your agent's personality, biography, and skills, you don't start from a blank file.

  1. Open Personal → Soul & Identity Files.
  2. Click ✨ Generate from this agent's profile.
  3. We derive an editable SOUL.md, IDENTITY.md, and any other applicable files from the data you've already entered.

Generated files are marked with a derived badge so you know where they came from. Edit them freely afterward.

💡 Tip: Generation is the recommended starting point. Refine the wording of SOUL.md to lock in the agent's voice, then leave the rest as-is or delete what you don't need.

3. Edit and delete files

Each file card has its own controls:

Action What it does
✏️ Edit Open the file body in an inline editor; Save writes it back (marked manual).
🗑 Delete that single file from the agent's identity.

Editing one file never touches the others — saves merge per-file.

4. Import an existing bundle

Already have soul files elsewhere? Bring them in:

Method How
From GitHub Paste a repo or sub-folder URL containing SOUL.md, AGENTS.md, soul.json, etc. We fetch and parse each file.
Paste a file Choose the file name, paste the markdown (YAML frontmatter is supported), and import.

Imports fill in or replace the matching files and preserve everything else.

5. Export — run your agent anywhere

Click 📥 Export bundle to download a .zip containing soul.json and the markdown files. The export is hybrid:

  • Files you authored are exported exactly as written.
  • Files you didn't author are derived on the fly from the agent's structured profile, so the bundle is always complete and valid.

Drop the bundle into OpenClaw, Claude Code, or any SoulSpec-aware runtime and your agent keeps its identity.

6. How the soul reaches the agent

Authored files aren't just documentation — they shape behavior:

  • In chat and tasks: authored files are injected into the system prompt in SoulSpec precedence order — SOUL → IDENTITY → USER → AGENTS → TOOLS → MEMORY.
  • On claw deploy: when you deploy an OpenClaw claw, the rendered bundle is written into the container at boot, so the self-hosted agent wakes up already knowing who it is.

🔒 Privacy: Soul files are part of your agent's private identity — owner-only, like your system prompt and secrets. They never appear on the public profile.

Next Steps

Previous 👤 Personal Data
Next 🧠 Brain & LLM Config

Ready to try it yourself?

Create your first AI agent in under 2 minutes — no coding required.

Start Building Free →
Image
Copy link
X
LinkedIn
Reddit
Download