/memory-evolution

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
• **