temporal

Overview ¶

Package temporal - Decay integration for adaptive memory retention.

DecayIntegration modifies NornicDB's decay system based on temporal patterns:

• Frequently accessed nodes decay SLOWER (important memories persist)
• Rarely accessed nodes decay FASTER (forgotten memories fade)
• Nodes with daily patterns maintain longer (routine knowledge)
• Burst-accessed nodes get temporary boost (current focus)

This creates a more human-like memory system where:

• Things you use often stay fresh
• Things you forget naturally fade
• Context matters (current session nodes are prioritized)

Integration points:

• DecayManager: Call GetDecayModifier() to adjust decay rate
• ArchiveManager: Call ShouldArchive() to identify cold nodes
• SearchRanker: Call GetRelevanceBoost() to rank results

ELI12 (Explain Like I'm 12) ¶

Your brain forgets things! But it's SMART about what it forgets:

🧠 Your best friend's name?     → NEVER forget (use it daily!)
🧠 What you had for lunch today → Remember for a bit, then forget
🧠 Random fact from 5 years ago → Probably already forgot it

DecayIntegration makes the database work like your brain:

The "decay" is like forgetting. Every memory slowly fades over time. But the Kalman filter velocity tells us HOW to adjust the forgetting speed:

📈 Velocity positive (accessing MORE often):
   "Hey, you're using this a lot lately - slow down the forgetting!"
   Decay multiplier: 0.1 (10x slower decay)

📉 Velocity negative (accessing LESS often):
   "You used to look at this every day, now it's been weeks..."
   Decay multiplier: 2.0 (2x faster decay)

📊 Velocity stable:
   "Normal usage pattern, normal forgetting speed"
   Decay multiplier: 1.0 (normal decay)

Special cases:

🔥 BURST: Looking at something 10 times RIGHT NOW?
   → "Super important right now!" → Nearly zero decay

📅 DAILY PATTERN: Access every morning at 9am?
   → "Part of your routine!" → Slower decay

❄️ COLD: Haven't touched in 2 weeks?
   → "Probably not important anymore" → Faster decay, maybe archive

The Kalman filter smooths out noise. If you access something once by accident, it doesn't suddenly become "important". It waits to see a TREND.

Package temporal - Pattern detection for cyclic access patterns.

PatternDetector identifies recurring access patterns such as:

• Daily patterns (e.g., accessed every morning at 9am)
• Weekly patterns (e.g., accessed on Mondays)
• Burst patterns (clusters of rapid accesses)
• Decay patterns (gradually decreasing access)

ELI12 (Explain Like I'm 12) ¶

Imagine you have a favorite YouTube video. The PatternDetector notices:

📊 Daily Pattern: "You watch this video every day at 7pm after dinner"
📊 Weekly Pattern: "You binge-watch on Saturdays"
📊 Burst Pattern: "You're watching 10 videos right NOW - probably bored!"
📊 Growing: "You're watching more and more cat videos each week"
📊 Decaying: "You used to watch daily, now it's been 2 weeks..."

The detector counts how often you do things at each hour (0-23) and each day (Sunday-Saturday). If one hour has WAY more than others, that's a pattern!

Example:

Hour  0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16 17 18 19 20 21 22 23
Count 0  0  0  0  0  0  0  0  2  45  3  2  1  0  1  2  1  0  0  0  1  0  0  0
                                 ^^
                           "9am is clearly your jam!"

The Kalman filter velocity tells us if you're watching MORE or LESS over time. Positive velocity = growing interest, Negative velocity = losing interest.

Package temporal - Query load prediction for resource scaling.

QueryLoadPredictor tracks query volume trends and predicts future load using KalmanVelocity filters. This enables:

• Predicting upcoming query spikes
• Detecting load trends (increasing/decreasing)
• Triggering pre-emptive resource scaling
• Identifying query patterns (peak hours, burst events)

Use cases:

• Auto-scale database connections
• Pre-warm caches before predicted spikes
• Alert on unusual load patterns
• Capacity planning

Example usage:

predictor := temporal.NewQueryLoadPredictor(temporal.DefaultLoadConfig())

// Record each query
predictor.RecordQuery()

// Get current load prediction
prediction := predictor.GetPrediction()
fmt.Printf("Current QPS: %.1f, Predicted (5min): %.1f\n",
    prediction.CurrentQPS, prediction.PredictedQPS)

// Check if scaling needed
if predictor.ShouldScaleUp(100) { // threshold QPS
    triggerScaleUp()
}

ELI12 (Explain Like I'm 12) ¶

Imagine you're running a lemonade stand. You want to know:

🍋 "How many customers are coming right now?" (Current QPS)
🍋 "Will it get busier or slower?" (Trend)
🍋 "Should I make more lemonade NOW?" (Scale up prediction)

The QueryLoadPredictor counts how many "questions" (queries) the database gets every second. It's like counting customers:

Second 1: 10 queries
Second 2: 12 queries
Second 3: 15 queries
Second 4: 20 queries
→ "Whoa, we're getting BUSIER! Velocity is positive!" 📈

The Kalman filter smooths out the bumps:

Raw counts:   10, 12, 50, 11, 13  (that 50 was a weird spike!)
Filtered:     10, 11, 15, 13, 13  (smoothed - ignores the spike)

Why filter? Because ONE busy second doesn't mean you need to panic! The filter asks: "Is this a REAL trend or just random noise?"

Predictions:

Current: 50 QPS (queries per second)
Velocity: +5 QPS/second (getting busier)
Predicted in 5 min: 50 + (5 × 300) = 1550 QPS! 😱
→ "Better scale up NOW before we're overwhelmed!"

Anomaly detection:

Normal: 50 QPS
Suddenly: 500 QPS ← "SPIKE! Something's happening!"
Suddenly: 5 QPS ← "DROP! Did something break?"

Peak hour detection:

Hour    0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16 17 18 19 20 21 22 23
Count   2  1  1  1  2  5  15 30 50 45 40 30 35 40 50 45 40 35 25 20 15 10 5  3
                              ^^^^^^^^^^^^
                    "Peak hours are 8-10am and 2-4pm"

This lets us PREPARE before the rush! Pre-warm caches at 7:30am! 🚀

Package temporal - Relationship evolution tracking for dynamic graphs.

RelationshipEvolution tracks how edge weights change over time using KalmanVelocity filters. This enables:

• Detecting strengthening relationships (increasing co-access)
• Detecting weakening relationships (decreasing relevance)
• Predicting future relationship strength
• Identifying emerging connections

Use cases:

• Recommend strengthening edges for pre-fetching
• Prune weakening edges to save memory
• Detect new relationship patterns automatically
• Power dynamic graph visualizations

Example usage:

re := temporal.NewRelationshipEvolution(temporal.DefaultRelationshipConfig())

// Record co-access (updates edge weight)
re.RecordCoAccess("node-1", "node-2", 1.0)

// Get relationship trend
trend := re.GetTrend("node-1", "node-2")
fmt.Printf("Relationship is %s (velocity: %.3f)\n", trend.Direction, trend.Velocity)

// Predict future strength
future := re.PredictStrength("node-1", "node-2", 10)
fmt.Printf("In 10 steps, strength will be: %.3f\n", future)

ELI12 (Explain Like I'm 12) ¶

Think about your friendships. Some get STRONGER over time, some fade:

👫 Best friend in 1st grade → Moved away → Don't talk anymore (WEAKENING)
👫 New kid at school → Hang out more → Now best friends! (STRENGTHENING)
👫 Neighbor → See them same amount → Just neighbors (STABLE)

RelationshipEvolution tracks how "connected" two things are, and whether that connection is growing or shrinking.

In a database, "relationships" are like friendships between data:

📚 "JavaScript" ←→ "React" : Strong connection (always accessed together)
📚 "JavaScript" ←→ "Python": Weak connection (rarely together)

The Kalman filter tracks the TREND:

Week 1: JS+React accessed together 10 times
Week 2: JS+React accessed together 15 times
Week 3: JS+React accessed together 20 times
→ Velocity is POSITIVE! Relationship is STRENGTHENING! 📈

Week 1: JS+Python accessed together 5 times
Week 2: JS+Python accessed together 3 times
Week 3: JS+Python accessed together 1 time
→ Velocity is NEGATIVE! Relationship is WEAKENING! 📉

Why this matters:

✅ STRENGTHENING relationships: Pre-fetch! If you access JS, also load React
❌ WEAKENING relationships: Maybe delete the connection, save memory
🌱 EMERGING relationships: "Ooh, this is new and growing fast - watch it!"

The Kalman filter makes this smooth. One weird week doesn't change everything. It looks for REAL TRENDS, not random noise.

Package temporal - Session detection via velocity changes.

SessionDetector identifies user context switches by monitoring:

• Time gaps between accesses
• Sudden changes in access rate (velocity)
• Pattern breaks (different time-of-day)

Sessions are important for:

• Co-access inference (nodes accessed in same session are related)
• Context-aware search (prioritize current session nodes)
• Memory consolidation (sessions = semantic boundaries)

ELI12 (Explain Like I'm 12) ¶

Think about how you use your phone. You might:

📱 Morning: Check weather → Check email → Check news (WORK SESSION)
☕ Coffee break
📱 Later: Instagram → TikTok → YouTube (FUN SESSION)

The SessionDetector notices when you switch between "modes":

How it detects session changes:

1. TIME GAP: If you stop for 5+ minutes, that's probably a new session "You were looking at work stuff, went to lunch, now you're on games"

2. VELOCITY CHANGE (the Kalman filter magic!): The filter tracks HOW FAST you're accessing things. If velocity suddenly changes, your "mode" changed!

   Before: accessing every 2 seconds (fast browsing) After: accessing every 30 seconds (reading something) → "Whoa, you slowed WAY down - new session!"

Why does this matter for memory?

Session 1: [Weather, Email, News] → These are probably related (work stuff)
Session 2: [Instagram, TikTok]    → These are probably related (fun stuff)

So if you search for "weather", we boost Email and News because they were accessed in the SAME SESSION. That's co-access inference!

Package temporal provides temporal pattern tracking and prediction for NornicDB.

This package tracks when nodes are accessed and uses Kalman filtering to:

• Smooth noisy access patterns
• Predict when nodes will be accessed next
• Detect session boundaries (context switches)
• Identify cyclic patterns (daily, weekly, etc.)

The temporal system integrates with NornicDB's decay system to:

• Slow decay for frequently accessed nodes
• Speed decay for abandoned nodes
• Predict archival candidates

Example usage:

tracker := temporal.NewTracker(temporal.DefaultConfig())

// Record accesses
tracker.RecordAccess("node-123")
tracker.RecordAccess("node-456")

// Get predictions
prediction := tracker.PredictNextAccess("node-123")
fmt.Printf("Node likely accessed in %.1f seconds\n", prediction.SecondsUntil)

// Check for session change
if tracker.IsSessionBoundary("node-123") {
	fmt.Println("User context has changed!")
}

ELI12 (Explain Like I'm 12) ¶

Imagine you're keeping a diary of when your friends visit:

📅 Monday:    Sarah came at 3pm
📅 Tuesday:   Sarah came at 3pm
📅 Wednesday: Sarah came at 3:15pm
📅 Thursday:  ???

The Tracker is like a smart diary that notices patterns:

🧠 "Sarah visits around 3pm every day"
🧠 "Mike comes on weekends"
🧠 "Random friend hasn't visited in 2 weeks - maybe forgot about us?"

The Kalman filter is the "smart" part. When Sarah came at 3:15pm on Wednesday, instead of panicking ("OMG she's 15 minutes late!"), it smoothly updates:

Before: "Sarah comes at 3:00pm"
After:  "Sarah comes around 3:03pm" (small adjustment)

It's like averaging, but SMARTER because it:

• Trusts patterns more than single weird events
• Notices if someone is visiting MORE or LESS often (velocity)
• Can predict: "At this rate, Sarah will visit at 2:50pm next week"

Why Kalman instead of simple averaging?

• Simple average: "3pm + 3pm + 3:15pm = 3:05pm average"
• Kalman: "3pm, 3pm, then 3:15pm... she might be getting later, or maybe it was just traffic. I'll say 3:03pm and watch for more data."

The Kalman filter LEARNS the trend (velocity) and uses it to predict!