Memory System Skill

Memory operations for AI agents using Brain MCP.

Quick Start

// Tier 1: Search memory (Semantic)
mcp__plugin_brain_brain__search({
  query: "git hooks",
  limit: 10,
  mode: "auto",
});

// Tier 1: List available memories
mcp__plugin_brain_brain__list_directory({
  dir_name: "/",
  depth: 2,
});

// Tier 1: Read specific memory
mcp__plugin_brain_brain__read_note({
  identifier: "usage-mandatory",
});

# Tier 2: Extract episode from session (Episodic)
bun run apps/claude-plugin/skills/memory/scripts/extract-episode.ts \
  --session SESSION-2026-01-20_06

# Tier 3: Add pattern (Causal)
bun run apps/claude-plugin/skills/memory/scripts/add-pattern.ts \
  --name "Memory-First Investigation" \
  --trigger "Agent wants to change existing system" \
  --action "Search memory before making changes" \
  --success-rate 0.95

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: mcp__plugin_brain_brain__search({ 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 [FUTURE]

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

Tier 3 (Causal): Decision patterns [FUTURE]

• •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. •mcp__plugin_brain_brain__search({ query: "[topic]" })
2. •Review results for historical context
3. •If insufficient, document gap (Tiers 2-3 not yet available)
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 ADR-007 for:

• •Memory-first architecture principles
• •Investigation protocol
• •Verification requirements
• •BLOCKING gate enforcement

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

Triggers

Quick Reference

Retrieval Depth Strategy

Use depth parameter to expand context via relations:

What do you need?
│
├─► Current facts, patterns, or rules?
│   └─► TIER 1: mcp__plugin_brain_brain__search()
│
├─► List available memories?
│   └─► TIER 1: mcp__plugin_brain_brain__list_directory()
│
├─► Read specific memory?
│   └─► TIER 1: mcp__plugin_brain_brain__read_note()
│
├─► What happened in a specific session?
│   ├─ Extract first: bun run scripts/extract-episode.ts [log-path]
│   └─► TIER 2: mcp__plugin_brain_brain__read_note({ identifier: "EPISODE-X" })
│
├─► Recent sessions with specific outcome?
│   └─► TIER 2: mcp__plugin_brain_brain__search({ query: "outcome:failure" })
│
├─► Why did decision X lead to outcome Y?
│   └─► TIER 3: Search related patterns, trace WikiLink relations
│
├─► What patterns have high success rate?
│   └─► TIER 3: mcp__plugin_brain_brain__search({ query: "success_rate:>0.7" })
│
├─► Need to store new knowledge?
│   ├─ Session complete? → bun run scripts/extract-episode.ts
│   ├─ Pattern discovered? → bun run scripts/add-pattern.ts
│   └─ Factual knowledge? → mcp__plugin_brain_brain__write_note()
│
└─► Not sure which tier?
    └─► Start with TIER 1 (search), escalate to Tier 2/3 if insufficient

Anti-Patterns

Storage Locations

Configuration: Memory paths configured in ~/.config/brain/config.json (see ADR-020).

Note: memories_location defaults to ~/memories but is configurable via brain config set memories-location <path>.

Notes:

• •Brain MCP tools handle path resolution automatically. Do not use hardcoded paths in agent instructions.
• •The memories_location default is ~/memories but can be configured per-project or globally.
• •ADR-020 defines three modes: DEFAULT, CODE, CUSTOM (see table above).

Verification

Related Skills

Write Operations Governance (BLOCKING)

References:

• •ADR-019: Memory Operations Governance (validation-based governance)
• •ADR-020: Configuration Architecture Refactoring (storage locations, terminology)

All agents MAY write to Brain memory using this skill.

The agent system uses one-level delegation. Subagents cannot delegate to other subagents. When orchestrator delegates to analyst, analyst must be able to write directly. Governance is achieved through pre-flight validation, not access control.

Non-compliant writes create governance debt:

• •Notes in wrong folders
• •Inconsistent naming (missing CAPS prefix)
• •Missing quality thresholds
• •Broken knowledge graph relations

All Agents Can Write (with Validation)

No delegation required. All agents write directly after completing validation.

Pre-Flight Validation (BLOCKING - All Agents)

Before calling write_note or edit_note, you MUST complete this checklist:

### Pre-Flight Checklist (MUST all pass before write)

- [ ] Entity type is valid (13 types only, see table below)
- [ ] Folder matches entity type (see mapping)
- [ ] File name follows CAPS prefix pattern
- [ ] Frontmatter has: title, type, tags (2-5)
- [ ] Observations section: 3-10 entries with categories
- [ ] Observation format: `- [category] content #tags`
- [ ] Relations section: 2-8 entries with wikilinks
- [ ] Relation format: `- relation_type [[Target Entity]]`

Agents that skip validation create governance debt. Post-hoc audit will detect violations.

Entity Type to Folder Mapping (Canonical)

File names MUST match the File Pattern exactly. The entity prefix MUST be ALL CAPS — ADR-, SESSION-, REQ-, etc. Never lowercase (adr-, session-, req-). This is non-negotiable; lowercase prefixes are malformed and will break lookups.

No generic NOTE-* type allowed. Forces proper categorization.

Specs folder naming: {ENTITY-NNN-topic} is the canonical name of the parent entity the spec belongs to. Use the parent's ALL CAPS prefix and kebab-case topic. Examples:

• •specs/ADR-015-auth-strategy/requirements/REQ-001-token-validation.md
• •specs/FEATURE-003-oauth/design/DESIGN-001-auth-flow.md
• •specs/EPIC-001-authentication/tasks/TASK-001-implement-jwt.md

Valid Observation Categories

[fact], [decision], [requirement], [technique], [insight],
[problem], [solution], [constraint], [risk], [outcome]

Source Attribution in Observations

Every observation should include provenance. Three methods:

Context in observation — source in parentheses:

- [decision] Using JWT tokens (decided in ADR-005) #auth
- [fact] Rate limit is 1000/hour (per API Documentation) #api

Wikilink to source — link to related entity:

- [decision] Using JWT tokens #auth
  - requires [[ADR-005 Auth Token Strategy]]

Tags for agent source — indicate which agent created observation:

- [insight] Auth failures spike at token expiry #pattern #analyst

Valid Relation Types

implements, depends_on, relates_to, extends, part_of,
inspired_by, contains, pairs_with, supersedes, leads_to, caused_by

Quality Thresholds

Example: Compliant Note Structure

The frontmatter title prefix MUST be ALL CAPS (ADR-019, not adr-019). Wikilink references MUST match the canonical title casing.

---
title: ADR-019 Memory Governance
type: decision
tags: [memory, governance, enforcement]
---

# ADR-019 Memory Governance

## Context

Agents writing to memory without conventions create governance debt.

## Observations

- [decision] Validation-based governance selected #architecture
- [fact] All agents retain direct write access #one-level-delegation
- [requirement] Pre-flight validation MUST pass before writes #blocking
- [technique] Memory skill provides validation guidance (not access control) #pattern

## Relations

- supersedes [[Ad-hoc Memory Writing]]
- implements [[ADR-007 Memory-First Architecture]]
- relates_to [[Session 06 Entity Standards]]

Write Operation Decision Tree

Need to write/edit a memory note?
│
├─► Run pre-flight validation checklist
│   │
│   ├─► All checks PASS: Proceed with write_note/edit_note
│   │
│   └─► Any check FAILS: Fix violations before writing
│       │
│       ├─► Wrong folder? Check entity type mapping
│       ├─► Missing CAPS prefix? Follow naming pattern
│       ├─► Too few observations? Add more facts/decisions
│       └─► No relations? Add 2+ wikilinks
│
├─► Unsure about conventions?
│   │
│   └─► Consult this skill for entity type mapping, naming patterns, examples
│
└─► Read/search operations: Always allowed directly (no validation needed)

All agents write directly. No delegation to memory agent required.

Storage Protocol

When to Store

Store frequently. Autocompaction, crashes, and session interruptions lose context. Incremental updates prevent information loss.

Anti-pattern: Large research task then single update at end. Correct pattern: Update note after each finding during research.

Create vs Update Decision

Always search before creating to prevent duplicates.

Curation Operations

Treat memories as living documents. Refine, reorganize, clarify continuously.

Append — add new observations, relations, or context:

mcp__plugin_brain_brain__edit_note
identifier: "[note-title]"
operation: "append"
content: "- [decision] Made choice X based on constraint Y #topic"

Prepend — add critical updates at top for visibility:

mcp__plugin_brain_brain__edit_note
identifier: "[note-title]"
operation: "prepend"
content: "- [problem] Critical issue discovered: Z #urgent"

Find/Replace — refine existing observations as understanding evolves:

mcp__plugin_brain_brain__edit_note
identifier: "[note-title]"
operation: "find_replace"
find_text: "- [idea] Might use approach A"
content: "- [decision] Decided on approach A after testing B #validated"

Replace Section — update entire sections when context changes:

mcp__plugin_brain_brain__edit_note
identifier: "[note-title]"
operation: "replace_section"
section: "Context"
content: "## Context\n[Updated context with new information]"

Freshness Protocol

Update Triggers

Update parent memory entities when downstream refinements occur:

Staleness Detection

Observations older than 30 days without updates should be reviewed:

1. •Mark for review: Add [REVIEW] tag if uncertain about accuracy
2. •Supersede if outdated: Create new observation with supersedes relation
3. •Archive if irrelevant: Move to archive folder or delete note

Conflict Resolution

When observations contradict:

1. •Prefer most recent observation
2. •Create relation with type supersedes
3. •Add [REVIEW] tag if uncertain

Session Log Creation

Session logs are stored in Brain memory under sessions/ folder.

mcp__plugin_brain_brain__write_note
title: "SESSION-YYYY-MM-DD_NN-topic"
folder: "sessions"
content: "[Session log template content]"

Session Log Template:

---
title: SESSION-YYYY-MM-DD_NN-topic
type: session
tags: [session, YYYY-MM-DD]
---

# Session NN - YYYY-MM-DD

## Session Info

- **Date**: YYYY-MM-DD
- **Branch**: [branch name]
- **Starting Commit**: [SHA]
- **Objective**: [What this session aims to accomplish]

## Protocol Compliance

[Session start checklist here]

## Work Log

### [Task/Topic]

**Status**: In Progress / Complete / Blocked

**What was done**:
- [Action taken]

**Decisions made**:
- [Decision]: [Rationale]

## Relations

- part_of [[Current Project]]
- leads_to [[Next Session Topic]]

Governance Access

Project governance documents are stored in Brain memory under governance/ folder:

At session start: Read handoff for current state. At session end: Update handoff with edit_note using replace_section on "Current State".

Entity naming is enforced by validators in both TypeScript and Go:

• •TypeScript: @brain/validation package (MCP runtime)
• •Go: packages/validation/internal/validate_consistency.go (CLI/hooks)
• •Parity: Cross-language tests ensure identical validation (packages/validation/src/__tests__/parity/)

See ADR-023 for validation architecture details.

Tier 2: Episodic Memory

Session replay via structured episode extraction. Reduces session logs from 10K-50K tokens to 500-2000 tokens.

Capabilities:

• •Extract structured episodes from completed session logs
• •Query past sessions by outcome/task/date
• •Read decision sequences and event timelines
• •95% token reduction vs full session logs

Architecture: Markdown notes in episodes/ folder with structured frontmatter, integrated with basic-memory knowledge graph.

Usage:

# Extract episode from completed session (reads from Brain memory)
bun run apps/claude-plugin/skills/memory/scripts/extract-episode.ts \
  --session SESSION-2026-01-20_06

# Query episodes by outcome
mcp__plugin_brain_brain__search({
  query: "outcome:failure",
  folder: "episodes",
  limit: 10
})

# Read specific episode
mcp__plugin_brain_brain__read_note({
  identifier: "EPISODE-2026-01-20-06"
})

Tier 3: Causal Graph

Decision pattern tracking with statistical validation. Prevents repeated mistakes through success rate tracking.

Capabilities:

• •Track cause-effect relationships via WikiLink relations
• •Success rate tracking for patterns (running average)
• •Anti-pattern detection (low success rate patterns)
• •Pattern queries via semantic search

Architecture: Pattern notes in patterns/ folder with typed WikiLink relations (causes, enables, prevents, correlates).

Usage:

# Add new pattern
bun run apps/claude-plugin/skills/memory/scripts/add-pattern.ts \
  --name "Memory-First Investigation" \
  --trigger "Agent wants to change existing system" \
  --action "Search memory before making changes" \
  --success-rate 0.95

# Query high success patterns
mcp__plugin_brain_brain__search({
  query: "success_rate:>0.7",
  folder: "patterns"
})

# Find antipatterns
mcp__plugin_brain_brain__search({
  query: "success_rate:<0.3",
  folder: "patterns"
})

Reference: See ADR-018 for complete episodic and causal memory architecture.