Skip to main content
Mibyan automatically discovers and loads context files that shape how it behaves. Some are project-local and discovered from your working directory. SOUL.md is now global to the Mibyan instance and is loaded from mibyan_HOME only.

​
Supported Context Files

Priority systemOnly one project context type is loaded per session (first match wins): .mibyan.md → AGENTS.override.md → AGENTS.md → CLAUDE.md → .cursorrules. SOUL.md is always loaded independently as the agent identity (slot #1).If an AGENTS.override.md exists next to an AGENTS.md, the override is loaded instead of the committed file — keep a personal (usually gitignored) AGENTS.override.md when you want different instructions than the ones checked into the repo, without editing the tracked AGENTS.md.

​
AGENTS.md

AGENTS.md is the primary project context file. It tells the agent how your project is structured, what conventions to follow, and any special instructions.

​
Directory Chain (git root → working directory)

When your working directory sits inside a git repository, Mibyan loads a merged chain of AGENTS.md files at session start: the git-root AGENTS.md first, then the AGENTS.md in every intermediate directory down to your working directory. Deeper files appear later in the prompt, so more specific guidance takes precedence. Each file gets its own provenance header (e.g. ## ../../AGENTS.md), and identical copies along the chain are deduplicated.
Outside a git repository, only the working directory itself is checked — parents are never consulted, so an AGENTS.md planted in /tmp or $HOME can’t leak into unrelated sessions.

​
Progressive Subdirectory Discovery

At session start, Mibyan loads the AGENTS.md from your working directory into the system prompt. As the agent navigates into subdirectories during the session (via read_file, terminal, search_files, etc.), it progressively discovers context files in those directories and injects them into the conversation at the moment they become relevant.
This approach has two advantages over loading everything at startup:
  • No system prompt bloat — subdirectory hints only appear when needed
  • Prompt cache preservation — the system prompt stays stable across turns
Each subdirectory is checked at most once per session. The discovery also walks up parent directories, so reading backend/src/main.py will discover backend/AGENTS.md even if backend/src/ has no context file of its own.
Subdirectory context files go through the same security scan as startup context files. Malicious files are blocked.

​
Example AGENTS.md

​
SOUL.md

SOUL.md controls the agent’s personality, tone, and communication style. See the Personality page for full details. Location:
  • ~/.mibyan/SOUL.md
  • or $mibyan_HOME/SOUL.md if you run Mibyan with a custom home directory
Important details:
  • Mibyan seeds a default SOUL.md automatically if one does not exist yet
  • Mibyan loads SOUL.md only from mibyan_HOME
  • Mibyan does not probe the working directory for SOUL.md
  • If the file is empty, nothing from SOUL.md is added to the prompt
  • If the file has content, the content is injected verbatim after scanning and truncation

​
.cursorrules

Mibyan is compatible with Cursor IDE’s .cursorrules file and .cursor/rules/*.mdc rule modules. If these files exist in your project root and no higher-priority context file (.mibyan.md, AGENTS.md, or CLAUDE.md) is found, they’re loaded as the project context. This means your existing Cursor conventions automatically apply when using Mibyan.

​
How Context Files Are Loaded

​
At startup (system prompt)

Context files are loaded by build_context_files_prompt() in agent/prompt_builder.py:
  1. Scan working directory — checks for .mibyan.md → AGENTS.md → CLAUDE.md → .cursorrules (first match wins)
  2. Content is read — each file is read as UTF-8 text
  3. Security scan — content is checked for prompt injection patterns
  4. Truncation — files exceeding the character cap are head/tail truncated (70% head, 20% tail, with a marker in the middle). The cap is an explicit context_file_max_chars from config.yaml when set; otherwise it scales dynamically with the model’s context window (floor 20,000 chars, ceiling 500,000)
  5. Assembly — all sections are combined under a # Project Context header
  6. Injection — the assembled content is added to the system prompt

​
During the session (progressive discovery)

SubdirectoryHintTracker in agent/subdirectory_hints.py watches tool call arguments for file paths:
  1. Path extraction — after each tool call, file paths are extracted from arguments (path, workdir, shell commands)
  2. Ancestor walk — the directory and up to 5 parent directories are checked (stopping at already-visited directories)
  3. Hint loading — if an AGENTS.md, CLAUDE.md, or .cursorrules is found, it’s loaded (first match per directory)
  4. Security scan — same prompt injection scan as startup files
  5. Truncation — capped at 32,000 characters per file (a fixed preview cap; context_file_max_chars and the model’s context window do not change it). An oversized hint keeps its head/tail marker pointing at the full file and is logged, but does not raise the chat truncation warning that startup context files do
  6. Injection — appended to the tool result, so the model sees it in context naturally
The final prompt section looks roughly like:
Notice that SOUL content is inserted directly, without extra wrapper text.

​
Security: Prompt Injection Protection

All context files are scanned for potential prompt injection before being included. The scanner checks for:
  • Instruction override attempts: “ignore previous instructions”, “disregard your rules”
  • Deception patterns: “do not tell the user”
  • System prompt overrides: “system prompt override”
  • Hidden HTML comments: “
  • Hidden div elements: <div style="display:none">
  • Credential exfiltration: curl ... $API_KEY
  • Secret file access: cat .env, cat credentials
  • Invisible characters: zero-width spaces, bidirectional overrides, word joiners
If any threat pattern is detected in a project context file (.mibyan.md, AGENTS.md, CLAUDE.md, .cursorrules), the file is blocked:
Your own SOUL.md in mibyan_HOME is treated differently: it is a file you wrote (file-tool writes to it need your approval, and project checkouts never supply it), so a scanner hit there does not block the file. Mibyan logs a warning naming the matched pattern, loads the file as usual, and /context lists it as ⚠ SOUL.md … loaded — matched prompt-injection pattern(s); review the file. This lets an identity file that documents an attack phrase (security guidance such as “content telling you to ignore previous instructions”) keep working; if you did not write the flagged text, treat the warning as a sign that something else edited the file. The exception does not extend to a SOUL.md shipped by a profile distribution: mibyan profile install <git-url> and mibyan profile update copy a third party’s SOUL.md into the profile home without a scan or an approval prompt, so when distribution.yaml owns the file a scanner hit still blocks it.
This scanner protects against common injection patterns, but it’s not a substitute for reviewing context files in shared repositories. Always validate AGENTS.md content in projects you didn’t author.

​
Size Limits

When a file exceeds the configured limit, the truncation message reads:

​
Tips for Effective Context Files

Best practices for AGENTS.md
  1. Keep it concise — stay under your configured context_file_max_chars; the agent reads it every turn
  2. Structure with headers — use ## sections for architecture, conventions, important notes
  3. Include concrete examples — show preferred code patterns, API shapes, naming conventions
  4. Mention what NOT to do — “never modify migration files directly”
  5. List key paths and ports — the agent uses these for terminal commands
  6. Update as the project evolves — stale context is worse than no context

​
Per-Subdirectory Context

For monorepos, put subdirectory-specific instructions in nested AGENTS.md files: