365 lines
9.5 KiB
Markdown
365 lines
9.5 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```markdown
|
|
# Agent Memory Bank
|
|
|
|
## User Preferences
|
|
|
|
<!-- Learned from interactions -->
|
|
|
|
## Session History
|
|
|
|
<!-- Important moments and insights -->
|
|
|
|
## Personal Notes
|
|
|
|
<!-- Agent observations -->
|
|
```
|
|
|
|
**instructions.md** - Private directives
|
|
|
|
```markdown
|
|
# 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
|
|
|
|
```markdown
|
|
# Agent Knowledge Base
|
|
|
|
Add domain-specific documentation here.
|
|
```
|
|
|
|
### Critical Actions
|
|
|
|
**MANDATORY for expert agents** - These load sidecar files at activation:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
1. **Critical actions become numbered activation steps**
|
|
|
|
```xml
|
|
<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>
|
|
```
|
|
|
|
2. **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
|
|
|
|
```bash
|
|
# Copy entire folder to your project
|
|
cp -r /path/to/journal-keeper/ .bmad/custom/agents/
|
|
|
|
# Install with personalization
|
|
bmad agent-install
|
|
```
|
|
|
|
The installer:
|
|
|
|
1. Detects expert agent (folder with .agent.yaml)
|
|
2. Prompts for personalization
|
|
3. Compiles agent YAML to XML-in-markdown
|
|
4. **Copies sidecar files to installation target**
|
|
5. Creates IDE slash commands
|
|
6. Saves source for reinstallation
|
|
|
|
## Memory Patterns
|
|
|
|
### Accumulative Memory
|
|
|
|
```yaml
|
|
menu:
|
|
- trigger: save
|
|
action: "Update {agent-folder}/sidecar/memories.md with today's session insights"
|
|
description: 'Save session to memory'
|
|
```
|
|
|
|
### Reference Memory
|
|
|
|
```yaml
|
|
prompts:
|
|
- id: recall
|
|
content: |
|
|
<instructions>
|
|
Reference memories.md naturally:
|
|
"Last week you mentioned..." or "I notice a pattern..."
|
|
</instructions>
|
|
```
|
|
|
|
### Structured Insights
|
|
|
|
```yaml
|
|
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
|
|
|
|
```yaml
|
|
critical_actions:
|
|
- 'ONLY read/write files in {agent-folder}/sidecar/ - NO OTHER FOLDERS'
|
|
```
|
|
|
|
### User Space Access
|
|
|
|
```yaml
|
|
critical_actions:
|
|
- 'ONLY access files in {user-folder}/journals/ - private space'
|
|
```
|
|
|
|
### Read-Only Access
|
|
|
|
```yaml
|
|
critical_actions:
|
|
- 'Load knowledge from {agent-folder}/knowledge/ but NEVER modify'
|
|
- 'Write ONLY to {agent-folder}/sessions/'
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
|
|
2. **Enforce domain restrictions** - Clear boundaries prevent scope creep
|
|
3. **Use {agent-folder} paths** - Portable across installations
|
|
4. **Design for memory growth** - Structure sidecar files for accumulation
|
|
5. **Reference past naturally** - Don't dump memory, weave it into conversation
|
|
6. **Separate concerns** - Memories, instructions, knowledge in distinct files
|
|
7. **Include privacy features** - Users trust expert agents with personal data
|
|
|
|
## Common Patterns
|
|
|
|
### Session Continuity
|
|
|
|
```yaml
|
|
communication_style: |
|
|
I reference past conversations naturally:
|
|
"Last time we discussed..." or "I've noticed over the weeks..."
|
|
```
|
|
|
|
### Pattern Recognition
|
|
|
|
```yaml
|
|
critical_actions:
|
|
- 'Track mood patterns, recurring themes, and breakthrough moments'
|
|
- 'Cross-reference current session with historical patterns'
|
|
```
|
|
|
|
### Adaptive Responses
|
|
|
|
```yaml
|
|
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/`
|