Memory lifecycle patterns for artifact retention, decision recording, context compaction, and Copilot Memory hygiene. Use for session context management, ADR creation, and rolloff strategies.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Memory lifecycle patterns for artifact retention, decision recording, context compaction, and Copilot Memory hygiene. Use for session context management, ADR creation, and rolloff strategies.
user-invocable
true
argument-hint
[session or context to snapshot or clean up]
Memory Management
Teaches agents how to manage institutional memory across sessions -- recording decisions, maintaining context, compacting artifacts, and using Copilot Memory effectively.
Description
This skill covers the full memory lifecycle: what to remember, where to store it, when to compact or forget it, and how to read it back efficiently. It bridges three memory layers: Copilot Memory (cross-session facts), artifact storage (structured documents), and session context (active working memory).
When to Use
Starting a new session (read-back phase)
Making architectural or design decisions
Completing a plan phase or review cycle
Running artifact cleanup or compaction
Storing or refreshing Copilot Memory facts
Context window approaching capacity
When NOT to Use
Do not use for runtime budget enforcement — use the budget-gatekeeper skill instead.
Do not use for code-level implementation details or transient debugging state that will not be relevant next session.
Entry Points
Trigger Phrases: "record this decision", "what did we decide", "clean up artifacts", "memory budget", "active context"
Copilot Memory = centralized. Cross-repo, auto-injected into every session. Stores durable facts that help in any repo.
artifacts/ = per-repo. Each consuming repository has its own isolated artifacts folder. Never shared across repos.
Routing decision tree:
Would this help in a different repo? -> Copilot Memory
Does it need rationale and alternatives? -> ADR in artifacts/decisions/
Tied to current work in this repo? -> artifacts/ (appropriate subfolder)
Irrelevant next week? -> activeContext.md or skip
Cross-repo pattern: When a convention applies everywhere, store a short fact in Copilot Memory (centralized) AND record the full ADR in the originating repo's artifacts/decisions/ (per-repo). The memory propagates automatically; the ADR preserves the reasoning.
Retention Tiers
Tier
Default TTL
Rolloff Action
Examples
Permanent
Never
Never archived
ADRs, compliance audits, architecture decisions
Seasonal
90 days
Compact at 75% TTL, archive at 100%
Plans, research briefs, reviews
Ephemeral
14 days
Delete at 100% TTL
Session logs, activeContext.md, debug traces
Set tier via YAML frontmatter:
---retention:seasonalttl-days:90---
Decision Recording
When to create an ADR:
Architecture pattern chosen (e.g., "use event-driven over polling")
Technology selection (e.g., "chose PostgreSQL over DynamoDB")
Convention established (e.g., "all agents use model fallback arrays")
Trade-off resolved (e.g., "accepted eventual consistency for performance")
artifacts/artifact-index.md -- inventory of all active artifacts
artifacts/memory/activeContext.md -- current focus, recent decisions, open questions
Budget: Combined read-back should stay under 10K tokens. If the index is large, read only sections relevant to the current task.
Session Write-Back Protocol
At session end or major pause points, update artifacts/memory/activeContext.md:
## Current Focus
{What we're working on}
## Recent Decisions- DEC-042: Chose hybrid rolloff strategy
- DEC-043: Set 10K token memory budget
## Open Questions- Should cleanup run automatically on session start?
## Active Plan
memory-management / Phase 4 of 5
Artifact Compaction
When artifacts approach 75% of their TTL, the cleanup script generates a .compact.md stub:
A durable convention (naming patterns, shell commands, model tiers)
Not discoverable from limited code (e.g., "use powershell not pwsh")
Actionable for future tasks (build commands, test patterns)
Independent of in-flight work
Skip when the fact is:
Obvious from reading the code
Transient (branch names, session IDs)
Already in instructions or AGENTS.md
Contains secrets or PII
Refresh -- re-store a memory you use and verify, to extend its retention.
Context Window Discipline
Never bulk-read artifacts -- use the index to identify what's relevant, then read selectively
Prefer compacted versions -- .compact.md over full artifacts for summaries
Progressive disclosure -- start with index, drill into specific artifacts as needed
Phase splitting -- when context grows, split work into smaller phases with artifact handoffs
Decision-first reading -- read ADRs before code to avoid re-debating settled choices
Wiki Knowledge Base (Karpathy Pattern)
Beyond activeContext.md (session-scoped), agents maintain a wiki — a set of topic-organized living documents in artifacts/memory/wiki/. The wiki is the agent's institutional memory: facts discovered during work, curated and refined over time.
Key dependency notes, version constraints, known issues
After dependency changes
tooling.md
Working tool configurations, MCP servers, editor settings
After tool discovery or setup
Wiki rules:
Append, don't rewrite — add new facts to the relevant page. Remove only when a fact is verified stale.
One fact per bullet — keep entries scannable. No paragraphs.
Date-stamp entries — - [2026-04-16] PowerShell 5.1 requires semicolons, not && for chaining
Max 50 lines per page — if a page exceeds 50 lines, prune the oldest/least-useful entries.
Read wiki at session start — after activeContext.md, scan wiki pages relevant to the current task.
Write wiki after verification — only store facts that have been verified through tool execution, not assumed.
Wiki vs. Copilot Memory:
Wiki = per-repo, detailed, living — "PowerShell tests use Invoke-Pester -Path tests -Output Detailed"
Copilot Memory = cross-repo, durable conventions — "Always use model fallback arrays"
Initialization:pwsh -File scripts/init-artifacts.ps1 creates the wiki folder with empty starter pages.
Examples
Pattern: New Decision
1. Identify the decision point during planning/review
2. Create ADR: artifacts/decisions/DEC-{NNN}-{slug}.md
3. Set retention: permanent (architecture) or seasonal (tactical)
4. Reference DEC-ID in the plan/review artifact
5. Update activeContext.md with the decision summary
6. Store in Copilot Memory if it's a durable convention
Pattern: Session Resume
1. Read artifacts/artifact-index.md (scan for relevant sections)
2. Read artifacts/memory/activeContext.md (full)
3. Check Copilot Memory for relevant stored facts
4. Identify current phase and pending work
5. Proceed with implementation
Pattern: Artifact Cleanup
1. Run: powershell -File scripts/cleanup-artifacts.ps1 -DryRun
2. Review proposed actions (archive, delete, compact)
3. Run without -DryRun to execute
4. Verify artifact-index.md was regenerated
5. Spot-check any .compact.md stubs and refine summaries
Boundaries
Agents MUST set retention and ttl-days frontmatter on new artifacts
Agents MUST NOT bulk-read all artifacts into context
Agents SHOULD prefer .compact.md over full artifacts for non-current work
Conductor MUST read-back activeContext.md at session start
Conductor MUST write-back activeContext.md at session end
Only scripts/cleanup-artifacts.ps1 moves files to .archive/ -- never move manually
References
scripts/cleanup-artifacts.ps1 — artifact compaction, archival, and cleanup workflow
docs/templates/decision.md — ADR template for recording durable decisions
.github/agents/conductor.agent.md — session read-back and write-back responsibilities
artifacts/memory/activeContext.md — active session context handoff document
