@dollhousemcp/mcp-server/dist/seed-elements/memories/how-to-create-custom-auto-load-memories.yaml

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

---
name: how-to-create-custom-auto-load-memories
type: memory
description: Complete guide for creating custom auto-load memories - step-by-step instructions and examples
version: 1.0.0
author: DollhouseMCP
category: documentation
tags:
  - auto-load
  - guide
  - tutorial
  - memory-creation
  - documentation
triggers:
  - how-to-auto-load
  - create-auto-load-memory
  - auto-load-guide
  - auto-load-tutorial
  - custom-auto-load
autoLoad: false
priority: 999
retention: permanent
privacyLevel: public
searchable: true
trustLevel: VALIDATED
---

# How to Create Custom Auto-Load Memories

## Overview

Auto-load memories are automatically loaded when DollhouseMCP starts, providing instant context without searching. Perfect for baseline knowledge, project context, team standards, and frequently-needed information.

## Quick Start

### 1. Create or Modify a Memory

Any memory can be marked for auto-load by adding two metadata fields:

```yaml
---
name: my-custom-memory
type: memory
description: My project context
autoLoad: true      # ← Enable auto-load
priority: 10        # ← Load order (lower = first)
---

# Your content here
```

### 2. Configure Auto-Load Settings (Optional)

Edit `~/.dollhouse/config.yaml`:

```yaml
autoLoad:
  enabled: true              # Global on/off
  maxTokenBudget: 5000      # Total token limit
  maxSingleMemoryTokens: 2000  # Per-memory limit (optional)
  suppressLargeMemoryWarnings: false
```

### 3. Restart DollhouseMCP

```bash
# Restart your MCP client (Claude Desktop, Claude Code, etc.)
# Auto-load memories will be loaded automatically
```

## Step-by-Step Guide

### Step 1: Decide What to Auto-Load

**Good Candidates**:
- Project overview and architecture
- Team coding standards
- Frequently-referenced specifications
- Domain knowledge (medical terms, legal concepts)
- API reference sheets
- Personal preferences and workflows

**Poor Candidates**:
- Large datasets (>10,000 tokens)
- Sensitive information (credentials, PII)
- Frequently changing content
- Temporary notes

### Step 2: Create the Memory

#### Using MCP Tools:

```javascript
// In Claude Code or compatible MCP client
create_element({
  type: "memories",
  name: "my-project-context",
  description: "Core project information for AI context",
  content: "# Project: MyApp\n\n## Architecture\n...",
  metadata: {
    autoLoad: true,
    priority: 5
  }
})
```

#### Using CLI:

```bash
dollhouse create memory my-project-context \
  --autoLoad true \
  --priority 5 \
  --content "# Project: MyApp..."
```

#### Manual YAML:

Create `~/.dollhouse/portfolio/memories/my-project-context.yaml`:

```yaml
---
name: my-project-context
type: memory
description: Core project information
autoLoad: true
priority: 5
retention: permanent
privacyLevel: private
searchable: true
---

# Project: MyApp

## Architecture
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL

## Key Decisions
- Using REST API (not GraphQL) for simplicity
- Tailwind CSS for styling
- Jest for testing
```

### Step 3: Set Priority

Priority determines load order (lower number = loads first):

- **1-10**: System/baseline knowledge (reserved for DollhouseMCP)
- **11-50**: Critical project context (load first)
- **51-100**: Important reference material
- **101-500**: Nice-to-have context
- **501+**: Lowest priority

Example priority scheme:
```yaml
# Priority 1: DollhouseMCP baseline (system)
name: dollhousemcp-baseline-knowledge
priority: 1

# Priority 20: Your project overview
name: project-overview
priority: 20

# Priority 30: Team coding standards
name: coding-standards
priority: 30

# Priority 50: API reference
name: api-reference
priority: 50
```

### Step 4: Optimize Token Usage

Check token estimate:

```bash
dollhouse validate memory my-project-context
# Output includes: "Estimated tokens: 1,234"
```

**Token Guidelines**:
- **Small** (0-1,000): Ideal for auto-load
- **Medium** (1,000-5,000): Good, stays under default budget
- **Large** (5,000-10,000): Consider splitting or increasing budget
- **Very Large** (10,000+): Not recommended for auto-load

Reduce token count:
- Remove verbose examples
- Use bullet points instead of paragraphs
- Link to external docs instead of embedding
- Split into multiple focused memories

### Step 5: Test Your Memory

```bash
# Check if memory will auto-load
dollhouse config show autoLoad

# Validate memory syntax
dollhouse validate memory my-project-context

# See auto-load order
dollhouse list memories --filter autoLoad=true --sort priority
```

## Advanced Configuration

### Explicit Memory List

Override metadata-driven auto-load with explicit list:

```yaml
# ~/.dollhouse/config.yaml
autoLoad:
  enabled: true
  memories:
    - dollhousemcp-baseline-knowledge
    - my-project-context
    - coding-standards
    # Only these memories will auto-load
```

