Memory Consolidation System - Quick Reference

Overview

Energy-based memory consolidation system for Milo's cognitive architecture with automatic tier promotion and expiry.

Key Commands

Regular Use

# Manual consolidation (usually automatic via /goodbye)
brainBridge --brain=milo -consolidateAll
brainBridge --brain=milo -promoteMemories

# Check memory status
brainBridge --brain=milo -memoryStatus
brainBridge --brain=milo -memoryHealth

Testing & Development

# Create test memory
brainBridge --brain=milo -testMemory "content" <energy> <tier>

# Test operations (only affect test memories)
brainBridge --brain=milo -decayEnergy --testOnly
brainBridge --brain=milo -promoteMemories --testOnly
brainBridge --brain=milo -consolidateAll --testOnly

# List test memories
brainBridge --brain=milo -listTestMemories

# Boost memory energy
brainBridge --brain=milo -boostMemory <memoryId>

Energy System

Decay Formula

E(t) = E₀ × e^(-λt)

Decay Constants (λ)

• Working Memory: 0.5 (fast decay)
• Short-term Memory: 0.05 (moderate decay)
• Long-term Memory: 0.001 (very slow decay)

Promotion Thresholds

• Working → Short-term: Energy > 2.0
• Short-term → Long-term: Energy > 5.0
• Expiry: Energy < 0.1

Initial Energy Levels

• Crystallizations: 3.0 (high importance insights)
• Reminders: 2.5 (important to remember)
• Learnings: 2.0 (moderate importance knowledge)

Architecture

Memory Node Properties

{
  id: randomUUID(),
  content: "memory content",
  tier: "working" | "shortTerm" | "longTerm" | "expired",
  energy: 3.0,
  created: datetime(),
  lastAccessed: datetime(),
  lastDecay: datetime(),
  accessCount: 1,
  isTest: false,  // true for test memories
  memoryType: "crystallization" | "learning" | "reminder",
  sourceNodeId: "original_node_id",
  validFrom: datetime(),
  validTo: null  // set when archived
}

Relationships

• (OriginalNode)-[:HAS_MEMORY]->(Memory) - Links source to memory
• (OldMemory)-[:PROMOTED_TO]->(NewMemory) - Tracks promotion history

File Locations

Core Implementation

• Main code: /Users/tqwhite/Documents/webdev/botWorld/system/code/cli/lib.d/brain-bridge/brainBridge.js
• Goodbye hook: /Users/tqwhite/.claude/commands/WISE/goodbye.md
• Logs: /Users/tqwhite/Documents/webdev/botWorld/system/code/cli/lib.d/wise-friend/brain/logs/consolidation.log

Documentation

• Full process: /Users/tqwhite/Documents/webdev/botWorld/system/management/zNotesPlansDocs/memoryConsolidationProcess.md
• This reference: /Users/tqwhite/Documents/webdev/botWorld/system/management/zNotesPlansDocs/memoryConsolidationQuickReference.md

Automatic Consolidation

The system automatically consolidates memories when you use the /goodbye command:

1. Energy decay applied to all memories
2. Expired memories (energy < 0.1) marked with tier='expired'
3. High-energy memories promoted to next tier
4. All operations logged to consolidation.log
5. Runs asynchronously in background (fire-and-forget with &)

Testing Strategy

1. Create test memories with varying energy levels
2. Run consolidation with --testOnly flag
3. Verify promotions occur at correct thresholds
4. Check logs for operation details
5. Use -memoryStatus to verify tier distribution

Monitoring

Check consolidation log for operation history:

tail -f /Users/tqwhite/Documents/webdev/botWorld/system/code/cli/lib.d/wise-friend/brain/logs/consolidation.log | jq '.'

Troubleshooting

Common Issues

• Memories not promoting: Check energy levels and thresholds
• Test memories affecting real: Ensure isTest flag is set correctly
• Consolidation not running: Check /goodbye hook is properly configured
• Duplicate memories: Verify randomUUID() is used for all Memory nodes

Debug Commands

# View all memories with details
brainBridge --brain=milo "MATCH (m:Memory) WHERE m.validTo IS NULL RETURN m ORDER BY m.energy DESC"

# Check consolidation config
brainBridge --brain=milo "MATCH (c:ConsolidationConfig) RETURN c"

# View promotion history
brainBridge --brain=milo "MATCH (m1:Memory)-[:PROMOTED_TO]->(m2:Memory) RETURN m1, m2"

Implementation Notes

• Parallel System: Memory nodes exist alongside traditional nodes for backward compatibility
• Test Isolation: isTest flag ensures test operations don't affect real memories
• Cypher Limitations: Complex consolidation split into separate decay and promotion operations
• Background Processing: Uses & for async execution during /goodbye

Last updated: 2025-09-08