Neural Memory

neural-memory

Purpose

Bridges Rune's file-based persistence (session-bridge, journal) with Neural Memory MCP's semantic graph. While session-bridge saves decisions to .rune/ files and journal tracks ADRs locally, neural-memory captures cross-project learnable patterns — decisions, error root causes, architectural insights, and workflow preferences — into a persistent cognitive layer that compounds across every project and session.

Without this skill, each project is an island. With it, a caching pattern discovered in Project A auto-surfaces when Project B faces a similar problem.

Triggers

Auto-trigger:

• Session start → Run Recall Mode (load relevant context before any work)
• After cook completes a feature → Run Capture Mode (save learnings)
• After debug finds root cause → Run Capture Mode (save error pattern)
• After review finds issues → Run Capture Mode (save code quality insight)
• After rescue completes a phase → Run Capture Mode (save refactoring pattern)
• After journal writes an ADR → Run Capture Mode (extract to nmem)
• Session end / before compaction → Run Flush Mode (capture remaining context)

Manual trigger:

• /rune recall <topic> — search neural memory for a topic
• /rune remember <text> — save a specific memory
• /rune brain-health — check neural memory health + maintenance
• /rune hypothesize <question> — start hypothesis tracking

Calls (outbound)

• session-bridge (L3): after Capture Mode — sync key decisions back to .rune/ files

Called By (inbound)

• cook (L1): Phase 0 (resume) + Phase 8 (complete) — recall context at start, capture learnings at end
• rescue (L1): phase start + phase end — recall past refactoring patterns, capture new ones
• debug (L2): after root cause found — capture error pattern for future recognition
• fix (L2): after fix verified — capture fix pattern (cause → solution)
• review (L2): after review complete — capture code quality insight
• plan (L2): before architecture decisions — recall past decisions on similar problems
• sentinel (L2): after security finding — capture vulnerability pattern
• incident (L2): after resolution — capture incident root cause + fix
• retro (L2): during retrospective — capture retro insights and patterns
• session-bridge (L3): Step 6 (cross-project extraction) — extract generalizable patterns
• journal (L3): after ADR written — extract decision + rejected alternatives
• context-engine (L3): before compaction — trigger Flush Mode to preserve context

Modes

Mode 1: Recall (Session Start / Before Decisions)

Load relevant context from neural memory before starting work.

Step 1 — Identify Recall Topics Read .rune/progress.md and current task context to determine 3-5 diverse recall topics. Always prefix queries with the project name to avoid cross-project noise.

Copy code
GOOD: "Rune compiler cross-reference resolution"
GOOD: "MyTrend PocketBase auth session handling"
BAD:  "cross-reference" (too generic, returns all projects)
BAD:  "auth" (returns noise from every project)

Step 2 — Execute Recall Call nmem_recall for each topic. Use diverse angles:

• Technology-specific: "<project> React state management"
• Problem-specific: "<project> caching strategy decision"
• Pattern-specific: "<project> error handling approach"

Step 3 — Synthesize Context Summarize recalled memories into actionable context:

• Decisions that apply to current task
• Patterns that worked (or failed) before
• Constraints or preferences from past sessions
• Open hypotheses still being tracked

Step 4 — Surface Gaps If recall returns thin results for the current domain, note the gap. Call nmem_gaps(action="detect") if working in a domain with sparse memories.

Mode 2: Capture (After Task Completion)

Extract learnable patterns from completed work and save to neural memory.

Step 1 — Classify What Happened Determine which memory types to create from the completed task:

Step 2 — Craft Rich Memories Each memory MUST use cognitive language patterns for strong neural connections:

Copy code
BAD:  "PostgreSQL" (flat, no context — orphan neuron)
GOOD: "Chose PostgreSQL over MongoDB because ACID needed for payment processing"

BAD:  "Fixed auth bug" (no root cause — useless for future recall)
GOOD: "Auth cookie expired silently because SameSite=Lax blocked cross-origin. Fixed by setting SameSite=None + Secure flag"