### Conditional Auto-Load

Use environment variables to control auto-load:

```bash
# Disable all auto-load temporarily
export DOLLHOUSE_DISABLE_AUTOLOAD=true

# Normal auto-load behavior
unset DOLLHOUSE_DISABLE_AUTOLOAD
```

### Per-Project Configuration

Create project-specific config:

```yaml
# /project/.dollhouserc.yaml
autoLoad:
  maxTokenBudget: 10000  # Higher budget for this project
  memories:
    - project-overview
    - local-dev-setup
    # Project-specific memories only
```

## Common Patterns

### Pattern 1: Layered Context

Load knowledge in layers (general → specific):

```yaml
# Priority 10: Company-wide standards
name: company-coding-standards
priority: 10

# Priority 20: Team standards
name: team-backend-patterns
priority: 20

# Priority 30: Project-specific context
name: myapp-architecture
priority: 30
```

### Pattern 2: Role-Based Context

Different memories for different roles:

```yaml
# For backend developers
name: backend-context
autoLoad: true
tags: [backend, api, database]

# For frontend developers
name: frontend-context
autoLoad: true
tags: [frontend, ui, components]
```

### Pattern 3: Onboarding Kit

New team member baseline:

```yaml
name: team-onboarding
priority: 5
description: Everything new engineers need to know
content: |
  # Welcome to Team Atlas!

  ## First Week Checklist
  - [ ] Read architecture docs
  - [ ] Set up dev environment
  - [ ] Deploy your first PR

  ## Key Resources
  - Slack: #team-atlas
  - Docs: docs.company.com/atlas
  - CI/CD: Jenkins (jenkins.company.com)
```

## Troubleshooting

### Memory Not Loading

1. Check metadata:
   ```yaml
   autoLoad: true  # Must be boolean, not string
   priority: 10    # Must be number, not string
   ```

2. Verify config:
   ```bash
   dollhouse config show autoLoad.enabled
   # Should output: true
   ```

3. Check startup logs:
   ```bash
   # Look for: "[ServerStartup] Auto-load complete: X memories loaded"
   ```

### Budget Exceeded

If memories are skipped due to budget:

```yaml
# Increase budget
autoLoad:
  maxTokenBudget: 10000  # Default: 5000

# Or prioritize critical memories (lower priority = loads first)
# Or split large memories into smaller focused ones
```

### Memory Too Large

Warning: "Memory 'xyz' is very large (~12,000 tokens)"

Solutions:
1. Split into multiple memories
2. Remove verbose sections
3. Increase single memory limit:
   ```yaml
   autoLoad:
     maxSingleMemoryTokens: 15000
   ```
4. Suppress warnings (not recommended):
   ```yaml
   autoLoad:
     suppressLargeMemoryWarnings: true
   ```

## Examples

### Example 1: Project Context

```yaml
---
name: webapp-project-context
autoLoad: true
priority: 20
---

# WebApp Project Context

**Stack**: React + Node.js + PostgreSQL
**Deployment**: AWS (ECS + RDS)
**CI/CD**: GitHub Actions

## Active Sprints
- Sprint 42: User authentication (ends Oct 15)
- Tech debt: Migrate to TypeScript (Q4 2025)

## Key Contacts
- PM: Jane (@jane)
- Tech Lead: Bob (@bob)
- DevOps: Alice (@alice)
```

### Example 2: API Reference

```yaml
---
name: internal-api-reference
autoLoad: true
priority: 50
---

# Internal API Reference

## User Service
- `GET /api/users/:id` - Get user by ID
- `POST /api/users` - Create user
- `PUT /api/users/:id` - Update user

## Auth
- Header: `Authorization: Bearer <token>`
- Token expires: 24 hours
```

### Example 3: Coding Standards

```yaml
---
name: team-coding-standards
autoLoad: true
priority: 30
---

# Team Coding Standards

## TypeScript
- Use strict mode
- No `any` types
- Prefer interfaces over types

## Testing
- Coverage: >80% required
- Unit tests: Jest
- E2E tests: Playwright

## PR Process
1. Create feature branch
2. Write tests first
3. Get 2 approvals
4. Squash merge to main
```

## Best Practices

1. **Start Small**: Begin with 1-2 auto-load memories, expand as needed
2. **Review Regularly**: Update memories quarterly, remove stale content
3. **Monitor Token Usage**: Check startup logs for token counts
4. **Use Priorities Wisely**: Reserve low priorities for critical content
5. **Document Changes**: Add version history to memory content
6. **Test Before Committing**: Validate memories before pushing to team
7. **Share Configurations**: Commit `.dollhouserc.yaml` to project repos

## Related Documentation

- [Priority Best Practices for Teams](./priority-best-practices-for-teams.yaml)
- [Token Estimation Guidelines](./token-estimation-guidelines.yaml)
- [DollhouseMCP Baseline Knowledge](./dollhousemcp-baseline-knowledge.yaml)

---

**Last Updated**: v1.9.25 (October 2025)