Memory System Toolkit
Reference guides for the memory system: session capture, pattern extraction, and cost tracking.
When to Use
- During Phase 0 (Orient) to load previous session context
- During Phase 6 (Reflect) to capture learnings and patterns
- When the
analystagent tracks costs or extracts patterns
Workflow Integration
Operates in Phase 0 (Orient) and Phase 6 (Reflect). Output supports the analyst agent.
References
| Reference | When to load | Content |
|---|---|---|
| capture-architecture.md | Before any agent-side memory write | The 2-path contract — ##prefix: is user-typed only; agents write via direct Edit |
| session-capture.md | Phase 6 | Capturing session learnings in 3 categories (patterns/decisions/failures) |
| pattern-extraction.md | Phase 6 | Extracting high-frequency patterns for instruction-file promotion |
| cost-tracking.md | Phase 0, 6 | Token usage tracking, cost reporting, budget alerts |
| consolidation.md | Manual | Prune stale entries, merge duplicates, archive cost data (run when memory grows large) |
How session-capture is invoked
session-capture is not a CLI subcommand. At Phase 6 (Reflect) the agent reads references/session-capture.md and follows its 4 steps using Read / Write / Edit directly. There is no mewkit memory session-capture script — content extraction requires LLM analysis that a static CLI cannot produce.
Subcommands
--prune
Archive old standard-severity entries from topic files to lessons-archive.md.
Topic files subject to pruning:
fixes.md— bug-class session learningsreview-patterns.md— process/review learningsarchitecture-decisions.md— architectural decision records
What gets pruned:
## headingswith a date(YYYY-MM-DD, severity: standard)older than threshold (default: 90 days)
What is exempt:
severity: criticalorseverity: securityentries — never pruned- Entries without a parseable date — kept as-is (safe default)
How to run:
/mk:memory --prune # default 90-day threshold
/mk:memory --prune --days 180 # custom threshold
/mk:memory --prune --dry-run # show what would be archived without moving
Mechanism (grep-based — no parser dependency):
- For each topic file: grep for
##headings + date pattern(YYYY-MM-DD, severity: standard) - Compute age from today's date; identify entries older than threshold
- Append stale entries to
.claude/memory/lessons-archive.md - Remove stale entry blocks from topic file (rewrite without them)
- Report: "Archived N entries across M files"
Recovery: Copy entries from lessons-archive.md back to the appropriate topic file.
Schema Notes
Split JSON files (fixes.json, review-patterns.json, architecture-decisions.json) all use v2.0.0 schema with fields: version, scope, consumer, patterns[], metadata. Each pattern entry supports: id, type, category, severity, domain, applicable_when, context, pattern, frequency, lastSeen.
Gotchas
- Stale patterns applied to changed codebase: Memory suggests patterns from old architecture → Run consolidation when patterns exceed 50 entries; flag patterns with lastSeen > 6 months
- cost-log.json growing unbounded: Every session appends without pruning → Run consolidation to archive entries older than 90 days
- lessons.md is now archived: Do not write to lessons.md — it is a stub. Write to topic files (fixes.md, architecture-decisions.md, review-patterns.md) instead.