Custom Instructions — Memory Management¶
What Are Custom Instructions?¶
Custom instructions are a Markdown file that Copilot CLI reads at the start of every session. They tell Copilot who you are, how you like to work, and what it needs to remember.
Analogy
☕ Think of it like a staff briefing sheet pinned to the café wall. Every new shift worker (session) reads it before starting — so they know the house rules, who the regular customers are, and where everything is kept.
The Two-File System¶
As your projects grow, a single instruction file gets too large. Loading a huge file into every session wastes "brain space" (context window) and slows things down.
The solution: split it into two files — a lean main file and a detailed reference file.
~\.copilot\
├── copilot-instructions.md ← Main file (loaded EVERY session)
└── copilot-instructions-reference.md ← Reference file (checked WHEN NEEDED)
Why Two Files?¶
| Problem | Solution |
|---|---|
| Main file grew to 65% capacity in just 2 days | Split into main + reference |
| Detailed info (deploy commands, persona mappings) wastes space every session | Move to reference file — only read when relevant |
| Risk of hitting the comfort zone limit as learning progresses | Auto-consolidation rule triggers at 60% |
Wallet vs Filing Cabinet
- Main file (wallet) = essentials you carry everywhere — who you are, how to teach, key rules, important paths
- Reference file (filing cabinet) = detailed records pulled out for specific tasks — deploy commands, backup scripts, Cloud Café persona mappings, full site structure
What Goes Where?¶
Main File — copilot-instructions.md¶
Purpose: Loaded into every session. Must be concise and punchy.
Contains:
- Output style and behaviour rules
- Teaching approach and learning style preferences
- "Lab" vs "Org" environment routing
- Key info about the user (role, background, goals)
- Important file/folder locations (one-liners)
- Research and accuracy rules
Target size: Under 50% of comfort zone (~7,500 chars)
Reference File — copilot-instructions-reference.md¶
Purpose: Detailed context checked only when a specific topic comes up.
Contains:
- ☕ Cloud Café scenario details and persona mappings
- Content creator platform links and details
- Learning portal technical details (deploy commands, site sections)
- Backup system technical details (scripts, retention, restore steps)
- Full learning goals list
- Lab environment technical details (tenant IDs, subscription names)
Auto-Consolidation Rule¶
To prevent the main file from growing too large over time:
| Trigger | Action |
|---|---|
| Main file reaches ~60% of comfort zone (~9,000 chars) | Copilot automatically consolidates |
| How: | Move detailed/granular info to reference file, keep main file punchy |
| Target after consolidation: | Under 50% (~7,500 chars) |
This means the main file stays fast and lean, while the reference file grows as a knowledge archive.
Size Guidelines¶
| Zone | Characters | Percentage | Status |
|---|---|---|---|
| ✅ Comfortable | < 7,500 | < 50% | Ideal — plenty of room |
| ⚠️ Getting full | 7,500 – 9,000 | 50% – 60% | Consider consolidating soon |
| 🔴 Consolidation trigger | > 9,000 | > 60% | Auto-consolidation kicks in |
| ❌ Too large | > 15,000 | > 100% | Impacts session performance |
Current Status¶
After the restructure:
| File | Size | % of Comfort Zone |
|---|---|---|
| Main file | ~3,300 chars | 22% ✅ |
| Reference file | ~5,000 chars | N/A (not size-limited) |
Backup Coverage¶
Both instruction files are automatically backed up as part of the daily backup system:
| File | Backed up? | How |
|---|---|---|
copilot-instructions.md |
✅ Yes | Part of .copilot/ folder backup |
copilot-instructions-reference.md |
✅ Yes | Part of .copilot/ folder backup |
The backup script copies all top-level files from ~\.copilot\ — both instruction files are included automatically. No extra configuration needed.
Both copies end up in:
- Corp OneDrive:
~/OneDrive - Microsoft/CopilotCLI_Backups/backup_*/ - Google Drive:
G:\My Drive\CopilotCLI_Backups/backup_*/
How to Check the Current Size¶
Run this PowerShell command anytime to see how your instruction files are doing:
$main = (Get-Content "$env:USERPROFILE\.copilot\copilot-instructions.md" -Raw).Length
$ref = (Get-Content "$env:USERPROFILE\.copilot\copilot-instructions-reference.md" -Raw).Length
Write-Host "Main file: $main chars ($([math]::Round($main/15000*100))%)"
Write-Host "Reference file: $ref chars"
Write-Host "Total knowledge: $($main + $ref) chars"
Summary
The two-file memory system keeps Copilot CLI fast and focused every session, while preserving all the detailed context for when it's needed. The auto-consolidation rule at 60% ensures the main file never gets bloated — even as your projects and learning grow over time.