calctext/.agents/skills/bmad-agent-builder/assets/memory-system.md

Memory System for {displayName}

Memory location: _bmad/_memory/{skillName}-sidecar/

Core Principle

Tokens are expensive. Only remember what matters. Condense everything to its essence.

File Structure

index.md — Primary Source

Load on activation. Contains:

• Essential context (what we're working on)
• Active work items
• User preferences (condensed)
• Quick reference to other files if needed

Update: When essential context changes (immediately for critical data).

access-boundaries.md — Access Control (Required for all agents)

Load on activation. Contains:

• Read access — Folders/patterns this agent can read from
• Write access — Folders/patterns this agent can write to
• Deny zones — Explicitly forbidden folders/patterns
• Created by — Agent builder at creation time, confirmed/adjusted during init

Template structure:

# Access Boundaries for {displayName}

## Read Access
- {folder-path-or-pattern}
- {another-folder-or-pattern}

## Write Access
- {folder-path-or-pattern}
- {another-folder-or-pattern}

## Deny Zones
- {explicitly-forbidden-path}

Critical: On every activation, load these boundaries first. Before any file operation (read/write), verify the path is within allowed boundaries. If uncertain, ask user.

{if-standalone}

• User-configured paths — Additional paths set during init (journal location, etc.) are appended here {/if-standalone}

patterns.md — Learned Patterns

Load when needed. Contains:

• User's quirks and preferences discovered over time
• Recurring patterns or issues
• Conventions learned

Format: Append-only, summarized regularly. Prune outdated entries.

chronology.md — Timeline

Load when needed. Contains:

• Session summaries
• Significant events
• Progress over time

Format: Append-only. Prune regularly; keep only significant events.

Memory Persistence Strategy

Write-Through (Immediate Persistence)

Persist immediately when:

1. User data changes — preferences, configurations
2. Work products created — entries, documents, code, artifacts
3. State transitions — tasks completed, status changes
4. User requests save — explicit [SM] - Save Memory capability

Checkpoint (Periodic Persistence)

Update periodically after:

• N interactions (default: every 5-10 significant exchanges)
• Session milestones (completing a capability/task)
• When file grows beyond target size

Save Triggers

After these events, always update memory:

• {save-trigger-1}
• {save-trigger-2}
• {save-trigger-3}

Memory is updated via the [SM] - Save Memory capability which:

1. Reads current index.md
2. Updates with current session context
3. Writes condensed, current version
4. Checkpoints patterns.md and chronology.md if needed

Write Discipline

Before writing to memory, ask:

1. Is this worth remembering?

   • If no → skip
   • If yes → continue

2. What's the minimum tokens that capture this?

   • Condense to essence
   • No fluff, no repetition

3. Which file?

   • index.md → essential context, active work
   • patterns.md → user quirks, recurring patterns, conventions
   • chronology.md → session summaries, significant events

4. Does this require index update?

   • If yes → update index.md to point to it

Memory Maintenance

Regularly (every few sessions or when files grow large):

1. Condense verbose entries — Summarize to essence
2. Prune outdated content — Move old items to chronology or remove
3. Consolidate patterns — Merge similar entries
4. Update chronology — Archive significant past events

First Run

If sidecar doesn't exist, load init.md to create the structure.