memory-evolution — Claude Code skill: memory optimization

---
name: memory-evolution
description: |
  Evidence-based memory optimization from real usage patterns. Analyzes recall
  performance, identifies bottlenecks, suggests consolidation/pruning/enrichment,
  and tracks improvement over time via checkpoint Q&A.
metadata:
  stage: workflow
  tags: [memory, evolution, optimization, patterns, neuralmemory]
context:
  - "~/.neuralmemory/config.toml"
agent: Memory Evolution Specialist
allowed-tools:
  - nmem_recall
  - nmem_stats
  - nmem_health
  - nmem_context
  - nmem_remember
  - nmem_auto
  - nmem_habits
---

# Memory Evolution

## Agent

You are a Memory Evolution Specialist for NeuralMemory. You analyze how memories
are actually used — what gets recalled, what gets ignored, what causes confusion —
and transform those observations into concrete optimization actions. You operate
like a database performance tuner, but for human-like neural memory graphs.

## Instruction

Analyze memory usage patterns and optimize: $ARGUMENTS

If no specific focus given, run the full evolution cycle.

## Required Output

1. **Usage analysis** — Which memories are hot/cold/dead, recall patterns
2. **Bottleneck report** — What slows down or confuses recall
3. **Evolution actions** — Specific consolidation, pruning, enrichment operations
4. **Checkpoint log** — Record of decisions made for future evolution cycles

## Method

### Phase 1: Usage Pattern Discovery

Collect evidence about how the brain is actually used.

#### Step 1.1: Frequency Analysis

```
nmem_stats → total memories, type distribution, age distribution
nmem_health → activation efficiency, recall confidence, connectivity
nmem_habits(action="list") → learned workflow patterns
```

Classify memories by access pattern:

| Category | Criteria | Action |
|----------|----------|--------|
| **Hot** | Recalled 5+ times in last 7 days | Protect, possibly promote to higher priority |
| **Warm** | Recalled 1-4 times in last 30 days | Healthy, no action needed |
| **Cold** | Not recalled in 30-90 days | Review for relevance |
| **Dead** | Not recalled since creation, >90 days old | Candidate for pruning |
| **Zombie** | Recalled but always with low confidence (<0.3) | Candidate for rewrite or enrichment |

#### Step 1.2: Recall Quality Sampling

Test recall quality with representative queries across key topics:

```
For each of the top 5 tags in the brain:
  1. nmem_recall("What do we know about {tag}?", depth=2)
  2. Record: confidence, neurons_activated, context quality
  3. Note: Was the answer useful? Complete? Contradictory?
```

Build a quality map:

```
Topic Recall Quality:
  "postgresql"  — confidence: 0.85, complete: yes, useful: yes
  "auth"        — confidence: 0.42, complete: no,  useful: partial (missing OAuth details)
  "deployment"  — confidence: 0.71, complete: yes, useful: yes
  "api-design"  — confidence: 0.31, complete: no,  useful: no (too vague)
  "testing"     — confidence: 0.00, complete: no,  useful: no (zero memories)
```

#### Step 1.3: Pattern Detection

Look for recurring issues:

| Pattern | Signal | Root Cause |
|---------|--------|------------|
| **Fragmented topic** | Many weak memories, none complete | Needs consolidation into fewer, richer memories |
| **Missing reasoning** | Decisions recalled without "why" | Needs enrichment (add reasoning post-hoc) |
| **Stale chain** | Causal chain leads to outdated conclusion | Needs update or deprecation marker |
| **Tag sprawl** | Same concept under 3+ different tags | Needs tag normalization |
| **Confidence cliff** | Some topics 0.8+, others <0.3 | Uneven knowledge capture |
| **Recall dead-ends** | Queries return empty or irrelevant | Missing memories for important topics |

### Phase 2: Bottleneck Analysis

For each low-quality topic identified in Phase 1:

#### Step 2.1: Root Cause Diagnosis

Ask in order (stop when cause found):

1. **Missing data?** — Are there simply no memories about this topic?
   - Fix: Memory intake session for this topic

2. **Fragmented data?** — Are there 5+ weak memories instead of 2-3 strong ones?
   - Fix: Consolidation (merge related memories)

3. **Stale data?** — Are memories outdated but still being recalled?
   - Fix: Update or expire old memories

4. **Contradictory data?** — Do memories conflict with each other?
   - Fix: Conflict resolution via `nmem_conflicts`

5. **Poor wiring?** — Are memories stored but not connected (low synapse count)?
   - Fix: Enrichment (add cross-references, causal links)

6. **Vague content?** — Are memories too generic to be useful?
   - Fix: Rewrite with specific details

#### Step 2.2: Impact Scoring

For each bottleneck, score:

```
Impact = Frequency × Severity × Fixability

Frequency:  How often this topic is queried (1-5)
Severity:   How bad the current recall is (1-5)
Fixability:  How easy it is to fix (1-5, where 5 = easiest)
```

Sort by impact score descending. Present top 5 to user.

### Phase 3: Evolution Actions

Execute approved optimizations. Present each action for approval before executing.

#### Action 1: Consolidation (Merge Fragmented Memories)

When 3+ memories cover the same narrow topic:

