Memory System Skill

Unified memory operations across four tiers for AI agents.

Quick Start

# Check system health
pwsh .claude/skills/memory/scripts/Test-MemoryHealth.ps1

# Search memory (Tier 1)
pwsh .claude/skills/memory/scripts/Search-Memory.ps1 -Query "git hooks"

# Extract episode from session (Tier 2)
pwsh .claude/skills/memory/scripts/Extract-SessionEpisode.ps1 -SessionLogPath ".agents/sessions/2026-01-01-session-126.md"

# Update causal graph (Tier 3)
pwsh .claude/skills/memory/scripts/Update-CausalGraph.ps1

Memory-First as Chesterton's Fence

Core Insight: Memory-first architecture implements Chesterton's Fence principle for AI agents.

"Do not remove a fence until you know why it was put up" - G.K. Chesterton

Translation for agents: Do not change code/architecture/protocol until you search memory for why it exists.

Why This Matters

Without memory search (removing fence without investigation):

• Agent encounters complex code, thinks "this is ugly, I'll refactor it"
• Removes validation logic that prevents edge case
• Production incident occurs
• Memory contains past incident that explains why validation existed

With memory search (Chesterton's Fence investigation):

• Agent encounters complex code
• Searches memory: Search-Memory.ps1 -Query "validation logic edge case"
• Finds past incident explaining why code exists
• Makes informed decision: preserve, modify, or replace with equivalent safety

Investigation Protocol

When you encounter something you want to change:

What Memory Contains (Git Archaeology)

Tier 1 (Semantic): Facts, patterns, constraints

• Why does PowerShell-only constraint exist? (ADR-005)
• Why do skills exist instead of raw CLI? (usage-mandatory)
• What incidents led to BLOCKING gates? (protocol-blocking-gates)

Tier 2 (Episodic): Past session outcomes

• What happened when we tried approach X? (session replay)
• What edge cases did we encounter? (failure episodes)

Tier 3 (Causal): Decision patterns

• What decisions led to success? (causal paths)
• What patterns should we repeat/avoid? (success/failure patterns)

Memory-First Gate (BLOCKING)

Before changing existing systems, you MUST:

1. pwsh .claude/skills/memory/scripts/Search-Memory.ps1 -Query "[topic]"
2. Review results for historical context
3. If insufficient, escalate to Tier 2/3
4. Document findings in decision rationale
5. Only then proceed with change

Why BLOCKING: <50% compliance with "check memory first" guidance. Making it BLOCKING achieves 100% compliance (same pattern as session protocol gates).

Verification: Session logs must show memory search BEFORE decisions, not after.

Connection to Chesterton's Fence Analysis

See .agents/analysis/chestertons-fence.md for:

• 4-phase decision framework (Investigation → Understanding → Evaluation → Action)
• Application to ai-agents project (ADR-037 recursion guard, skills-first violations)
• Decision matrix for when to investigate
• Implementation checklist

Key takeaway: Memory IS your investigation tool. It contains the "why" that Chesterton's Fence requires you to discover.

Triggers

Quick Reference

Decision Tree

What do you need?
│
├─► Current facts, patterns, or rules?
│   └─► TIER 1: Search-Memory.ps1
│
├─► What happened in a specific session?
│   └─► TIER 2: Get-Episode -SessionId "..."
│
├─► Recent sessions with specific outcome?
│   └─► TIER 2: Get-Episodes -Outcome "failure" -Since 7days
│
├─► Why did decision X lead to outcome Y?
│   └─► TIER 3: Get-CausalPath -FromLabel "..." -ToLabel "..."
│
├─► What patterns have high success rate?
│   └─► TIER 3: Get-Patterns -MinSuccessRate 0.7
│
├─► Need to store new knowledge?
│   ├─ From completed session? → Extract-SessionEpisode.ps1
│   └─ Factual knowledge? → using-forgetful-memory skill
│
└─► Not sure which tier?
    └─► Start with TIER 1 (Search-Memory), escalate if insufficient

Anti-Patterns

See Also

Storage Locations

Verification

pwsh .claude/skills/memory/scripts/Test-MemoryHealth.ps1 -Format Table

Related Skills