Context Files

Context files are local files that shape Anyy's prompt context. In the current runtime, the primary user-editable context file is the selected role's SOUL.md.

Project files such as README.md, source files, notes, and repo instructions are not automatically swept into every turn. Bring them in explicitly with Context References, file tools, or skills.

Supported Files

File	Scope	Loaded as
<home>/SOUL.md	Default role identity	Stable role identity context.
<home>/roles/<role_id>/SOUL.md	Named role identity	Stable role identity context for that role.
<home>/USER.md	Profile memory	Persistent memory context when memory is available.
<home>/MEMORY.md	Profile memory	Assistant notes and durable environment/project memory.

USER.md and MEMORY.md are covered in Persistent Memory. This page focuses on identity and explicit context-file behavior.

SOUL.md

SOUL.md defines Anyy's role persona, tone, boundaries, and interaction style. It is not a provider identity file and does not grant tool permissions.

Default role:

<home>/SOUL.md

Named role:

<home>/roles/<role_id>/SOUL.md

For a new profile, Anyy creates an empty SOUL.md sentinel and selects the default role. A named role is stored under roles/<role_id>/SOUL.md.

If a named role has no usable SOUL.md, prompt assembly falls back to the default role's SOUL.md. The default role never uses roles/default/SOUL.md.

Loading Rules

Each turn builds a prompt from stable and per-turn sources. Role identity is part of the stable prompt. It is assembled before runtime capabilities, skills, memory, and the recent transcript.

Anyy loads role identity through these rules:

Rule	Behavior
Selected session role	Existing sessions keep their role. Changing the profile default role does not rewrite old sessions.
New local session	Uses the profile default_role pointer, falling back to default.
Missing named-role file	Falls back to the default role identity.
Empty file	Adds no custom persona text for that file.
Large file	Truncates to the role identity character limit and adds a truncation marker.

Role files are read as local profile files. Symlinked or sensitive role paths are rejected and fall back instead of leaking the target.

What Is Not Auto-Loaded

Anyy does not currently auto-load every repository instruction file into resident sessions. Do not assume these files are present in the model context just because they exist in a project:

File	Current behavior
AGENTS.md	Not a resident runtime auto-load source in this build. Reference it explicitly when needed.
CLAUDE.md	Not used as an Anyy identity source.
.cursorrules	Not a built-in Anyy context source.
Project SOUL.md	Not probed from the working directory. Only role identity paths under the profile home are used.

Use @file:AGENTS.md, @folder:docs, file tools, or a skill when the current turn needs project-local instructions.

Safety

Role identity text is treated as user-controlled local content. Anyy applies basic safety checks before including it:

Check	Effect
Sensitive path checks	Refuses .env, SSH keys, token/credential-like paths, and similar sensitive locations.
Symlink checks	Refuses symlinked role identity files.
Prompt-injection markers	Drops role text containing obvious instruction override or secret-exfiltration markers.
Unicode cleanup	Converts invalid UTF-8 and rejects invisible control markers used in prompt attacks.

SOUL.md can set voice and preferences, but it cannot override user instructions, tool governance, approvals, ChangePlans, audit, or the requirement that the assistant identifies as Anyy.

Editing

Use the role CLI for repeatable edits:

anyy role update default --soul-file ./SOUL.md
anyy role create research --display-name "Research"
anyy role update research --soul-file ./research.SOUL.md
anyy role use research

The dashboard's Roles page can also create roles, select the active role, and edit a role's SOUL.md.

Best Practices

• Keep SOUL.md about identity, tone, boundaries, and collaboration style.
• Do not put API keys, local secrets, or credential paths in it.
• Do not put project-specific command lists in role identity. Use skills or explicit context references for workflow knowledge.
• Keep the file short enough to read every turn.

For role lifecycle details, see Roles.