Roles & Personality

A Role gives Anyy a stable assistant identity and working style. Use Roles when one Profile needs distinct modes—such as personal planning, research, or technical writing—while intentionally sharing the same data and capabilities.

Role and Profile Boundaries

Every Role in one Profile shares its:

• Workspace, database, and session boundary;
• USER.md and MEMORY.md memory;
• models, Tools, Skills, and MCP configuration;
• Channels and Cron jobs; and
• credentials and approvals.

Create a separate Profile when any of those resources must remain isolated.

Create a Role in Dashboard

1. Open Dashboard → Roles.
2. Select New Role.
3. Enter a permanent ID such as scribe.
4. Optionally enter a display name such as Scribe.
5. Select Create role.
6. Write and save non-empty Soul content to complete onboarding.

Role IDs use lowercase letters, digits, underscores, and hyphens, and begin with a letter or digit. The ID becomes part of the Role's storage path and cannot be renamed later; the display name can change.

The CLI equivalent is:

anyy role create scribe --display-name "Scribe"

Let Anyy Draft the First Soul

A newly created Role remains in pending onboarding until non-empty Soul content is saved. Instead of writing it alone, start a new session with that Role and describe the identity you want:

anyy chat --role scribe "Help me define this Role as a concise technical writing partner."

While onboarding is pending or active, the session can use role_onboarding_complete to propose final SOUL.md content. Anyy shows an approval before writing. Approving writes only that Role's Soul, marks onboarding completed, records Audit evidence, and removes the onboarding tool from later sessions. Rejecting leaves the Role incomplete.

The onboarding tool does not change the Role ID or display name, and it does not create a separate identity file. You can always complete the same process by saving Soul directly in Dashboard.

Write a Good Soul

Soul is Markdown that defines durable identity and behavior. Include only guidance that should apply across many tasks:

• purpose and audience;
• communication style;
• recurring priorities and decision principles;
• persistent boundaries; and
• how uncertainty should be handled.

Keep one-time requests, source material, and task instructions in the prompt, Workspace, or a Skill. Never put passwords, API keys, or other secrets in Soul.

Example:

# Research Partner

Help me compare evidence and expose uncertainty.
Prefer primary sources, concise tables, and explicit assumptions.
Do not turn an unresolved hypothesis into a fact.

Apply a local Soul file from the CLI:

anyy role update research --soul-file ./research-soul.md

Keep Soul small

Write the minimum durable guidance that changes how the Role should work. Long checklists consume context on every turn and are harder to keep consistent.

Select and Edit a Role

Open a Role in Dashboard to:

• select Use and make it the Profile default;
• edit its Soul;
• change its display name; or
• review its ID, onboarding state, and Soul path.

From the CLI:

anyy role use research
anyy role get research
anyy role list

Use --home PATH to target another Anyy Home and --json when a program needs structured output.

The selected Role is used when a new session does not request another Role explicitly. Choose a Role for one new CLI conversation with:

anyy chat --role research "Compare these two proposals."

--role applies only when creating a session and cannot be combined with --session. Existing sessions keep their original Role identity.

The base default Role is always present. You can edit its Soul, but cannot rename or delete it.

Archive a Role

A non-base Role can be deleted from active use only when it is not selected and no sessions or scheduled jobs reference it. Switch the Profile default and remove or update those references first.

anyy role delete research

The Role record is archived rather than returned to the active catalog. Use anyy role list --include-archived when you need to inspect archived records. Archiving a Role does not delete shared Profile memory, Workspace files, Channels, Skills, or other Roles.

Role, Profile, and Session

Concept	Use it for
Profile	Isolated Anyy home, configuration, data, and credentials
Role	Stable assistant identity and Soul inside a Profile
Session	One conversation, its history, and selected Role/model state

Changing the default Role does not rewrite existing sessions. Start a new session when you want the new identity to apply cleanly.

Prefer a few meaningful Roles

Create a Role only when identity and durable operating principles truly differ. Use Skills for repeatable procedures and prompts for one-off tasks.

Troubleshooting

Problem	Fix
Role ID is rejected	Use lowercase letters, digits, _, or -, beginning with a letter or digit
New Role shows incomplete onboarding	Save non-empty Soul content
Chat proposes a Soul change	Review the full onboarding approval; it is the write boundary for SOUL.md
Role cannot be archived	Select another default and remove active Session or Cron references
New conversation uses the wrong identity	Confirm the default Role, or pass --role ROLE_ID when creating it
You need private memory or credentials	Create a separate Profile instead of another Role