Profiles
A profile is the bot definition Nakama runs for a session.
It answers one practical question: which bot should respond, and how should it behave?
Profiles belong to an organization. Switching orgs in the dashboard shows only that org's bots.
Default profile per organization
Nakama does not share one global default bot across every org.
When an organization is created — including the first org at install — Nakama automatically:
- Creates one default profile for that org (
isDefault: true) - Assigns the standard builtin tool set (web search, file tools, email, and the rest)
- Initializes its soul directory on disk
That profile is named Default Bot and gets a unique id (not a fixed string like default).
| What | Behavior |
|---|---|
| Default profile | Exactly one per org, marked with isDefault |
| Super bot | Not auto-created; platform admin may add a profile with isSuper: true if needed |
| Additional orgs | Each gets its own default profile and isolated on-disk data |
If a session or channel config omits a profile id — or names one that does not exist in the active org — Nakama falls back to that org's default profile.
New custom profiles
Platform admins create extra profiles inside the active org. Each new profile gets its own soul directory and starts with read_file, write_file, edit_file, search_files, knowledge_base_search, and update_profile_memory when those builtins are available. Assign more tools, MCP servers, and skills from the dashboard.
Super Bot can also create profiles from chat. For profile-creation requests, it uses a Super Bot-only bundled skill that guides soul-file generation, keeps MEMORY.md empty, and uses the current tool inventory to recommend a small relevant starter set.
What a profile contains
| Field | What it means |
|---|---|
id | Stable unique profile id |
name | Human-friendly label shown in the UI |
model | Optional model selection for this profile |
systemPrompt | Base instructions stored in the database |
isSuper | Marks the profile as a super profile with elevated behavior |
isDefault | Marks the org's default profile used when none is specified |
tools | Builtin or custom tools the profile is allowed to use |
mcpServers | MCP servers available to the profile |
skills | Reusable instructions assigned to the profile |
hasAvatar | Whether the profile has a custom avatar |
soulActive | Whether soul files are present and active |
What a good profile usually represents
One profile should map to one clear purpose. Create another profile when you need different instructions, tools, tone, or knowledge.
How profiles affect replies
When a chat runs with a profile, Nakama builds the agent context in this order:
- Start with the profile's
systemPrompt - If soul files exist, compose them into the main system prompt
- Append the assigned skills catalog
- Append the knowledge base catalog
- Expose only the tools allowed for that profile
So a profile is not just a name. It controls both:
- How the agent behaves
- What the agent is allowed to do
For the full prompt assembly flow, see Agent prompt.
Soul vs system prompt
Profiles support two layers of instruction:
| Layer | Best for |
|---|---|
systemPrompt | Quick base instructions stored in the database |
| Soul files | Richer identity, style, operating rules, and memory on disk |
Soul files, avatars, knowledge-base documents, artifacts, and profile-scoped skills all live under an org-scoped path:
~/.nakama/orgs/{orgId}/profiles/{profileId}/Supported soul files:
| File | Purpose |
|---|---|
SOUL.md | Identity |
STYLE.md | Writing voice |
INSTRUCTIONS.md | Operating rules |
MEMORY.md | Continuity across sessions |
Profile-scoped skills are stored at:
~/.nakama/orgs/{orgId}/profiles/{profileId}/skills/Artifacts saved by the agent are stored at:
~/.nakama/orgs/{orgId}/profiles/{profileId}/artifacts/If you want richer personality and clearer long-term behavior, use soul files. If you only need a quick setup, the stored systemPrompt may be enough.
Platform-admin data exports include these org/profile workspaces as part of the full Nakama data-root ZIP. Restoring an export replaces the local data root after preview and confirmation; it is not a per-profile merge.
Default Bot soul stack
New organizations receive a pre-filled soul stack for Default Bot — identity, voice, operating rules, and memory — not blank placeholders. Customize files in the dashboard Prompt tab. The database systemPrompt field is for optional operational overrides when it differs from SOUL.md; fresh installs leave it empty so identity lives in soul files alone.
Existing profiles keep customized soul files. On server startup, ensureSoulScaffolded() fills missing or empty soul files and upgrades legacy placeholder SOUL.md content (the old # Your Name scaffold) to the current Default Bot template. Customized souls are not overwritten.
Model selection
Each profile can optionally select its own model.
| Field | Meaning |
|---|---|
model | Uses a specific model for this profile instead of the workspace default |
Knowledge base and memory
Profiles keep their own context on disk under the org-scoped profile directory:
- Knowledge base documents for searchable reference material
- Inherited knowledge sources for shared product references, such as the Nakama documentation
MEMORY.mdfor facts and continuity saved by the agent- Artifacts for persistent reports, generated files, images, PDFs, and other saved outputs
This data is isolated per org and per profile. Two orgs never read or write the same directory, even if profile ids happen to match.
Each profile also sees the default Nakama documentation source in the Knowledge tab:
https://ahmadrosid.github.io/nakama/When a user asks about Nakama setup, profiles, tools, orgs, integrations, API, or troubleshooting, the agent can use that inherited source with web_fetch or web_search before answering detailed product questions.
Multi-tenant behavior
Profiles are tenant-owned data inside an organization:
| Rule | Detail |
|---|---|
| Listing | GET /v1/profiles returns only profiles for the active org |
| Lookup | Requesting another org's profile id returns not found |
| Sessions | Bind to one profile within the active org |
| Tool access | Scoped per profile |
| Mutations | Platform-admin only; org members chat with org profiles |
Org admins manage members, not profiles. Platform admins need an active org context when creating or editing profiles.
When to create multiple profiles
Create separate profiles when you need different:
- Agent identities
- Safety or operating rules
- Tool access
- Knowledge bases
- Models
Next steps
- Builtin tools — what each profile can do
- MCP servers — extend a profile with external tools
- Multi-tenancy — who can manage profiles and members