Context Files

Fabric 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 Fabric instance and is loaded from FABRIC_HOME only.

Supported Context Files

File	Purpose	Discovery
.fabric.md / FABRIC.md	Canonical Fabric project instructions (highest priority)	Nearest file from CWD through the git root
AGENTS.md	Project instructions, conventions, architecture	CWD at startup + subdirectories progressively
CLAUDE.md	Claude Code context files (also detected)	CWD at startup + subdirectories progressively
SOUL.md	Global personality and tone customization for this Fabric instance	FABRIC_HOME/SOUL.md only
.cursorrules	Cursor IDE coding conventions	CWD only
.cursor/rules/*.mdc	Cursor IDE rule modules	CWD only

Priority system

Only one project context type is loaded at startup (first match wins): Fabric project file → AGENTS.md → CLAUDE.md → .cursorrules. For Fabric project files, the nearest directory wins; within that directory the name order is .fabric.md → FABRIC.md. SOUL.md is loaded independently as the agent identity (slot #1).

AGENTS.md

AGENTS.md is the portable project context file shared by Fabric and other coding agents. It tells the agent how your project is structured, what conventions to follow, and any special instructions.

Progressive Subdirectory Discovery

At session start, Fabric 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.

my-project/
├── AGENTS.md              ← Loaded at startup (system prompt)
├── frontend/
│   └── AGENTS.md          ← Discovered when agent reads frontend/ files
├── backend/
│   └── AGENTS.md          ← Discovered when agent reads backend/ files
└── shared/
    └── AGENTS.md          ← Discovered when agent reads shared/ files

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.

info

Subdirectory context files go through the same security scan as startup context files. Malicious files are blocked.

Example AGENTS.md

# Project Context

This is a Next.js 14 web application with a Python FastAPI backend.

## Architecture
- Frontend: Next.js 14 with App Router in `/frontend`
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
- Database: PostgreSQL 16
- Deployment: Docker Compose on a Hetzner VPS

## Conventions
- Use TypeScript strict mode for all frontend code
- Python code follows PEP 8, use type hints everywhere
- All API endpoints return JSON with `{data, error, meta}` shape
- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)

## Important Notes
- Never modify migration files directly — use Alembic commands
- The `.env.local` file has real API keys, don't commit it
- Frontend port is 3000, backend is 8000, DB is 5432

SOUL.md

SOUL.md controls the agent's personality, tone, and communication style. See the Personality page for full details.

Location:

• ~/.fabric/SOUL.md
• or $FABRIC_HOME/SOUL.md if you run Fabric with a custom home directory

Important details:

• Fabric seeds a default SOUL.md automatically if one does not exist yet
• Fabric loads SOUL.md only from FABRIC_HOME
• Fabric 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

Fabric 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 Fabric project file, AGENTS.md, or CLAUDE.md is found, they're loaded as the project context.

This means your existing Cursor conventions automatically apply when using Fabric.

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 project context — searches the CWD and then its parents through the git root for the nearest .fabric.md or FABRIC.md; if none exists, checks AGENTS.md → CLAUDE.md → .cursorrules in the CWD (first type 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 — sources exceeding the resolved dynamic or explicitly configured cap are head/tail truncated (70% head, 20% tail, with a marker in the middle)
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 8,000 characters per file
6. Injection — appended to the tool result, so the model sees it in context naturally

The final prompt section looks roughly like:

# Project Context

The following project context files have been loaded and should be followed:

## AGENTS.md

[Your AGENTS.md content here]

## .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

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: <!-- ignore instructions -->
• 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, the file is blocked:

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

warning

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

Limit	Value
Max chars per startup context source	Explicit context_file_max_chars, otherwise a model-window-aware cap (20,000 floor; 500,000 ceiling)
Head truncation ratio	70%
Tail truncation ratio	20%
Truncation marker	10% (shows char counts and suggests using file tools)

Without an explicit setting, Fabric budgets roughly 6% of the model context window using a four-characters-per-token estimate. That keeps the historical 20,000-character floor for small or unknown windows and scales up for larger-context models. Setting context_file_max_chars pins the exact limit and overrides the dynamic calculation.

When a source exceeds the resolved limit, the truncation message reads:

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

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:

<!-- frontend/AGENTS.md -->
# Frontend Context

- Use `pnpm` not `npm` for package management
- Components go in `src/components/`, pages in `src/app/`
- Use Tailwind CSS, never inline styles
- Run tests with `pnpm test`

<!-- backend/AGENTS.md -->
# Backend Context

- Use `poetry` for dependency management
- Run the dev server with `poetry run uvicorn main:app --reload`
- All endpoints need OpenAPI docstrings
- Database models are in `models/`, schemas in `schemas/`