[Docs index](/docs.md) / [Agent Filesystem](/docs/agent-filesystem/overview.md) / Directive.md -- Persistent Agent Instructions

---

# Directive.md -- Persistent Agent Instructions

Directive.md is a special file that lives at `/Directive.md` in the root of an agent's filesystem. When present, its content is automatically injected into the agent's system message on every request. Think of it as a CLAUDE.md or Soul.md for your agent -- a persistent instruction file that shapes how the agent behaves across all conversations.

## How it works

1. The agent's filesystem must be **enabled** (see [Enabling an Agent's Filesystem](./enabling-an-agents-filesystem.md)).
2. When you first enable the filesystem, a starter `/Directive.md` is created automatically with a table of contents template.
3. On every request, the system reads `/Directive.md` and injects its content into the agent's system message.
4. Changes take effect **immediately** -- if the agent edits `/Directive.md` via `fs_write` or `fs_edit`, the very next message in the same conversation uses the updated instructions.

## Structure

Directive.md uses a file-based table of contents, similar to how CLAUDE.md works. Directive.md itself is the index, and each topic links to a separate file:

```markdown
# Directive

## Usage

- Only this file (/Directive.md) is injected into the system prompt.
  Linked files are reference material you can read with fs_read.
- Edit this file with fs_write or fs_edit.
- Add new entries to the table of contents as you create new files.
- Remove entries you do not need.

## Table of Contents

- [Identity](/instructions/identity.md)
- [Rules & Constraints](/instructions/rules.md)
- [Domain Knowledge](/instructions/domain.md)
- [Workflows & Procedures](/instructions/workflows.md)
- [Tools & Integrations](/instructions/tools.md)
- [Style & Formatting](/instructions/style.md)
- [Memory & Context](/instructions/memory.md)
```

**Only `/Directive.md` is injected into the system prompt.** The linked files are reference material the agent can read with `fs_read` when it needs the detail. This keeps the system prompt focused while letting you store extensive reference material in the filesystem.

## What to put where

**In Directive.md (injected every request):**
- Identity, role, and tone -- kept brief
- Hard rules and constraints
- Short summaries and pointers to detailed files
- The table of contents

**In linked files (read on demand):**
- Detailed workflow procedures
- Large reference tables or domain data
- Style guides and formatting templates
- Running memory logs

## Example

A research agent might have:

**/Directive.md:**
```markdown
# Directive

## Usage
...

## Table of Contents

- [Identity](/instructions/identity.md)
- [Research Procedure](/instructions/research-procedure.md)
- [Source Policy](/instructions/sources.md)
- [Output Format](/instructions/format.md)
- [Completed Reports](/log/completed.md)

You are a senior market research analyst specializing in SaaS companies.
Never share customer PII in responses. Always anonymize names in examples.
```

**/instructions/research-procedure.md:**
```markdown
# Research Procedure

1. Check /data/ for cached data before making new queries.
2. Prefer primary sources (SEC filings, earnings calls) over secondary analysis.
3. Save all research drafts to /drafts/ before finalizing.
4. Log completed analyses in /log/completed.md.
```

**/instructions/format.md:**
```markdown
# Output Format

- Use structured markdown with headers for all reports.
- Include a "Key Findings" summary at the top of every report.
- Always note the date of data collection.
- Use tables for any comparison data.
```

## The agent can update its own instructions

Because Directive.md and linked files are regular files in the agent's filesystem, the agent can read and modify them using `fs_read`, `fs_write`, and `fs_edit`. This means:

- You can ask the agent to **add new rules**: "Add a rule to your Directive.md that all currency values should be in USD."
- The agent can **learn from corrections**: "That output format was wrong. Update your format instructions to always use tables for comparison data."
- You can ask the agent to **show its current instructions**: "Read your Directive.md and tell me what rules you follow."
- The agent can **create new instruction files** and link them from the table of contents.
- Changes to Directive.md are picked up **immediately** -- no need to start a new chat.

## Size limit

Directive.md content is capped at 100 KB when injected into the system message. If the file exceeds this limit, only the first 100 KB is used. This is why detailed material should go in linked files -- Directive.md stays lean and within the limit, while the agent reads linked files on demand.

## Directive.md vs. the system message

The agent's **system message** (set in the agent edit page) and **Directive.md** serve complementary purposes:

| | System Message | Directive.md |
|---|---|---|
| **Set by** | Users via the agent edit page | The agent itself (or users through the agent) |
| **Editable by the agent** | No | Yes |
| **Persists across chats** | Yes | Yes |
| **When changes apply** | Immediately | Immediately |
| **Best for** | Initial identity, core capabilities | Evolving rules, learned preferences, workflow state |

Both are included in the agent's context. The system message comes first, followed by Directive.md content.

## Troubleshooting

**Directive.md is not taking effect**
- Verify the filesystem is enabled for the agent.
- Check that the file is at exactly `/Directive.md` (case-sensitive).

**Directive.md content seems truncated**
- The injection cap is 100 KB. Move detailed reference material into linked files and keep Directive.md as a concise index.

---

## Navigation

### In this section: Agent Filesystem

- [Agent Filesystem](/docs/agent-filesystem/overview.md)
- [Use Cases and Playbooks](/docs/agent-filesystem/use-cases.md)
- [Enabling an Agent's Filesystem](/docs/agent-filesystem/enabling-an-agents-filesystem.md)
- [Disabling an Agent's Filesystem](/docs/agent-filesystem/disabling-an-agents-filesystem.md)
- [Sharing an Agent's Filesystem](/docs/agent-filesystem/sharing-an-agents-filesystem.md)
- **Directive.md -- Persistent Agent Instructions** (current)
- [Troubleshooting](/docs/agent-filesystem/troubleshooting.md)

#### Playbooks

- [Playbook: Build a Monthly Reporting Agent With Templates and an Archive](/docs/agent-filesystem/playbook-monthly-reporting-agent.md)
- [Playbook: Build a Reconciliation Drift Tracker Across Two Systems](/docs/agent-filesystem/playbook-reconciliation-drift-tracker.md)
- [Playbook: Build a Vendor Research Agent That Remembers Every Session](/docs/agent-filesystem/playbook-vendor-research-agent.md)

### Other sections

- [Tool Creation](/docs/tool-creation/overview.md)
- [Subagents](/docs/subagents/overview.md)
- [Agent Skills](/docs/agent-skills/overview.md)
- [Sandcastles](/docs/sandcastles/overview.md)
- [MCP Servers](/docs/mcp-servers/overview.md)
- [Scheduled Triggers](/docs/scheduled-triggers/overview.md)
- [Tool Policies](/docs/tool-policies/overview.md)
- [Workspace Permissions](/docs/workspace-permissions/overview.md)
- [Workspace Billing](/docs/workspace-billing/overview.md)
- [Chat Sharing](/docs/chat-sharing/overview.md)

[Back to docs index](/docs.md)