memory-evolution
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.
- Installs
- 748
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/nhadaututtheky/neural-memory --skill memory-evolution- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads memory-evolution automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
- Usage analysis — Which memories are hot/cold/dead, recall patterns
- Bottleneck report — What slows down or confuses recall
- Evolution actions — Specific consolidation, pruning, enrichment operations
- 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):
-
Missing data? — Are there simply no memories about this topic?
- Fix: Memory intake session for this topic
-
Fragmented data? — Are there 5+ weak memories instead of 2-3 strong ones?
- Fix: Consolidation (merge related memories)
-
Stale data? — Are memories outdated but still being recalled?
- Fix: Update or expire old memories
-
Contradictory data? — Do memories conflict with each other?
- Fix: Conflict resolution via
nmem_conflicts
- Fix: Conflict resolution via
-
Poor wiring? — Are memories stored but not connected (low synapse count)?
- Fix: Enrichment (add cross-references, causal links)
-
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
FAQ
What does the memory-evolution skill do?
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.
How do I install memory-evolution?
Run npx skills add https://github.com/nhadaututtheky/neural-memory --skill memory-evolution in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/memory-evolution/ (personal) or .claude/skills/memory-evolution/ (project).
Which AI agents can use memory-evolution?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is memory-evolution safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains memory-evolution?
It is published by nhadaututtheky in nhadaututtheky/neural-memory. It has 748 recorded installs.
More from nhadaututtheky/neural-memory
memory-intake
nhadaututtheky/neural-memory
Structured memory creation workflow. Converts messy notes, conversations, and unstructured thoughts into well-typed, tagged, confidence-scored memories. Uses 1-question-at-a-time clarification to avoid cognitive overload.
memory-audit
nhadaututtheky/neural-memory
Comprehensive memory quality review across 6 dimensions: purity, freshness, coverage, clarity, relevance, and structure. Generates prioritized findings with specific memory references and actionable recommendations.
neural-memory
nhadaututtheky/neural-memory
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.