243 lines
7.8 KiB
Markdown
243 lines
7.8 KiB
Markdown
# Expert Agent Reference: Personal Journal Keeper (Whisper)
|
|
|
|
This folder contains a complete reference implementation of a **BMAD Expert Agent** - an agent with persistent memory and domain-specific resources via a sidecar folder.
|
|
|
|
## Overview
|
|
|
|
**Agent Name:** Whisper
|
|
**Type:** Expert Agent
|
|
**Purpose:** Personal journal companion that remembers your entries, tracks mood patterns, and notices themes over time
|
|
|
|
This reference demonstrates:
|
|
|
|
- Expert Agent with focused sidecar resources
|
|
- Embedded prompts PLUS sidecar file references (hybrid pattern)
|
|
- Persistent memory across sessions
|
|
- Domain-restricted file access
|
|
- Pattern tracking and recall
|
|
- Simple, maintainable architecture
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
agent-with-memory/
|
|
├── README.md # This file
|
|
├── journal-keeper.agent.yaml # Main agent definition
|
|
└── journal-keeper-sidecar/ # Agent's private workspace
|
|
├── instructions.md # Core directives
|
|
├── memories.md # Persistent session memory
|
|
├── mood-patterns.md # Emotional tracking data
|
|
├── breakthroughs.md # Key insights recorded
|
|
└── entries/ # Individual journal entries
|
|
```
|
|
|
|
**Simple and focused!** Just 4 core files + a folder for entries.
|
|
|
|
## Key Architecture Patterns
|
|
|
|
### 1. Hybrid Command Pattern
|
|
|
|
Expert Agents can use BOTH:
|
|
|
|
- **Embedded prompts** via `action: "#prompt-id"` (like Simple Agents)
|
|
- **Sidecar file references** via direct paths
|
|
|
|
```yaml
|
|
menu:
|
|
# Embedded prompt (like Simple Agent)
|
|
- trigger: 'write'
|
|
action: '#guided-entry'
|
|
description: "Write today's journal entry"
|
|
|
|
# Direct sidecar file action
|
|
- trigger: 'insight'
|
|
action: 'Document this breakthrough in {agent-folder}/journal-keeper-sidecar/breakthroughs.md'
|
|
description: 'Record a meaningful insight'
|
|
```
|
|
|
|
This hybrid approach gives you the best of both worlds!
|
|
|
|
### 2. Mandatory Critical Actions
|
|
|
|
Expert Agents MUST load sidecar files explicitly:
|
|
|
|
```yaml
|
|
critical_actions:
|
|
- 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/memories.md'
|
|
- 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/instructions.md'
|
|
- 'ONLY read/write files in {agent-folder}/journal-keeper-sidecar/'
|
|
```
|
|
|
|
**Key points:**
|
|
|
|
- Files are loaded at startup
|
|
- Domain restriction is enforced
|
|
- Agent knows its boundaries
|
|
|
|
### 3. Persistent Memory Pattern
|
|
|
|
The `memories.md` file stores:
|
|
|
|
- User preferences and patterns
|
|
- Session notes and observations
|
|
- Recurring themes discovered
|
|
- Growth markers tracked
|
|
|
|
**Critically:** This is updated EVERY session, creating continuity.
|
|
|
|
### 4. Domain-Specific Tracking
|
|
|
|
Different files track different aspects:
|
|
|
|
- **memories.md** - Qualitative insights and observations
|
|
- **mood-patterns.md** - Quantitative emotional data
|
|
- **breakthroughs.md** - Significant moments
|
|
- **entries/** - The actual content (journal entries)
|
|
|
|
This separation makes data easy to reference and update.
|
|
|
|
### 5. Simple Sidecar Structure
|
|
|
|
Unlike modules with complex folder hierarchies, Expert Agent sidecars are flat and focused:
|
|
|
|
- Just the files the agent needs
|
|
- No nested workflows or templates
|
|
- Easy to understand and maintain
|
|
- All domain knowledge in one place
|
|
|
|
## Comparison: Simple vs Expert vs Module
|
|
|
|
| Feature | Simple Agent | Expert Agent | Module Agent |
|
|
| ------------- | -------------------- | -------------------------- | ---------------------- |
|
|
| Architecture | Single YAML | YAML + sidecar folder | YAML + module system |
|
|
| Memory | Session only | Persistent (sidecar files) | Config-driven |
|
|
| Prompts | Embedded only | Embedded + external files | Workflow references |
|
|
| Dependencies | None | Sidecar folder | Module workflows/tasks |
|
|
| Domain Access | None | Restricted to sidecar | Full module access |
|
|
| Complexity | Low | Medium | High |
|
|
| Use Case | Self-contained tools | Domain experts with memory | Full workflow systems |
|
|
|
|
## The Sweet Spot
|
|
|
|
Expert Agents are the middle ground:
|
|
|
|
- **More powerful** than Simple Agents (persistent memory, domain knowledge)
|
|
- **Simpler** than Module Agents (no workflow orchestration)
|
|
- **Focused** on specific domain expertise
|
|
- **Personal** to the user's needs
|
|
|
|
## When to Use Expert Agents
|
|
|
|
**Perfect for:**
|
|
|
|
- Personal assistants that need memory (journal keeper, diary, notes)
|
|
- Domain specialists with knowledge bases (specific project context)
|
|
- Agents that track patterns over time (mood, habits, progress)
|
|
- Privacy-focused tools with restricted access
|
|
- Tools that learn and adapt to individual users
|
|
|
|
**Key indicators:**
|
|
|
|
- Need to remember things between sessions
|
|
- Should only access specific folders/files
|
|
- Tracks data over time
|
|
- Adapts based on accumulated knowledge
|
|
|
|
## File Breakdown
|
|
|
|
### journal-keeper.agent.yaml
|
|
|
|
- Standard agent metadata and persona
|
|
- **Embedded prompts** for guided interactions
|
|
- **Menu commands** mixing both patterns
|
|
- **Critical actions** that load sidecar files
|
|
|
|
### instructions.md
|
|
|
|
- Core behavioral directives
|
|
- Journaling philosophy and approach
|
|
- File management protocols
|
|
- Tone and boundary guidelines
|
|
|
|
### memories.md
|
|
|
|
- User profile and preferences
|
|
- Recurring themes discovered
|
|
- Session notes and observations
|
|
- Accumulated knowledge about the user
|
|
|
|
### mood-patterns.md
|
|
|
|
- Quantitative tracking (mood scores, energy, etc.)
|
|
- Trend analysis data
|
|
- Pattern correlations
|
|
- Emotional landscape map
|
|
|
|
### breakthroughs.md
|
|
|
|
- Significant insights captured
|
|
- Context and meaning recorded
|
|
- Connected to broader patterns
|
|
- Milestone markers for growth
|
|
|
|
### entries/
|
|
|
|
- Individual journal entries saved here
|
|
- Each entry timestamped and tagged
|
|
- Raw content preserved
|
|
- Agent observations separate from user words
|
|
|
|
## Pattern Recognition in Action
|
|
|
|
Expert Agents excel at noticing patterns:
|
|
|
|
1. **Reference past sessions:** "Last week you mentioned feeling stuck..."
|
|
2. **Track quantitative data:** Mood scores over time
|
|
3. **Spot recurring themes:** Topics that keep surfacing
|
|
4. **Notice growth:** Changes in language, perspective, emotions
|
|
5. **Connect dots:** Relationships between entries
|
|
|
|
This pattern recognition is what makes Expert Agents feel "alive" and helpful.
|
|
|
|
## Usage Notes
|
|
|
|
### Starting Fresh
|
|
|
|
The sidecar files are templates. A new user would:
|
|
|
|
1. Start journaling with the agent
|
|
2. Agent fills in memories.md over time
|
|
3. Patterns emerge from accumulated data
|
|
4. Insights build from history
|
|
|
|
### Building Your Own Expert Agent
|
|
|
|
1. **Define the domain** - What specific area will this agent focus on?
|
|
2. **Choose sidecar files** - What data needs to be tracked/remembered?
|
|
3. **Mix command patterns** - Use embedded prompts + sidecar references
|
|
4. **Enforce boundaries** - Clearly state domain restrictions
|
|
5. **Design for accumulation** - How will memory grow over time?
|
|
|
|
### Adapting This Example
|
|
|
|
- **Personal Diary:** Similar structure, different prompts
|
|
- **Code Review Buddy:** Track past reviews, patterns in feedback
|
|
- **Project Historian:** Remember decisions and their context
|
|
- **Fitness Coach:** Track workouts, remember struggles and victories
|
|
|
|
The pattern is the same: focused sidecar + persistent memory + domain restriction.
|
|
|
|
## Key Takeaways
|
|
|
|
- **Expert Agents** bridge Simple and Module complexity
|
|
- **Sidecar folders** provide persistent, domain-specific memory
|
|
- **Hybrid commands** use both embedded prompts and file references
|
|
- **Pattern recognition** comes from accumulated data
|
|
- **Simple structure** keeps it maintainable
|
|
- **Domain restriction** ensures focused expertise
|
|
- **Memory is the superpower** - remembering makes the agent truly useful
|
|
|
|
---
|
|
|
|
_This reference shows how Expert Agents can be powerful memory-driven assistants while maintaining architectural simplicity._
|