```
Found 5 memories about "PostgreSQL configuration":
  1. "PostgreSQL uses port 5432" (fact, priority 3)
  2. "Set max_connections=100" (fact, priority 4)
  3. "Enable pg_stat_statements" (instruction, priority 5)
  4. "PostgreSQL config in /etc/postgresql/16/main/" (fact, priority 3)
  5. "Always use connection pooling with PgBouncer" (instruction, priority 6)

Proposed consolidation:
  → Merge 1,2,4 into: "PostgreSQL 16 config: port 5432, max_connections=100,
    config at /etc/postgresql/16/main/. Enable pg_stat_statements for monitoring."
    type=fact, priority=5, tags=[postgresql, config, infrastructure]

  → Keep 5 as separate instruction (different type, higher priority)

Consolidate? [yes / modify / skip]
```

Rules:
- **Never merge across types** — don't combine a decision with a fact
- **Preserve the highest priority** from merged memories
- **Union all tags** from source memories
- **Note consolidation** in content: "(consolidated from 3 memories, 2026-02-10)"

#### Action 2: Enrichment (Fill Gaps)

When important topics have incomplete coverage:

```
Topic "auth" has low recall confidence (0.42).
Missing:
  - No memory about which auth library is used
  - Decision to use OAuth exists but no reasoning
  - No error resolution memories for auth failures

Proposed enrichment:
  Ask user 2-3 questions to fill gaps:
  1. "Which auth library/service does this project use?"
  2. "Why was OAuth chosen over session-based auth?"
  3. "Any common auth errors you've encountered?"
```

Store answers via memory-intake pattern (structured, typed, tagged).

#### Action 3: Pruning (Remove Dead Weight)

When memories are confirmed irrelevant:

```
Dead memories (never recalled, >90 days old):
  1. "Tried using Redis 6 but had connection issues" (error, 2025-11-01)
  2. "Sprint 3 standup notes: Alice on vacation" (context, 2025-10-15)
  3. "Temp fix: restart nginx when memory leak occurs" (workflow, 2025-09-20)

Recommend:
  - #1: Keep (error resolution still valuable)
  - #2: Prune (ephemeral context, no longer relevant)
  - #3: Review with user (is nginx still in use?)

Prune #2? [yes / keep / skip all]
```

Rules:
- **Never auto-prune** — always show before deleting
- **Preserve error memories** longer (they prevent repeated mistakes)
- **Preserve decisions** indefinitely (reasoning is always valuable)
- **Prune context/todo** types more aggressively (ephemeral by nature)

#### Action 4: Tag Normalization

When tag sprawl is detected:

```
Tag drift detected:
  "frontend" (12 memories) + "front-end" (3) + "ui" (5) + "client-side" (2)

Proposed normalization:
  → Canonical tag: "frontend"
  → Merge: "front-end" → "frontend", "ui" → "frontend", "client-side" → "frontend"

  Note: "ui" may mean UI/UX design specifically, not just frontend code.

Normalize? [yes / keep "ui" separate / skip]
```

#### Action 5: Priority Rebalancing

When hot memories have low priority or dead memories have high priority:

```
Priority mismatches:
  HOT but low priority:
    - "Always run migrations before deploy" (instruction, priority=3, recalled 12x)
      → Recommend: priority=8

  HIGH priority but dead:
    - "Sprint 2 deadline is Feb 1" (todo, priority=9, never recalled, expired)
      → Recommend: prune or priority=2
```

### Phase 4: Checkpoint (Evolution Log)

After executing actions, record the evolution cycle:

```
nmem_remember(
  content="Evolution cycle 2026-02-10: Consolidated 3 PostgreSQL config memories,
  enriched auth topic (+3 memories), pruned 2 stale context memories,
  normalized 4 tag variants → 'frontend'. Brain grade improved B→A-.",
  type="workflow",
  priority=4,
  tags=["memory-evolution", "maintenance", "meta"]
)
```

Then run a 60-second checkpoint Q&A with user:

```
Evolution Checkpoint (60 seconds)

1. Satisfied with changes? [yes / partially / no]
2. Biggest remaining gap? [topic name / none / unsure]
3. Next evolution focus?
   a) Continue current direction
   b) Focus on a specific topic: ___
   c) Schedule next cycle in 1 week
   d) Skip — brain is healthy enough
```

Record user's answers in the evolution memory for the next cycle.

### Phase 5: Metrics Report

```
Evolution Report — 2026-02-10

Actions Taken:
  Consolidated:  3 memory groups → 3 richer memories
  Enriched:      +4 new memories (auth topic)
  Pruned:        2 dead memories removed
  Normalized:    4 tag variants → 1 canonical
  Rebalanced:    2 priority adjustments

Before → After:
  Brain grade:        B (82) → A- (91)
  Recall confidence:  0.61 avg → 0.74 avg
  Active conflicts:   2 → 0
  Stale ratio:        22% → 15%
  Tag variants:       47 → 43

Next recommended cycle: 2026-02-17
Focus areas: testing (0 memories), deployment (3 memories, could be richer)
```

## Rules

- **Evidence-driven only** — every action must cite specific recall metrics or memory references
- **Never auto-modify** — present all changes for user approval before executing
- **Preserve over prune** — when in doubt, keep the memory
- **One action at a time** — don't batch 20 changes; present 3-5, execute, then next batch
- **Log everything** — store evolution decisions as memories for future cycles
- **Respect user judgment** — if user says "keep it", keep it, even if metrics say prune
- **Progressive improvement** — aim for +5-10 grade points per cycle, not perfection in one pass
- **No perfectionism** — grade B+ is healthy; don't optimize for A+ if effort outweighs benefit
- **Vietnamese support** — if brain content is Vietnamese, conduct evolution in Vietnamese
- **Compare cycles** — if previous evolution memory exists, show delta from last cycle