Skip to main content
“I told my agent something and it forgot.” “Which file is my agent’s brain?” “I edited SOUL.md — why doesn’t it know my name?” These questions all come down to the same thing: Mibyan is shaped by several markdown files, and each one has a different job. This page maps them all in one place. For depth on any of them, follow the links to Persistent Memory, Personality & SOUL.md, and Context Files.

​
The Master Table

One project context file per sessionOnly one project context type is loaded per session, first match wins: .mibyan.md → AGENTS.md → CLAUDE.md → .cursorrules. SOUL.md is always loaded independently as the agent identity — it is not part of that priority chain. See Context Files for the full list, including CLAUDE.md and .cursorrules compatibility.
A useful shorthand:
  • SOUL.md is who the agent is — if it should follow you everywhere, it belongs here.
  • USER.md is who you are — the agent maintains it for you.
  • MEMORY.md is what the agent has learned — it maintains this itself too.
  • AGENTS.md (or .mibyan.md) is what the project needs — if it belongs to a project, it belongs here.

​
”Why did it forget what I just said?”

Memory (MEMORY.md and USER.md) is injected into the system prompt as a frozen snapshot captured once at session start — when the agent saves something mid-session, the change is persisted to disk immediately but won’t appear in the system prompt until the next session starts. This is intentional: it preserves the LLM’s prefix cache for performance, and tool responses always show the live state, so nothing is lost — start a new session and the updated memory is there. Full details in How Memory Appears in the System Prompt.

​
Common Mix-Ups

​
”I put facts about myself in SOUL.md, but USER.md stayed empty”

SOUL.md and USER.md are separate systems that never feed each other. SOUL.md is a personality file you edit directly — it shapes tone and identity, and its content is injected verbatim as slot #1 of the prompt. USER.md is part of persistent memory and is written by the agent through the memory tool. If you want facts about yourself in USER.md, tell the agent (“remember that I prefer concise answers”) and it saves them — editing SOUL.md won’t populate memory, and memory entries won’t change the persona. Use SOUL.md for durable voice and personality guidance; leave preferences and profile facts to memory. See What should go in SOUL.md? and Two Targets Explained.

​
”I told it my name mid-session and it acted like it never heard it”

If the agent saved your name to memory, the save worked — check with the memory tool’s responses or mibyan journey list. What you’re seeing is the frozen-snapshot rule above: the system prompt doesn’t refresh mid-session, so the injected memory block still shows the session-start state. The agent can still use what you told it within the current conversation (it’s in the context), and the saved entry will be in the system prompt from the next session onward. The same applies to edits you make to SOUL.md or AGENTS.md while a session is running: context is assembled at session start, so restart the session to pick up changes.
Quick decision guide
  • Want to change how the agent talks? Edit ~/.mibyan/SOUL.md — Personality & SOUL.md.
  • Want the agent to remember a fact? Just tell it — it saves to memory itself. Persistent Memory.
  • Want to set project rules? Put an AGENTS.md (or .mibyan.md) in the project — Context Files.
  • Need a temporary personality change? Use /personality — it’s a session-level overlay, no file edits needed.
  • Persistent Memory — MEMORY.md, USER.md, the memory tool, capacity limits, write_approval
  • Personality & SOUL.md — SOUL.md content guidance, /personality presets, the prompt stack
  • Context Files — AGENTS.md, .mibyan.md, progressive discovery, security scanning