SOUL, MEMORY and USER -- optional context layer (legacy)
SOUL, MEMORY and USER are three optional Markdown files whose text can be added to the agent's system prompt (the hidden instructions it receives). Today only USER matters in practice: it holds a user's personal preferences ("answer in Italian", "I work in finance"), which users edit from Chat UI settings. This page is for administrators maintaining older installations and developers; new setups should use YAML profiles and Mnemos memory instead of SOUL and MEMORY.
The content of SOUL.md has been replaced by the YAML profiles system (config/profiles/*.yaml) with the fields instructions, skills, mcp_servers. The content of MEMORY.md has been replaced by Mnemos (native long-term memory, LTM) and SQL QueryMemory.
USER.md remains the only layer still active and recommended.
The code for SOUL and MEMORY still exists and is backward-compatible (by setting AION_SOUL_MEMORY_USER_SPLIT=1), but it is no longer the recommended path.
This page describes the additional layer of text that can be concatenated to the system prompt, in addition to what is defined in the config/profiles/*.yaml profiles. It does not replace the YAML: it enriches the prompt with Markdown content stored on the filesystem.
Relationship with YAML profiles
| What | Where | Status | Role |
|---|---|---|---|
| Agent profile | config/profiles/<slug>.yaml | Main | Name, description, instructions, skill list, MCP. It remains the main configuration and versionable in git. |
| SOUL | SOUL.md | Deprecated | Identity and guidelines. Replaced by instructions in the YAML profile. |
| MEMORY | MEMORY.md | Deprecated | Operational memory. Replaced by Mnemos (LTM) + SQL QueryMemory. |
| USER | USER.md | Active | Preferences for a single user. The only file layer still recommended. |
The profile slug coincides with the YAML file name without extension (e.g. generic_assistant from generic_assistant.yaml). It is the same value used in AgentProfile.slug and in ProfileMemoryBundle.
Activation
The whole mechanism is governed by an environment variable:
| Variable | Default in code | Effect |
|---|---|---|
AION_SOUL_MEMORY_USER_SPLIT | 0 | If 1, true or yes (case-insensitive), the backend reads the files and inserts them into the system prompt. If 0 (default) or absent, the prompt is constructed only from role + YAML instructions + skill block. |
Other useful parameters (see also .env.example in the root of the repository):
AION_PROFILE_STATE_DIR— root forMEMORY.md,USER.mdandSOUL.md"in data" (defaultdata/profiles).AION_MEMORY_FILE_MAX_CHARS,AION_USER_FILE_MAX_CHARS,AION_SOUL_FILE_MAX_CHARS— size limits in characters (validation on write and bundle).AION_ADMIN_MEMORY_TOKEN— if set, the HTTP routes/admin/profile-memory/*can requireAuthorization: Bearer <token>(seesrc/api/admin_profile_memory.py).
Enabling the split is a backward-compatibility feature. For new projects, use YAML profiles (instructions) and Mnemos (LTM) instead of SOUL and MEMORY.
Semantics of the three files
- SOUL (
SOUL.md) — Deprecated. Identity and long guidelines. Theinstructionsfield in the YAML profile does exactly the same thing, with significant advantages (versionable in git, validated by the schema, composable with skills and MCP). See Agent Profiles. - MEMORY (
MEMORY.md) — Deprecated. Profile-level shared memory. Replaced by Mnemos (LTM with notes, digests and hybrid full-text + semantic recall) and SQL QueryMemory (cache of validated SQL queries). See STM, LTM and QueryMemory Memory. - USER (
USER.md) — Active. Preferences and notes for a single user (same concept ofuser_idused by API/Chat UI). A separate file for each(profile_slug, user_id)pair.
Implementation of reading and paths: src/memory/memory_files.py. Prompt construction: AgentProfile.generate_system_prompt() in src/agent_profile.py.
Paths on disk
These paths are maintained for backward-compatibility. They apply only if AION_SOUL_MEMORY_USER_SPLIT=1.
SOUL
The system searches for the first existing file among:
config/profiles/<slug>/SOUL.md— if theconfig/profiles/<slug>/directory exists (profile "with folder").- Otherwise
data/profiles/<slug>/SOUL.md(underAION_PROFILE_STATE_DIR).
The write via admin API goes to:
config/profiles/<slug>/SOUL.mdif the profile folder exists;- otherwise
data/profiles/<slug>/SOUL.md(creating the directories if necessary).
Functions: soul_read_path(), soul_write_path() in memory_files.py.
MEMORY
Always:
<AION_PROFILE_STATE_DIR>/<slug>/MEMORY.md
(default:data/profiles/<slug>/MEMORY.md)
USER
For sanitized user:
<AION_PROFILE_STATE_DIR>/<slug>/<user_id>/USER.md
user_id is normalized by sanitize_user_id() in src/identity.py (safe characters for path). The actual value depends on the client: body/header user_id in POST /chat, or Chat user (see Identity and Chat Auth).
Order in the system prompt (split active)
This order applies only if AION_SOUL_MEMORY_USER_SPLIT=1 is explicitly enabled (legacy scenario).
With AION_SOUL_MEMORY_USER_SPLIT enabled, the order of the joined parts is:
- SOUL (file content only; if not empty, inserted as the first block).
# Role: <name>+instructionsfrom the YAML.- Skill section (
indexorfullmode according toAION_SKILL_SYSTEM_PROMPT_MODE). - If MEMORY is not empty → section with heading
## OPERATIONAL MEMORY (agent). - If USER is not empty → section
## USER PREFERENCES.
If the files do not exist or are empty, the relative parts add nothing: the behavior is equivalent to not having that layer.
What to use instead of SOUL and MEMORY
SOUL.md → YAML Profiles
The instructions field in the YAML profile (config/profiles/<slug>.yaml) does exactly the same thing as SOUL.md, but with significant advantages:
- Versionable in git (YAML file, not scattered markdown)
- Validated by the schema (
ProfileSchema) - Composable with skills and MCP servers
- Automatically loaded by the
ProfileManager
Example:
# config/profiles/my_profile.yaml
name: My Profile
instructions: |
You are an expert assistant for X.
Your tone is professional but friendly.
Follow these guidelines:
- ...
See Agent Profiles for full details.
MEMORY.md → Mnemos + QueryMemory
Mnemos (which replaced the earlier MemPalace MCP server) offers a much richer long-term memory:
- Notes (short durable facts) per user, project or global scope
- Digests (LLM-compressed summaries over blocks of notes)
- Hybrid recall (full-text search plus embeddings)
- Automatic extraction LLM post-turn, plus a nightly "dream" cycle that compresses and cleans up notes
See Mnemos.
SQL QueryMemory adds a cache for validated SQL/SELECT queries, separate from the PromQL system.
See STM, LTM and QueryMemory Memory for full details.
USER.md → Remains active
USER.md remains the only recommended file layer. It works as described on this page.
Runtime integration
get_agent(profile_name, session_id, user_id)(src/main.py) loads the profile and callsprofile.generate_system_prompt(user_id).- With active split,
ProfileMemoryBundle(profile.slug, user_id)is created andsnapshot()reads the three files. - The same
user_idis propagated where needed (MCP, context, etc.) — consistency with theUSER.mdpath.
For direct APIs: POST /chat accepts user_id in the JSON and/or the X-AION-User-Id header only in open mode or from the trusted BFF; with a chat token the token's user wins. See REST API and contract.
Management from Chat UI and REST API
- Interface:
chat-uisettings page managesUSER.mdper user. - API: prefix
/admin/profile-memory/—GET/PUT .../<slug>/users/<user_id>for USER instructions,GET .../<slug>/metafor user metadata and limits.
If AION_ADMIN_MEMORY_TOKEN is set, administrative requests can include the expected bearer token.
Memory Hub (/memory in the admin UI) instead concerns memory projects (SQL QueryMemory and Mnemos notes) — a separate concept from SOUL/MEMORY/USER; see STM, LTM and QueryMemory Memory.
What changes compared to "YAML only"
| Scenario | Effect |
|---|---|
| Split off (default) | None of the three files is read. The prompt is constructed only from role + YAML instructions + skill. |
| Split on | SOUL/MEMORY/USER are read and inserted into the prompt. Not recommended: use YAML profiles and Mnemos instead of SOUL and MEMORY. |
| Only USER active | Set AION_SOUL_MEMORY_USER_SPLIT=1 but leave SOUL.md and MEMORY.md empty/absent. |
References in the code
| File | Content |
|---|---|
src/agent_profile.py | generate_system_prompt(), condition on AION_SOUL_MEMORY_USER_SPLIT. |
src/memory/memory_files.py | ProfileMemoryBundle, BoundedMemoryFile, path for USER.md. |
src/api/admin_profile_memory.py | REST CRUD for USER.md preferences and meta routes. |
Related documents
- Agent Profiles — Replace SOUL.md with
instructionsin the YAML profile. - STM, LTM and QueryMemory Memory — Replace MEMORY.md with Mnemos (LTM) and SQL QueryMemory.
- Skills and system prompt — skill mode
index/fullin the same prompt. - Identity and Chat Auth —
user_id, login, alignment withUSER.md. - REST API —
POST /chatand system prompt construction. - Environment — overview of variables (cross-reference with
.env.example).