BAD:  "React project structure" (vague — won't match specific queries)
GOOD: "Rune compiler uses 3-stage pipeline: Parse SKILL.md → Transform cross-refs → Emit per-platform files"

Cognitive patterns to use:

• Causal: "X caused Y because Z", "Root cause was X which led to Y"
• Temporal: "After upgrading to v3, the middleware broke because of new cookie format"
• Decisional: "Chose X over Y because Z", "Rejected X due to Y"
• Comparative: "X is 3x faster than Y for read-heavy workloads"
• Relational: "X depends on Y", "X replaced Y", "X connects to Y through Z"

Step 3 — Tag and Prioritize Every memory MUST include:

• Tags: [project-name, technology, topic] — lowercase, specific
• Priority: 5 (normal), 7-8 (important decisions/errors), 9-10 (critical security/breaking)
• Max length: 1-3 sentences. If longer, split into focused pieces.

Step 4 — Save Memories Call nmem_remember for each memory. Save 2-5 memories per completed task:

• A bug fix has: root cause, fix approach, prevention insight
• A feature has: architecture decision, pattern used, trade-off made
• A review has: quality issue found, fix suggestion, pattern to avoid

Step 5 — Reinforce Connections After saving, call nmem_recall on the topic to reinforce new neural connections. This activates related neurons and strengthens the memory graph.

Mode 3: Hypothesis Tracking

Track uncertain decisions with evidence over time.

Step 1 — Form Hypothesis When making an uncertain architectural or design decision:

Copy code
nmem_hypothesize("Redis will handle our session load better than Memcached
                   because our access pattern is 80% reads with complex data types")

Step 2 — Collect Evidence As you work, update the hypothesis with evidence:

Copy code
nmem_evidence(hypothesis_id, "Redis handled 10K concurrent sessions with
              p99 < 5ms in load test — SUPPORTS hypothesis")

nmem_evidence(hypothesis_id, "Memory usage 2x higher than Memcached estimate
              — WEAKENS hypothesis for memory-constrained deployments")

Step 3 — Make Predictions Create falsifiable predictions:

Copy code
nmem_predict("If we switch to Redis Cluster, session failover time will drop
              from 30s to < 2s")

Step 4 — Verify Outcomes After deployment/testing, verify:

Copy code
nmem_verify(prediction_id, outcome="Failover time dropped to 1.2s — CONFIRMED")

Mode 4: Flush (Session End / Pre-Compaction)

Capture remaining context before session ends.

Step 1 — Scan Unsaved Context Review the current session for:

• Decisions made but not yet captured
• Errors encountered and their resolutions
• Patterns discovered during exploration
• User preferences expressed

Step 2 — Batch Save Call nmem_auto(action="process", text="<session summary>") with a concise summary of the session's key outcomes, decisions, and learnings.

Step 3 — Update Session Bridge If significant decisions were captured, also call session-bridge to sync the most important ones to .rune/decisions.md for local persistence.

Mode 5: Maintenance (Weekly / On-Demand)

Keep the neural memory healthy and useful.

Step 1 — Health Check Call nmem_health() to assess brain status. Key metrics:

• Consolidation % (low = run consolidation)
• Orphan % (>20% = prune disconnected memories)
• Activation levels (low = recall more diverse topics)
• Connectivity (low = use richer cognitive language)
• Diversity (low = vary memory types)

Step 2 — Consolidation If brain has >100 memories or consolidation is low:

Copy code
nmem_consolidate  — merge episodic → semantic memories

Step 3 — Review Queue Call nmem_review(action="queue") to surface memories needing attention:

• Outdated decisions that may no longer apply
• Low-confidence memories that need evidence
• Wall-of-text memories (>500 chars) that should be split

Step 4 — Corrections Fix bad memories:

• Wrong type → nmem_edit(memory_id, type="correct_type")
• Wrong content → nmem_edit(memory_id, content="corrected text")
• Outdated → nmem_forget(memory_id, reason="outdated")
• Sensitive/garbage → nmem_forget(memory_id, hard=true)

Step 5 — Connection Tracing Use nmem_explain(entity_a, entity_b) to trace paths between concepts. Useful for understanding why certain memories surface together.

Output Format

Recall Report

Copy code
## Neural Memory Recall — <project>

### Loaded Context
- <memory 1 summary — decision/pattern/insight>
- <memory 2 summary>
- <memory 3 summary>

### Applicable to Current Task
- <how memory X applies>
- <how memory Y applies>

### Gaps Detected
- <domain with sparse coverage>

Capture Report

Copy code
## Neural Memory Capture — <task summary>

### Saved Memories
| # | Type | Priority | Tags | Content (preview) |
|---|------|----------|------|--------------------|
| 1 | decision | 7 | [project, tech, topic] | Chose X over Y because... |
| 2 | error | 7 | [project, bug, tech] | Root cause was X... |
| 3 | insight | 6 | [project, pattern] | This codebase uses... |

### Reinforced Topics
- <topic recalled to strengthen connections>

Health Report

Copy code
## Neural Memory Health

| Metric | Value | Status |
|--------|-------|--------|
| Total memories | N | — |
| Consolidation | N% | ✅ / ⚠️ |
| Orphans | N% | ✅ / ⚠️ |
| Activation | level | ✅ / ⚠️ |
| Top penalty | <metric> | Fix: <action> |

### Recommended Actions
1. <action with command>

Constraints

1. MUST prefix all recall queries with project name — generic queries return cross-project noise that confuses the AI. The ONLY exception is intentional cross-project searches.
2. MUST use rich cognitive language — flat facts ("X exists") create orphan neurons with zero connections. Every memory MUST include WHY, BECAUSE, or relationship context.
3. MUST NOT save wall-of-text memories — max 1-3 sentences per memory. Split longer content into focused pieces. Memories >500 chars degrade recall quality.
4. MUST NOT duplicate file-based state — don't save task progress, file paths, or git history to nmem. Those belong in .rune/ files (session-bridge) or git. nmem is for learnable patterns only.
5. MUST save 2-5 memories per completed task — a single memory per task is insufficient. Capture the decision, the reasoning, the pattern, and the prevention insight separately.
6. MUST NOT save sensitive data — no API keys, passwords, tokens, or PII. Mask or omit sensitive values.
7. MUST tag every memory — always include [project-name, technology, topic]. Tags enable future recall precision.

Sharp Edges

Done When

Recall Mode:

• 3-5 diverse topics recalled with project-name prefix
• Applicable context summarized for current task
• Gaps noted if coverage is thin

Capture Mode:

• 2-5 memories saved with rich cognitive language
• All memories tagged with [project, technology, topic]
• Priority assigned (5-10 scale)
• Connections reinforced via post-save recall

Flush Mode:

• All significant unsaved decisions captured
• nmem_auto called with session summary
• Session-bridge synced if major decisions made

Maintenance Mode:

• nmem_health run and metrics assessed
• Top penalty addressed with specific action
• Review queue processed (outdated/bloated memories fixed)

Cost Profile

• Recall: ~200-500 tokens (3-5 queries + synthesis)
• Capture: ~300-600 tokens (2-5 memories + reinforcement)
• Flush: ~100-300 tokens (auto-process + sync)
• Maintenance: ~500-1000 tokens (health + consolidate + review)
• Hypothesis: ~200-400 tokens per hypothesis lifecycle