Cortex debugging logs cleaned up

LOGGING_QUICK_REF.md

@@ -0,0 +1,176 @@
+# Cortex Logging Quick Reference
+
+## 🎯 TL;DR
+
+**Finding weak links in the LLM chain?**
+```bash
+export LOG_DETAIL_LEVEL=detailed
+export VERBOSE_DEBUG=true
+```
+
+**Production use?**
+```bash
+export LOG_DETAIL_LEVEL=summary
+```
+
+---
+
+## 📊 Log Levels Comparison
+
+| Level | Output Lines/Message | Use Case | Raw LLM Output? |
+|-------|---------------------|----------|-----------------|
+| **minimal** | 1-2 | Silent production | ❌ No |
+| **summary** | 5-7 | Production (DEFAULT) | ❌ No |
+| **detailed** | 30-50 | Debugging, finding bottlenecks | ✅ Parsed only |
+| **verbose** | 100+ | Deep debugging, seeing raw data | ✅ Full JSON |
+
+---
+
+## 🔍 Common Debugging Tasks
+
+### See Raw LLM Outputs
+```bash
+export LOG_DETAIL_LEVEL=verbose
+```
+Look for:
+```
+╭─ RAW RESPONSE ────────────────────────────────────
+│ { "choices": [ { "message": { "content": "..." } } ] }
+╰───────────────────────────────────────────────────
+```
+
+### Find Performance Bottlenecks
+```bash
+export LOG_DETAIL_LEVEL=detailed
+```
+Look for:
+```
+⏱️  Stage Timings:
+   reasoning      :  3450ms ( 76.0%)  ← SLOW!
+```
+
+### Check Which RAG Memories Are Used
+```bash
+export LOG_DETAIL_LEVEL=detailed
+```
+Look for:
+```
+╭─ RAG RESULTS (5) ──────────────────────────────
+│ [1] 0.923 | Memory content...
+```
+
+### Detect Loops
+```bash
+export ENABLE_DUPLICATE_DETECTION=true  # (default)
+```
+Look for:
+```
+⚠️  DUPLICATE MESSAGE DETECTED
+🔁 LOOP DETECTED - Returning cached context
+```
+
+### See All Backend Failures
+```bash
+export LOG_DETAIL_LEVEL=summary  # or higher
+```
+Look for:
+```
+⚠️  [LLM] PRIMARY failed | Connection timeout
+⚠️  [LLM] SECONDARY failed | Model not found
+✅ [LLM] CLOUD | Reply: Based on...
+```
+
+---
+
+## 🛠️ Environment Variables Cheat Sheet
+
+```bash
+# Verbosity Control
+LOG_DETAIL_LEVEL=detailed        # minimal | summary | detailed | verbose
+VERBOSE_DEBUG=false              # true = maximum verbosity (legacy)
+
+# Raw Data Visibility
+LOG_RAW_CONTEXT_DATA=false       # Show full intake L1-L30 dumps
+
+# Loop Protection
+ENABLE_DUPLICATE_DETECTION=true  # Detect duplicate messages
+MAX_MESSAGE_HISTORY=100          # Trim history after N messages
+SESSION_TTL_HOURS=24             # Expire sessions after N hours
+
+# Features
+NEOMEM_ENABLED=false             # Enable long-term memory
+ENABLE_AUTONOMOUS_TOOLS=true     # Enable tool invocation
+ENABLE_PROACTIVE_MONITORING=true # Enable suggestions
+```
+
+---
+
+## 📋 Sample Output
+
+### Summary Mode (Default - Production)
+```
+✅ [LLM] PRIMARY | 14:23:45.123 | Reply: Based on your question...
+📊 Context | Session: abc123 | Messages: 42 | Last: 5.2min | RAG: 5 results
+🧠 Monologue | question | Tone: curious
+✨ PIPELINE COMPLETE | Session: abc123 | Total: 1250ms
+📤 Output: 342 characters
+```
+
+### Detailed Mode (Debugging)
+```
+════════════════════════════════════════════════════════════════════════════
+🚀 PIPELINE START | Session: abc123 | 14:23:45.123
+════════════════════════════════════════════════════════════════════════════
+📝 User: What is the meaning of life?
+────────────────────────────────────────────────────────────────────────────
+
+────────────────────────────────────────────────────────────────────────────
+🧠 LLM CALL | Backend: PRIMARY | 14:23:45.234
+────────────────────────────────────────────────────────────────────────────
+📝 Prompt: You are Lyra, a thoughtful AI assistant...
+💬 Reply: Based on philosophical perspectives...
+
+📊 Context | Session: abc123 | Messages: 42 | Last: 5.2min | RAG: 5 results
+  ╭─ RAG RESULTS (5) ──────────────────────────────
+  │ [1] 0.923 | Previous philosophy discussion...
+  │ [2] 0.891 | Existential note...
+  ╰────────────────────────────────────────────────
+
+════════════════════════════════════════════════════════════════════════════
+✨ PIPELINE COMPLETE | Session: abc123 | Total: 1250ms
+════════════════════════════════════════════════════════════════════════════
+⏱️  Stage Timings:
+   context        :   150ms ( 12.0%)
+   reasoning      :   450ms ( 36.0%)  ← Largest component
+   persona        :   140ms ( 11.2%)
+📤 Output: 342 characters
+════════════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## ⚡ Quick Troubleshooting
+
+| Symptom | Check | Fix |
+|---------|-------|-----|
+| **Logs too verbose** | Current level | Set `LOG_DETAIL_LEVEL=summary` |
+| **Can't see LLM outputs** | Current level | Set `LOG_DETAIL_LEVEL=detailed` or `verbose` |
+| **Repeating operations** | Loop warnings | Check for `🔁 LOOP DETECTED` messages |
+| **Slow responses** | Stage timings | Look for stages >1000ms in detailed mode |
+| **Missing RAG data** | NEOMEM_ENABLED | Set `NEOMEM_ENABLED=true` |
+| **Out of memory** | Message history | Lower `MAX_MESSAGE_HISTORY` |
+
+---
+
+## 📁 Key Files
+
+- **[.env.logging.example](.env.logging.example)** - Full configuration guide
+- **[LOGGING_REFACTOR_SUMMARY.md](LOGGING_REFACTOR_SUMMARY.md)** - Detailed explanation
+- **[cortex/utils/logging_utils.py](cortex/utils/logging_utils.py)** - Logging utilities
+- **[cortex/context.py](cortex/context.py)** - Context + loop protection
+- **[cortex/router.py](cortex/router.py)** - Pipeline stages
+- **[core/relay/lib/llm.js](core/relay/lib/llm.js)** - LLM backend logging
+
+---
+
+**Need more detail? See [LOGGING_REFACTOR_SUMMARY.md](LOGGING_REFACTOR_SUMMARY.md)**