memory

Unified four-tier memory system for AI agents. Tier 1 Semantic (Serena+Forgetful search), Tier 2 Episodic (session replay), Tier 3 Causal (decision patterns). Enables memory-first architecture per ADR-007.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026

When & Why to Use This Skill

The Memory System Skill is a sophisticated four-tier memory framework designed for AI agents to implement a 'memory-first' architecture. By integrating semantic, episodic, and causal memory layers, it enables agents to retrieve historical context, learn from past session outcomes, and understand the underlying rationale behind complex codebases. This skill effectively implements the 'Chesterton's Fence' principle, ensuring agents do not modify or remove existing logic until they fully comprehend why it was established, thereby significantly reducing regressions and production incidents in autonomous development.

Use Cases

  • Historical Rationale Investigation: Before refactoring complex or 'ugly' code, the agent searches semantic memory to discover past incidents or ADRs (Architecture Decision Records) that explain the necessity of the current implementation.
  • Failure Analysis and Prevention: Extracting 'episodes' from failed sessions to identify specific edge cases and ensure the agent recognizes and avoids similar pitfalls in future tasks.
  • Causal Pattern Recognition: Analyzing the causal graph to determine which decision patterns consistently lead to successful outcomes, allowing the agent to optimize its strategy for high-stakes workflows.
  • Architectural Guardrails: Implementing a 'blocking gate' that forces the agent to verify memory before changing system protocols or deleting significant blocks of code, ensuring compliance with long-term project constraints.
  • Knowledge Persistence: Storing and retrieving facts, patterns, and rules across different sessions to maintain a consistent understanding of project-specific requirements and PowerShell-only constraints.
namememory
version0.2.0
descriptionUnified four-tier memory system for AI agents. Tier 1 Semantic (Serena+Forgetful
licenseMIT
modelclaude-sonnet-4-5
adrADR-037, ADR-038
timelessness8/10

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:

Change Type Memory Search Required
Remove ADR constraint Search-Memory.ps1 -Query "[constraint name]"
Bypass protocol Search-Memory.ps1 -Query "[protocol name] why"
Delete >100 lines Search-Memory.ps1 -Query "[component] purpose"
Refactor complex code Search-Memory.ps1 -Query "[component] edge case"
Change workflow Search-Memory.ps1 -Query "[workflow] rationale"

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

Trigger Phrase Maps To
"search memory for X" Tier 1: Search-Memory.ps1
"what do we know about X" Tier 1: Search-Memory.ps1
"extract episode from session" Tier 2: Extract-SessionEpisode.ps1
"what happened in session X" Tier 2: Get-Episode -SessionId "X"
"find sessions with failures" Tier 2: Get-Episodes -Outcome "failure"
"update causal graph" Tier 3: Update-CausalGraph.ps1
"what patterns led to success" Tier 3: Get-Patterns
"check memory health" Test-MemoryHealth.ps1

Quick Reference

Operation Name Key Parameters
Search facts/patterns Search-Memory.ps1 -Query, -LexicalOnly, -MaxResults
Get single session Get-Episode -SessionId
Find multiple sessions Get-Episodes -Outcome, -Task, -Since
Trace causation Get-CausalPath -FromLabel, -ToLabel
Find success patterns Get-Patterns -MinSuccessRate
Extract episode Extract-SessionEpisode.ps1 -SessionLogPath
Update patterns Update-CausalGraph.ps1 -EpisodePath, -DryRun
Health check Test-MemoryHealth.ps1 -Format (Json/Table)

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

Anti-Pattern Do This Instead
Skipping memory search Always search before multi-step reasoning
Tier confusion Follow decision tree explicitly
Forgetful dependency Use -LexicalOnly fallback
Stale causal graph Run Update-CausalGraph.ps1 after extractions
Incomplete extraction Only extract from COMPLETED sessions

See Also

Document Content
quick-start.md Common workflows
skill-reference.md Detailed script parameters
tier-selection-guide.md When to use each tier
memory-router.md ADR-037 router architecture
reflexion-memory.md ADR-038 episode/causal schemas
troubleshooting.md Error recovery
benchmarking.md Performance targets
agent-integration.md Multi-agent patterns

Storage Locations

Data Location
Serena memories .serena/memories/*.md
Forgetful memories HTTP MCP (vector DB)
Episodes .agents/memory/episodes/*.json
Causal graph .agents/memory/causality/causal-graph.json

Verification

Operation Verification
Search completed Result count > 0 OR logged "no results"
Episode extracted JSON file in .agents/memory/episodes/
Graph updated Stats show nodes/edges added
Health check All tiers show "available: true"
pwsh .claude/skills/memory/scripts/Test-MemoryHealth.ps1 -Format Table

Skill When to Use Instead
using-forgetful-memory Deep Forgetful operations (create, update, link)
curating-memories Memory maintenance (obsolete, deduplicate)
exploring-knowledge-graph Multi-hop graph traversal