Claude-skill-registry-data memory

Unified four-tier memory system for AI agents. Tier 1 Semantic (Serena+Forgetful

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry-data

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry-data "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/memory" ~/.claude/skills/majiayu000-claude-skill-registry-data-memory-e0b3ca && rm -rf "$T"

manifest: data/memory/SKILL.md

source content

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

When to Use This Skill

Scenario	Use Memory Router?	Alternative
PowerShell script needs memory	✅ Yes	-
Agent needs deep context	❌ No	`context-retrieval` agent
Human at CLI	❌ No	`/memory-search` command
Cross-project semantic search	❌ No	Forgetful MCP directly

See context-retrieval agent for complete decision tree.

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:

pwsh .claude/skills/memory/scripts/Search-Memory.ps1 -Query "[topic]"

Review results for historical context
If insufficient, escalate to Tier 2/3
Document findings in decision rationale
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

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

Related Skills

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

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