Directives

Persistent rules and preferences that shape your AI's behavior across every conversation, skill, and channel.

7 min read

Directives

Directives are persistent rules that are always injected into the AI’s context, regardless of which skill is active, which channel the message came from, or what the conversation is about. They are the highest-priority instructions your AI follows — think of them as the constitution that governs all behavior.

How directives work

Unlike regular memories (which are retrieved based on semantic relevance), directives are always included in the system prompt. Every single LLM call includes every active directive. This makes them the right tool for rules that must never be forgotten or deprioritized.

┌─────────────────────────────────────────┐
│ System Prompt                           │
│                                         │
│  1. Directives (always included)        │
│  2. Active skill personality            │
│  3. Active skill rules                  │
│  4. Retrieved memories (top-k)          │
│  5. Conversation history                │
│                                         │
│ User message                            │
└─────────────────────────────────────────┘

Directives appear first in the system prompt, before the skill personality and rules. This means they take precedence over skill-level instructions if there is a conflict.

Setting directives

Through the UI

Open the Brain Canvas
Click the brain icon in the toolbar (or press Ctrl+D / Cmd+D)
The Directives panel opens
Type a new directive and click “Add”
The directive takes effect immediately on the next message

Through conversation

You can set directives by talking to the AI:

User: From now on, always respond in British English.
AI: Done — I've added that as a directive. I'll use British English
    in all future responses across every channel.

User: Add a directive: always include source URLs when citing information.
AI: Added. I'll include source URLs whenever I cite external information.

Through config.yaml

For directives you want version-controlled or shared across instances:

directives:
  - "Always respond in British English."
  - "When writing code, include error handling for all external calls."
  - "Never execute destructive operations (DELETE, DROP, rm -rf) without explicit confirmation."
  - "Prefer TypeScript over JavaScript in all code examples."
  - "Keep responses concise — under 300 words unless the user asks for detail."

Through the API

# Add a directive
curl -X POST http://localhost:3000/api/directives \
  -H "Content-Type: application/json" \
  -d '{"content": "Always include estimated completion time for tasks."}'

# List all directives
curl http://localhost:3000/api/directives | jq

# Remove a directive
curl -X DELETE http://localhost:3000/api/directives/dir_abc123

Examples

Tone and style

directives:
  - "Use a professional but approachable tone. Avoid jargon unless the user uses it first."
  - "Be direct. Lead with the answer, then explain if needed."
  - "Never use phrases like 'As an AI' or 'I don't have feelings'. Just answer the question."

Citation and accuracy

directives:
  - "Always include source URLs when citing facts from web searches."
  - "If you are uncertain about a fact, say so explicitly. Never present guesses as facts."
  - "When providing statistics, include the date of the source data."

Language preferences

directives:
  - "Respond in the same language the user writes in."
  - "Use British English spelling (colour, behaviour, organisation)."
  - "When writing code comments, always use English regardless of conversation language."

Code style

directives:
  - "Prefer TypeScript over JavaScript. Use strict mode."
  - "Use functional components with hooks in React. Never use class components."
  - "Follow the Airbnb style guide for JavaScript/TypeScript."
  - "Always handle errors explicitly. No empty catch blocks."
  - "Include JSDoc comments for all exported functions."

Safety and boundaries

directives:
  - "Never execute destructive shell commands (rm -rf, DROP TABLE, etc.) without asking for confirmation first."
  - "Never include API keys, tokens, or passwords in responses. Use placeholders like sk-..."
  - "If a request seems harmful or unethical, decline and explain why."
  - "Do not access files outside of the configured allowed_paths."

Workflow preferences

directives:
  - "When given a coding task, always start by asking clarifying questions if the requirements are ambiguous."
  - "After completing a task, suggest one follow-up improvement."
  - "When creating files, always ask which directory to use rather than assuming."

Directive priority and override behavior

Directives follow a clear priority hierarchy:

1. Config directives (highest base priority)

Directives defined in config.yaml load first and form the baseline behavior. They persist across restarts and cannot be removed through conversation — only by editing the config file.

2. User-added directives

Directives added through the UI, conversation, or API. These persist in the database and survive restarts, but can be removed by the user at any time.

3. Skill rules (lower priority)

Rules defined within a skill’s YAML file apply only when that skill is active. If a skill rule conflicts with a directive, the directive wins.

# Directive: "Always respond in British English."

# Skill rule: "Respond in American English."
# Result: British English wins (directive takes precedence)

Conflict resolution

When directives conflict with each other, the most recently added directive takes precedence. However, it is better to avoid conflicting directives entirely. The Directives panel in the UI flags potential conflicts:

⚠ Potential conflict detected:
  - Directive 3: "Keep responses under 300 words."
  - Directive 7: "Always provide detailed, comprehensive explanations."

Consider revising one of these directives.

Overriding directives per-message

Users can temporarily override a directive for a single message by being explicit:

Directive: "Always respond in British English."

User: Write this response in American English: [message]
AI: [responds in American English for this message only]
AI: [returns to British English for subsequent messages]

The directive is not removed — it is just deprioritized for that specific turn because the user’s explicit instruction takes precedence.

Directives vs skill rules

Both directives and skill rules constrain the AI’s behavior. Use them for different purposes:

	Directives	Skill Rules
Scope	Global — all skills, all channels	Local — only when the skill is active
Persistence	Always in context	Only during skill execution
Use for	Universal preferences, safety rules, style	Skill-specific constraints, output format
Set by	User (UI, conversation, config)	Developer (skill YAML)
Priority	Higher	Lower

A good rule of thumb: if the rule should apply everywhere, make it a directive. If it only matters for a specific task, put it in the skill’s rules field.

Directives and memory interaction

Directives and memories serve complementary roles:

Directives tell the AI how to behave (rules, preferences, constraints)
Memories tell the AI what it knows (facts, context, history)

Both are injected into the prompt, but at different stages. Directives are always present; memories are retrieved based on relevance. Together, they give the AI a stable personality (directives) with adaptive knowledge (memory).

User: "What database do we use?"

Prompt construction:
  [Directives]  → "Always respond in British English." (always present)
  [Skill]       → Personality and rules for the active skill
  [Memories]    → "Migrated to PostgreSQL 16 in January" (retrieved, score: 0.92)
  [History]     → Recent conversation turns
  [User msg]    → "What database do we use?"

AI: "You're running PostgreSQL 16 — you migrated in January."
     ^^^ British English (directive) + factual recall (memory)

Managing directives

Viewing active directives

The Directives panel in the UI shows all active directives with their source (config or user-added), creation date, and a toggle to enable/disable each one without deleting it.

Disabling vs deleting

Disable: The directive stays in the database but is not injected into prompts. Useful for temporarily turning off a rule without losing it.
Delete: The directive is permanently removed.

# Disable (keeps the directive, stops injecting it)
curl -X PATCH http://localhost:3000/api/directives/dir_abc123 \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Delete (permanent)
curl -X DELETE http://localhost:3000/api/directives/dir_abc123

Bulk operations

# Export all directives
curl http://localhost:3000/api/directives > my-directives.json

# Import directives (e.g., to a new instance)
curl -X POST http://localhost:3000/api/directives/import \
  -H "Content-Type: application/json" \
  -d @my-directives.json

Next steps

Skills — learn how skill rules interact with directives
Memory — understand the relationship between directives and semantic memory
Brain Canvas — see directives reflected in the AI’s behavior on the canvas