Persona files

Persona files are how you steer an agent: change the text, and you change the agent. They’re a small set of Markdown files in its workspace that define who it is, how it talks, what it’s allowed to do, and how it gets to know you.

They’re also the heart of every template, and the only template files that reach the agent.

The core files

IDENTITY.md

A short, durable self-description — the agent’s role, vibe, and a few defining traits. Think of it as the one-line “who am I” the agent carries everywhere.

SOUL.md

The fuller picture of the agent’s identity: its communication style, guidelines, working rhythms, the kind of work it produces, and its tone. This is where most of a persona’s personality lives. If you want an agent to be more concise, more cautious, or more opinionated, this is the file to shape.

AGENTS.md

The agent’s operating manual — the practical rules it follows every session: how it uses memory, what it can do freely versus what it should ask about first, its hard boundaries, and how it behaves in group conversations. This file keeps behaviour consistent and safe across sessions.

USER.md

A profile of you — the person or team the agent works with. It starts mostly empty and fills in as the agent learns about your context, preferences, and goals.

BOOTSTRAP.md

A first-conversation script, tailored to the agent’s role. On its first run, the agent uses this to interview you about how your team works — your standards, conventions, and priorities — and folds what it learns into its memory. Each built-in role has its own hand-written bootstrap, so a Product Manager asks about your product playbook while a DevOps agent asks about your infrastructure. Some roles also use it to propose their recurring jobs for you to confirm.

How the files work together

Every session, an agent reads its identity and operating files first, so it starts as the same, consistent version of itself. It’s a fresh instance each time; continuity comes from these files plus its memory. That’s why editing them is the most direct way to steer an agent — you’re editing the thing it reads to remember who it is.

Persona files also connect to memory. As an agent learns durable facts about your team, they survive across conversations without any work from you. See Agent memory for how recall works.

Editing a persona

You can shape a persona at two points:

• In a template — persona files are part of the snapshot, and each change creates a new version.
• On a running agent — editing the files in its workspace changes that agent only, not the template it came from. Alfe seeds persona files only when they’re missing, so your edits aren’t overwritten.

A few tips:

• Keep IDENTITY.md and SOUL.md focused on who the agent is, and AGENTS.md on how it operates. Mixing them makes both harder to tune.
• Small, specific edits work best. “Prefer bullet points over paragraphs” is easier for an agent to follow than a vague “be clearer”.
• Don’t put secrets or credentials in persona files — they’re plain workspace files, not a vault. Connect credentials through integrations instead.

Next steps

• Use a template — install an agent whose persona is already written for a role.
• Publish and fork — package a persona you’ve refined into a shareable template.