9.5 KiB

Raw Blame History

Expert Agent Architecture

Domain-specific agents with persistent memory, sidecar files, and restricted access patterns.

When to Use

Personal assistants (journal keeper, diary companion)
Specialized domain experts (legal advisor, medical reference)
Agents that need to remember past interactions
Agents with restricted file system access (privacy/security)
Long-term relationship agents that learn about users

File Structure

{agent-name}/
├── {agent-name}.agent.yaml    # Main agent definition
└── {agent-name}-sidecar/      # Supporting files
    ├── instructions.md        # Private directives
    ├── memories.md            # Persistent memory
    ├── knowledge/             # Domain-specific resources
    │   └── README.md
    └── [custom files]         # Agent-specific resources

YAML Structure

agent:
  metadata:
    name: 'Persona Name'
    title: 'Agent Title'
    icon: 'emoji'
    type: 'expert'

  persona:
    role: 'Domain Expert with specialized capability'

    identity: |
      Background and expertise in first-person voice.
      {{#if user_preference}}
      Customization based on install_config.
      {{/if}}      

    communication_style: |
      {{#if tone_style == "gentle"}}
      Gentle and supportive communication...
      {{/if}}
      {{#if tone_style == "direct"}}
      Direct and efficient communication...
      {{/if}}
      I reference past conversations naturally.      

    principles:
      - Core belief about the domain
      - How I handle user information
      - My approach to memory and learning

  critical_actions:
    - 'Load COMPLETE file {agent-folder}/{agent-name}-sidecar/memories.md and remember all past insights'
    - 'Load COMPLETE file {agent-folder}/{agent-name}-sidecar/instructions.md and follow ALL protocols'
    - 'ONLY read/write files in {agent-folder}/{agent-name}-sidecar/ - this is our private space'
    - 'Address user as {{greeting_name}}'
    - 'Track patterns, themes, and important moments'
    - 'Reference past interactions naturally to show continuity'

  prompts:
    - id: main-function
      content: |
        <instructions>
        Guide user through the primary function.
        {{#if tone_style == "gentle"}}
        Use gentle, supportive approach.
        {{/if}}
        </instructions>

        <process>
        1. Understand context
        2. Provide guidance
        3. Record insights
        </process>        

    - id: memory-recall
      content: |
        <instructions>
        Access and share relevant memories.
        </instructions>

        Reference stored information naturally.        

  menu:
    - trigger: action1
      action: '#main-function'
      description: 'Primary agent function'

    - trigger: remember
      action: 'Update {agent-folder}/{agent-name}-sidecar/memories.md with session insights'
      description: 'Save what we discussed today'

    - trigger: patterns
      action: '#memory-recall'
      description: 'Recall patterns from past interactions'

    - trigger: insight
      action: 'Document breakthrough in {agent-folder}/{agent-name}-sidecar/breakthroughs.md'
      description: 'Record a significant insight'

  install_config:
    compile_time_only: true
    description: 'Personalize your expert agent'
    questions:
      - var: greeting_name
        prompt: 'What should the agent call you?'
        type: text
        default: 'friend'

      - var: tone_style
        prompt: 'Preferred communication tone?'
        type: choice
        options:
          - label: 'Gentle - Supportive and nurturing'
            value: 'gentle'
          - label: 'Direct - Clear and efficient'
            value: 'direct'
        default: 'gentle'

      - var: user_preference
        prompt: 'Enable personalized features?'
        type: boolean
        default: true

Key Components

Sidecar Files (CRITICAL)

Expert agents use companion files for persistence and domain knowledge:

memories.md - Persistent user context

# Agent Memory Bank

## User Preferences

<!-- Learned from interactions -->

## Session History

<!-- Important moments and insights -->

## Personal Notes

<!-- Agent observations -->

instructions.md - Private directives

# Agent Private Instructions

## Core Directives

- Maintain character consistency
- Domain boundaries: {specific domain}
- Access restrictions: Only sidecar folder

## Special Rules

<!-- Agent-specific protocols -->

knowledge/ - Domain resources

# Agent Knowledge Base

Add domain-specific documentation here.

Critical Actions

MANDATORY for expert agents - These load sidecar files at activation:

critical_actions:
  - 'Load COMPLETE file {agent-folder}/{sidecar}/memories.md and remember all past insights'
  - 'Load COMPLETE file {agent-folder}/{sidecar}/instructions.md and follow ALL protocols'
  - 'ONLY read/write files in {agent-folder}/{sidecar}/ - this is our private space'

Key patterns:

COMPLETE file loading - Forces full file read, not partial
Domain restrictions - Limits file access for privacy/security
Memory integration - Past context becomes part of current session
Protocol adherence - Ensures consistent behavior

{agent-folder} Variable

Special variable resolved during installation:

Points to the agent's installation directory
Used to reference sidecar files
Example: .bmad/custom/agents/journal-keeper/

What Gets Injected at Compile Time

Same as simple agents, PLUS:

Critical actions become numbered activation steps

<step n="4">Load COMPLETE file {agent-folder}/memories.md...</step>
<step n="5">Load COMPLETE file {agent-folder}/instructions.md...</step>
<step n="6">ONLY read/write files in {agent-folder}/...</step>

Sidecar files copied during installation
- Entire sidecar folder structure preserved
- Relative paths maintained
- Files ready for agent use

Reference Example

See: src/modules/bmb/reference/agents/expert-examples/journal-keeper/

Features demonstrated:

Complete sidecar structure (memories, instructions, breakthroughs)
Critical actions for loading persistent context
Domain restrictions for privacy
Pattern recognition and memory recall
Handlebars-based personalization
Menu actions that update sidecar files

Installation

# Copy entire folder to your project
cp -r /path/to/journal-keeper/ .bmad/custom/agents/

# Install with personalization
bmad agent-install

The installer:

Detects expert agent (folder with .agent.yaml)
Prompts for personalization
Compiles agent YAML to XML-in-markdown
Copies sidecar files to installation target
Creates IDE slash commands
Saves source for reinstallation

Memory Patterns

Accumulative Memory

menu:
  - trigger: save
    action: "Update {agent-folder}/sidecar/memories.md with today's session insights"
    description: 'Save session to memory'

Reference Memory

prompts:
  - id: recall
    content: |
      <instructions>
      Reference memories.md naturally:
      "Last week you mentioned..." or "I notice a pattern..."
      </instructions>

Structured Insights

menu:
  - trigger: insight
    action: 'Document in {agent-folder}/sidecar/breakthroughs.md with date, context, significance'
    description: 'Record meaningful insight'

Domain Restriction Patterns

Single Folder Access

critical_actions:
  - 'ONLY read/write files in {agent-folder}/sidecar/ - NO OTHER FOLDERS'

User Space Access

critical_actions:
  - 'ONLY access files in {user-folder}/journals/ - private space'

Read-Only Access

critical_actions:
  - 'Load knowledge from {agent-folder}/knowledge/ but NEVER modify'
  - 'Write ONLY to {agent-folder}/sessions/'

Best Practices

Load sidecar files in critical_actions - Must be explicit and MANDATORY
Enforce domain restrictions - Clear boundaries prevent scope creep
Use {agent-folder} paths - Portable across installations
Design for memory growth - Structure sidecar files for accumulation
Reference past naturally - Don't dump memory, weave it into conversation
Separate concerns - Memories, instructions, knowledge in distinct files
Include privacy features - Users trust expert agents with personal data

Common Patterns

Session Continuity

communication_style: |
  I reference past conversations naturally:
  "Last time we discussed..." or "I've noticed over the weeks..."

Pattern Recognition

critical_actions:
  - 'Track mood patterns, recurring themes, and breakthrough moments'
  - 'Cross-reference current session with historical patterns'

Adaptive Responses

identity: |
  I learn your preferences and adapt my approach over time.
  {{#if track_preferences}}
  I maintain notes about what works best for you.
  {{/if}}

Validation Checklist

Valid YAML syntax
Metadata includes type: "expert"
critical_actions loads sidecar files explicitly
critical_actions enforces domain restrictions
Sidecar folder structure created and populated
memories.md has clear section structure
instructions.md contains core directives
Menu actions reference {agent-folder} correctly
File paths use {agent-folder} variable
Install config personalizes sidecar references
Agent folder named consistently: {agent-name}/
YAML file named: {agent-name}.agent.yaml
Sidecar folder named: {agent-name}-sidecar/

9.5 KiB Raw Blame History