fix: [SOVEREIGNTY] Audit NostrIdentity for side-channel timing attacks (closes #801)

Auto-merged by Timmy

FINDINGS-issue-801.md

@@ -0,0 +1,305 @@
+# Security Audit: NostrIdentity BIP340 Schnorr Signatures — Timing Side-Channel Analysis
+
+**Issue:** #801
+**Repository:** Timmy_Foundation/the-nexus
+**File:** `nexus/nostr_identity.py`
+**Auditor:** mimo-v2-pro swarm worker
+**Date:** 2026-04-10
+
+---
+
+## Summary
+
+The pure-Python BIP340 Schnorr signature implementation in `NostrIdentity` has **multiple timing side-channel vulnerabilities** that could allow an attacker with precise timing measurements to recover the private key. The implementation is suitable for prototyping and non-adversarial environments but **must not be used in production** without the fixes described below.
+
+---
+
+## Architecture
+
+The Nostr sovereign identity system consists of two files:
+
+- **`nexus/nostr_identity.py`** — Pure-Python secp256k1 + BIP340 Schnorr signature implementation. No external dependencies. Contains `NostrIdentity` class for key generation, event signing, and pubkey derivation.
+- **`nexus/nostr_publisher.py`** — Async WebSocket publisher that sends signed Nostr events to public relays (damus.io, nos.lol, snort.social).
+- **`app.js` (line 507)** — Browser-side `NostrAgent` class uses **mock signatures** (`mock_id`, `mock_sig`), not real crypto. Not affected.
+
+---
+
+## Vulnerabilities Found
+
+### 1. Branch-Dependent Scalar Multiplication — CRITICAL
+
+**Location:** `nostr_identity.py:41-47` — `point_mul()`
+
+```python
+def point_mul(p, n):
+    r = None
+    for i in range(256):
+        if (n >> i) & 1:        # <-- branch leaks Hamming weight
+            r = point_add(r, p)
+        p = point_add(p, p)
+    return r
+```
+
+**Problem:** The `if (n >> i) & 1` branch causes `point_add(r, p)` to execute only when the bit is 1. An attacker measuring signature generation time can determine which bits of the scalar are set, recovering the private key from a small number of timed signatures.
+
+**Severity:** CRITICAL — direct private key recovery.
+
+**Fix:** Use a constant-time double-and-always-add algorithm:
+
+```python
+def point_mul(p, n):
+    r = (None, None)
+    for i in range(256):
+        bit = (n >> i) & 1
+        r0 = point_add(r, p)         # always compute both
+        r = r0 if bit else r          # constant-time select
+        p = point_add(p, p)
+    return r
+```
+
+Or better: use Montgomery ladder which avoids point doubling on the identity.
+
+---
+
+### 2. Branch-Dependent Point Addition — CRITICAL
+
+**Location:** `nostr_identity.py:28-39` — `point_add()`
+
+```python
+def point_add(p1, p2):
+    if p1 is None: return p2       # <-- branch leaks operand state
+    if p2 is None: return p1       # <-- branch leaks operand state
+    (x1, y1), (x2, y2) = p1, p2
+    if x1 == x2 and y1 != y2: return None  # <-- branch leaks equality
+    if x1 == x2:                          # <-- branch leaks equality
+        m = (3 * x1 * x1 * inverse(2 * y1, P)) % P
+    else:
+        m = ((y2 - y1) * inverse(x2 - x1, P)) % P
+    ...
+```
+
+**Problem:** Multiple conditional branches leak whether inputs are the identity point, whether x-coordinates are equal, and whether y-coordinates are negations. Combined with the scalar multiplication above, this gives an attacker detailed timing information about intermediate computations.
+
+**Severity:** CRITICAL — compounds the scalar multiplication leak.
+
+**Fix:** Replace with a branchless point addition using Jacobian or projective coordinates with dummy operations:
+
+```python
+def point_add(p1, p2):
+    # Use Jacobian coordinates; always perform full addition
+    # Use conditional moves (simulated with arithmetic masking)
+    # for selecting between doubling and addition paths
+```
+
+---
+
+### 3. Branch-Dependent Y-Parity Check in Signing — HIGH
+
+**Location:** `nostr_identity.py:57-58` — `sign_schnorr()`
+
+```python
+R = point_mul(G, k)
+if R[1] % 2 != 0:       # <-- branch leaks parity of R's y-coordinate
+    k = N - k
+```
+
+**Problem:** The conditional negation of `k` based on the y-parity of R leaks information about the nonce through timing. While less critical than the point_mul leak (it's a single bit), combined with other leaks it aids key recovery.
+
+**Severity:** HIGH
+
+**Fix:** Use arithmetic masking:
+
+```python
+R = point_mul(G, k)
+parity = R[1] & 1
+k = (k * (1 - parity) + (N - k) * parity) % N  # constant-time select
+```
+
+---
+
+### 4. Non-Constant-Time Modular Inverse — MEDIUM
+
+**Location:** `nostr_identity.py:25-26` — `inverse()`
+
+```python
+def inverse(a, n):
+    return pow(a, n - 2, n)
+```
+
+**Problem:** CPython's built-in `pow()` with 3 args uses Montgomery ladder internally, which is *generally* constant-time for fixed-size operands. However:
+- This is an implementation detail, not a guarantee.
+- PyPy, GraalPy, and other Python runtimes may use different algorithms.
+- The exponent `n-2` has a fixed Hamming weight for secp256k1's `N`, so this specific case is less exploitable, but relying on it is fragile.
+
+**Severity:** MEDIUM — implementation-dependent; low risk on CPython specifically.
+
+**Fix:** Implement Fermat's little theorem inversion with blinding, or use a dedicated constant-time GCD algorithm (extended binary GCD).
+
+---
+
+### 5. Non-RFC6979 Nonce Generation — LOW (but non-standard)
+
+**Location:** `nostr_identity.py:55`
+
+```python
+k = int.from_bytes(sha256(privkey.to_bytes(32, 'big') + msg_hash), 'big') % N
+```
+
+**Problem:** The nonce derivation is `SHA256(privkey || msg_hash)` which is deterministic but doesn't follow RFC6979 (HMAC-based DRBG). Issues:
+- Not vulnerable to timing (it's a single hash), but could be vulnerable to related-message attacks if the same key signs messages with predictable relationships.
+- BIP340 specifies `tagged_hash("BIP0340/nonce", ...)` with specific domain separation, which is not used here.
+
+**Severity:** LOW — not a timing issue but a cryptographic correctness concern.
+
+**Fix:** Follow RFC6979 or BIP340's tagged hash approach:
+
+```python
+def sign_schnorr(msg_hash, privkey):
+    # BIP340 nonce generation with tagged hash
+    t = privkey.to_bytes(32, 'big')
+    if R_y_is_odd:
+        t = bytes(b ^ 0x01 for b in t)  # negate if needed
+    k = int.from_bytes(tagged_hash("BIP0340/nonce", t + pubkey + msg_hash), 'big') % N
+```
+
+---
+
+### 6. Private Key Bias in Random Generation — LOW
+
+**Location:** `nostr_identity.py:69`
+
+```python
+self.privkey = int.from_bytes(os.urandom(32), 'big') % N
+```
+
+**Problem:** `os.urandom(32)` produces values in `[0, 2^256)`, while `N` is slightly less than `2^256`. The modulo reduction introduces a negligible bias (~2^-128). Not exploitable in practice, but not the cleanest approach.
+
+**Severity:** LOW — theoretically biased, practically unexploitable.
+
+**Fix:** Use rejection sampling or derive from a hash:
+
+```python
+def generate_privkey():
+    while True:
+        candidate = int.from_bytes(os.urandom(32), 'big')
+        if 0 < candidate < N:
+            return candidate
+```
+
+---
+
+### 7. No Scalar/Point Blinding — MEDIUM
+
+**Location:** Global — no blinding anywhere in the implementation.
+
+**Problem:** The implementation has no countermeasures against:
+- **Power analysis** (DPA/SPA) on embedded systems
+- **Cache-timing attacks** on shared hardware (VMs, cloud)
+- **Electromagnetic emanation** attacks
+
+Adding random blinding to scalar multiplication (multiply by `r * r^-1` where `r` is random) would significantly raise the bar for side-channel attacks beyond simple timing.
+
+**Severity:** MEDIUM — not timing-specific, but important for hardening.
+
+---
+
+## What's NOT Vulnerable (Good News)
+
+1. **The JS-side `NostrAgent` in `app.js`** uses mock signatures (`mock_id`, `mock_sig`) — not real crypto, not affected.
+2. **`nostr_publisher.py`** correctly imports and uses `NostrIdentity` without modifying its internals.
+3. **The hash functions** (`sha256`, `hmac_sha256`) use Python's `hashlib` which delegates to OpenSSL — these are constant-time.
+4. **The JSON serialization** in `sign_event()` is deterministic and doesn't leak timing.
+
+---
+
+## Recommended Fix (Full Remediation)
+
+### Priority 1: Replace with secp256k1-py or coincurve (IMMEDIATE)
+
+The fastest, most reliable fix is to stop using the pure-Python implementation entirely:
+
+```python
+# nostr_identity.py — replacement using coincurve
+import coincurve
+import hashlib
+import json
+import os
+
+class NostrIdentity:
+    def __init__(self, privkey_hex=None):
+        if privkey_hex:
+            self.privkey = bytes.fromhex(privkey_hex)
+        else:
+            self.privkey = os.urandom(32)
+        self.pubkey = coincurve.PrivateKey(self.privkey).public_key.format(compressed=True)[1:].hex()
+
+    def sign_event(self, event):
+        event_data = [0, event['pubkey'], event['created_at'], event['kind'], event['tags'], event['content']]
+        serialized = json.dumps(event_data, separators=(',', ':'))
+        msg_hash = hashlib.sha256(serialized.encode()).digest()
+        event['id'] = msg_hash.hex()
+        # Use libsecp256k1's BIP340 Schnorr (constant-time C implementation)
+        event['sig'] = coincurve.PrivateKey(self.privkey).sign_schnorr(msg_hash).hex()
+        return event
+```
+
+**Effort:** ~2 hours (swap implementation, add `coincurve` to `requirements.txt`, test)
+**Risk:** Adds a C dependency. If pure-Python is required (sovereignty constraint), use Priority 2.
+
+### Priority 2: Pure-Python Constant-Time Rewrite (IF PURE PYTHON REQUIRED)
+
+If the sovereignty constraint (no C dependencies) must be maintained, rewrite the elliptic curve operations:
+
+1. **Replace `point_mul`** with Montgomery ladder (constant-time by design)
+2. **Replace `point_add`** with Jacobian coordinate addition that always performs both doubling and addition, selecting with arithmetic masking
+3. **Replace `inverse`** with extended binary GCD with blinding
+4. **Fix nonce generation** to follow RFC6979 or BIP340 tagged hashes
+5. **Fix key generation** to use rejection sampling
+
+**Effort:** ~8-12 hours (careful implementation + test vectors from BIP340 spec)
+**Risk:** Pure-Python crypto is inherently slower (~100ms per signature vs ~1ms with libsecp256k1)
+
+### Priority 3: Hybrid Approach
+
+Use `coincurve` when available, fall back to pure-Python with warnings:
+
+```python
+try:
+    import coincurve
+    USE_LIB = True
+except ImportError:
+    USE_LIB = False
+    import warnings
+    warnings.warn("Using pure-Python Schnorr — vulnerable to timing attacks. Install coincurve for production use.")
+```
+
+**Effort:** ~3 hours
+
+---
+
+## Effort Estimate
+
+| Fix | Effort | Risk Reduction | Recommended |
+|-----|--------|----------------|-------------|
+| Replace with coincurve (Priority 1) | 2h | Eliminates all timing issues | YES — do this |
+| Pure-Python constant-time rewrite (Priority 2) | 8-12h | Eliminates timing issues | Only if no-C constraint is firm |
+| Hybrid (Priority 3) | 3h | Full for installed, partial for fallback | Good compromise |
+| Findings doc + PR (this work) | 2h | Documents the problem | DONE |
+
+---
+
+## Test Vectors
+
+The BIP340 specification includes test vectors at https://github.com/bitcoin/bips/blob/master/bip-00340/test-vectors.csv
+
+Any replacement implementation MUST pass all test vectors before deployment.
+
+---
+
+## Conclusion
+
+The pure-Python BIP340 Schnorr implementation in `NostrIdentity` is **vulnerable to timing side-channel attacks** that could recover the private key. The primary issue is branch-dependent execution in scalar multiplication and point addition. The fastest fix is replacing with `coincurve` (libsecp256k1 binding). If pure-Python sovereignty is required, a constant-time rewrite using Montgomery ladder and arithmetic masking is needed.
+
+The JS-side `NostrAgent` in `app.js` uses mock signatures and is not affected.
+
+**Recommendation:** Ship `coincurve` replacement immediately. It's 2 hours of work and eliminates the entire attack surface.

app.js

@@ -4,6 +4,7 @@ import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
 import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
 import { SMAAPass } from 'three/addons/postprocessing/SMAAPass.js';
 import { SpatialMemory } from './nexus/components/spatial-memory.js';
+import { SessionRooms } from './nexus/components/session-rooms.js';
 
 // ═══════════════════════════════════════════
 // NEXUS v1.1 — Portal System Update
@@ -705,6 +706,7 @@ async function init() {
   createWorkshopTerminal();
   createAshStorm();
   SpatialMemory.init(scene);
+  SessionRooms.init(scene, camera, null);
   updateLoad(90);
 
   loadSession();
@@ -1883,7 +1885,7 @@ function setupControls() {
       orbitState.lastX = e.clientX;
       orbitState.lastY = e.clientY;
       
-      // Raycasting for portals
+      // Raycasting for portals and memory crystals
       if (!portalOverlayActive) {
         const mouse = new THREE.Vector2(
           (e.clientX / window.innerWidth) * 2 - 1,
@@ -1891,12 +1893,43 @@ function setupControls() {
         );
         const raycaster = new THREE.Raycaster();
         raycaster.setFromCamera(mouse, camera);
-        const intersects = raycaster.intersectObjects(portals.map(p => p.ring));
-        if (intersects.length > 0) {
-          const clickedRing = intersects[0].object;
+
+        // Priority 1: Portals
+        const portalHits = raycaster.intersectObjects(portals.map(p => p.ring));
+        if (portalHits.length > 0) {
+          const clickedRing = portalHits[0].object;
           const portal = portals.find(p => p.ring === clickedRing);
-          if (portal) activatePortal(portal);
+          if (portal) { activatePortal(portal); return; }
         }
+
+        // Priority 2: Memory crystals (Mnemosyne)
+        const crystalMeshes = SpatialMemory.getCrystalMeshes();
+        if (crystalMeshes.length > 0) {
+          const crystalHits = raycaster.intersectObjects(crystalMeshes, false);
+          if (crystalHits.length > 0) {
+            const hitMesh = crystalHits[0].object;
+            const memInfo = SpatialMemory.getMemoryFromMesh(hitMesh);
+            if (memInfo) {
+              SpatialMemory.highlightMemory(memInfo.data.id);
+              showMemoryPanel(memInfo, e.clientX, e.clientY);
+              return;
+            }
+          }
+        }
+
+        // Priority 3: Session rooms (Mnemosyne #1171)
+        const roomMeshes = SessionRooms.getClickableMeshes();
+        if (roomMeshes.length > 0) {
+          const roomHits = raycaster.intersectObjects(roomMeshes, false);
+          if (roomHits.length > 0) {
+            const session = SessionRooms.handleRoomClick(roomHits[0].object);
+            if (session) { _showSessionRoomPanel(session); return; }
+          }
+        }
+
+        // Clicked empty space — dismiss panel
+        dismissMemoryPanel();
+        _dismissSessionRoomPanel();
       }
     }
   });
@@ -2551,6 +2584,226 @@ function focusPortal(portal) {
 let lastThoughtTime = 0;
 let pulseTimer = 0;
 
+
+// ═══════════════════════════════════════════
+//  MNEMOSYNE — MEMORY CRYSTAL INSPECTION
+// ═══════════════════════════════════════════
+
+// ── pin state for memory panel ──
+let _memPanelPinned = false;
+
+/** Convert a packed hex color integer to "r,g,b" string for CSS rgba(). */
+function _hexToRgb(hex) {
+  return ((hex >> 16) & 255) + ',' + ((hex >> 8) & 255) + ',' + (hex & 255);
+}
+
+/**
+ * Position the panel near the screen click coordinates, keeping it on-screen.
+ */
+function _positionPanel(panel, clickX, clickY) {
+  const W = window.innerWidth;
+  const H = window.innerHeight;
+  const panelW = 356; // matches CSS width + padding
+  const panelH = 420; // generous estimate
+  const margin = 12;
+
+  let left = clickX + 24;
+  if (left + panelW > W - margin) left = clickX - panelW - 24;
+  left = Math.max(margin, Math.min(W - panelW - margin, left));
+
+  let top = clickY - 80;
+  top = Math.max(margin, Math.min(H - panelH - margin, top));
+
+  panel.style.right = 'auto';
+  panel.style.top = top + 'px';
+  panel.style.left = left + 'px';
+  panel.style.transform = 'none';
+}
+
+/**
+ * Navigate to (highlight + show panel for) a memory crystal by id.
+ */
+function _navigateToMemory(memId) {
+  SpatialMemory.highlightMemory(memId);
+  addChatMessage('system', `Focus: ${memId.replace(/_/g, ' ')}`);
+  const meshes = SpatialMemory.getCrystalMeshes();
+  for (const mesh of meshes) {
+    if (mesh.userData && mesh.userData.memId === memId) {
+      const memInfo = SpatialMemory.getMemoryFromMesh(mesh);
+      if (memInfo) { showMemoryPanel(memInfo); break; }
+    }
+  }
+}
+
+/**
+ * Show the holographic detail panel for a clicked crystal.
+ * @param {object} memInfo  — { data, region } from SpatialMemory.getMemoryFromMesh()
+ * @param {number} [clickX] — screen X of the click (for panel positioning)
+ * @param {number} [clickY] — screen Y of the click
+ */
+function showMemoryPanel(memInfo, clickX, clickY) {
+  const panel = document.getElementById('memory-panel');
+  if (!panel) return;
+
+  const { data, region } = memInfo;
+  const regionDef = SpatialMemory.REGIONS[region] || SpatialMemory.REGIONS.working;
+  const colorHex = regionDef.color.toString(16).padStart(6, '0');
+  const colorRgb = _hexToRgb(regionDef.color);
+
+  // Header — region dot + label
+  document.getElementById('memory-panel-region').textContent = regionDef.label;
+  document.getElementById('memory-panel-region-dot').style.background = '#' + colorHex;
+
+  // Category badge
+  const badge = document.getElementById('memory-panel-category-badge');
+  if (badge) {
+    badge.textContent = (data.category || region || 'memory').toUpperCase();
+    badge.style.background = 'rgba(' + colorRgb + ',0.16)';
+    badge.style.color = '#' + colorHex;
+    badge.style.borderColor = 'rgba(' + colorRgb + ',0.4)';
+  }
+
+  // Entity name (humanised id)
+  const entityEl = document.getElementById('memory-panel-entity-name');
+  if (entityEl) entityEl.textContent = (data.id || '\u2014').replace(/_/g, ' ');
+
+  // Fact content
+  document.getElementById('memory-panel-content').textContent = data.content || '(empty)';
+
+  // Trust score bar
+  const strength = data.strength != null ? data.strength : 0.7;
+  const trustFill = document.getElementById('memory-panel-trust-fill');
+  const trustVal  = document.getElementById('memory-panel-trust-value');
+  if (trustFill) {
+    trustFill.style.width = (strength * 100).toFixed(0) + '%';
+    trustFill.style.background = '#' + colorHex;
+  }
+  if (trustVal) trustVal.textContent = (strength * 100).toFixed(0) + '%';
+
+  // Meta rows
+  document.getElementById('memory-panel-id').textContent = data.id || '\u2014';
+  document.getElementById('memory-panel-source').textContent = data.source || 'unknown';
+  document.getElementById('memory-panel-time').textContent = data.timestamp ? new Date(data.timestamp).toLocaleString() : '\u2014';
+
+  // Related entities — clickable links
+  const connEl = document.getElementById('memory-panel-connections');
+  connEl.innerHTML = '';
+  if (data.connections && data.connections.length > 0) {
+    data.connections.forEach(cid => {
+      const btn = document.createElement('button');
+      btn.className = 'memory-conn-tag memory-conn-link';
+      btn.textContent = cid.replace(/_/g, ' ');
+      btn.title = 'Go to: ' + cid;
+      btn.addEventListener('click', (ev) => { ev.stopPropagation(); _navigateToMemory(cid); });
+      connEl.appendChild(btn);
+    });
+  } else {
+    connEl.innerHTML = '<span style="color:var(--color-text-muted)">None</span>';
+  }
+
+  // Pin button — reset on fresh open
+  _memPanelPinned = false;
+  const pinBtn = document.getElementById('memory-panel-pin');
+  if (pinBtn) {
+    pinBtn.classList.remove('pinned');
+    pinBtn.title = 'Pin panel';
+    pinBtn.onclick = () => {
+      _memPanelPinned = !_memPanelPinned;
+      pinBtn.classList.toggle('pinned', _memPanelPinned);
+      pinBtn.title = _memPanelPinned ? 'Unpin panel' : 'Pin panel';
+    };
+  }
+
+  // Positioning — near click if coords provided
+  if (clickX != null && clickY != null) {
+    _positionPanel(panel, clickX, clickY);
+  }
+
+  // Fade in
+  panel.classList.remove('memory-panel-fade-out');
+  panel.style.display = 'flex';
+}
+
+/**
+ * Dismiss the panel (respects pin). Called on empty-space click.
+ */
+function dismissMemoryPanel() {
+  if (_memPanelPinned) return;
+  _dismissMemoryPanelForce();
+}
+
+/**
+ * Force-dismiss the panel regardless of pin state. Used by the close button.
+ */
+function _dismissMemoryPanelForce() {
+  _memPanelPinned = false;
+  SpatialMemory.clearHighlight();
+  const panel = document.getElementById('memory-panel');
+  if (!panel || panel.style.display === 'none') return;
+  panel.classList.add('memory-panel-fade-out');
+  setTimeout(() => {
+    panel.style.display = 'none';
+    panel.classList.remove('memory-panel-fade-out');
+  }, 200);
+}
+
+/**
+ * Show the session room HUD panel when a chamber is entered.
+ * @param {object} session — { id, timestamp, facts[] }
+ */
+function _showSessionRoomPanel(session) {
+  const panel = document.getElementById('session-room-panel');
+  if (!panel) return;
+
+  const dt = session.timestamp ? new Date(session.timestamp) : new Date();
+  const tsEl = document.getElementById('session-room-timestamp');
+  if (tsEl) tsEl.textContent = isNaN(dt.getTime()) ? session.id : dt.toLocaleString();
+
+  const countEl = document.getElementById('session-room-fact-count');
+  const facts = session.facts || [];
+  if (countEl) countEl.textContent = facts.length + (facts.length === 1 ? ' fact' : ' facts') + ' in this chamber';
+
+  const listEl = document.getElementById('session-room-facts');
+  if (listEl) {
+    listEl.innerHTML = '';
+    facts.slice(0, 8).forEach(f => {
+      const item = document.createElement('div');
+      item.className = 'session-room-fact-item';
+      item.textContent = f.content || f.id || '(unknown)';
+      item.title = f.content || '';
+      listEl.appendChild(item);
+    });
+    if (facts.length > 8) {
+      const more = document.createElement('div');
+      more.className = 'session-room-fact-item';
+      more.style.color = 'rgba(200,180,255,0.4)';
+      more.textContent = '\u2026 ' + (facts.length - 8) + ' more';
+      listEl.appendChild(more);
+    }
+  }
+
+  // Close button
+  const closeBtn = document.getElementById('session-room-close');
+  if (closeBtn) closeBtn.onclick = () => _dismissSessionRoomPanel();
+
+  panel.classList.remove('session-panel-fade-out');
+  panel.style.display = 'block';
+}
+
+/**
+ * Dismiss the session room panel.
+ */
+function _dismissSessionRoomPanel() {
+  const panel = document.getElementById('session-room-panel');
+  if (!panel || panel.style.display === 'none') return;
+  panel.classList.add('session-panel-fade-out');
+  setTimeout(() => {
+    panel.style.display = 'none';
+    panel.classList.remove('session-panel-fade-out');
+  }, 200);
+}
+
+
 function gameLoop() {
   requestAnimationFrame(gameLoop);
   const delta = Math.min(clock.getDelta(), 0.1);
@@ -2581,6 +2834,9 @@ function gameLoop() {
     animateMemoryOrbs(delta);
   }
 
+  // Project Mnemosyne - Session Rooms (#1171)
+  SessionRooms.update(delta);
+
 
   const mode = NAV_MODES[navModeIdx];
   const chatActive = document.activeElement === document.getElementById('chat-input');
@@ -3104,9 +3360,52 @@ init().then(() => {
     { id: 'mem_hermes_chat', content: 'First conversation through the Hermes gateway', category: 'social', strength: 0.7, connections: [] },
     { id: 'mem_mnemosyne_start', content: 'Project Mnemosyne began — the living archive awakens', category: 'projects', strength: 0.9, connections: ['mem_nexus_birth', 'mem_spatial_schema'] },
     { id: 'mem_spatial_schema', content: 'Spatial Memory Schema defined — memories gain permanent homes', category: 'engineering', strength: 0.8, connections: ['mem_mnemosyne_start'] },
+    // MemPalace category zone demos — issue #1168
+    { id: 'mem_pref_dark_mode', content: 'User prefers dark mode and monospace fonts', category: 'user_pref', strength: 0.9, connections: [] },
+    { id: 'mem_pref_verbose_logs', content: 'User prefers verbose logging during debug sessions', category: 'user_pref', strength: 0.7, connections: [] },
+    { id: 'mem_proj_nexus_goal', content: 'The Nexus goal: local-first 3D training ground for Timmy', category: 'project', strength: 0.95, connections: ['mem_proj_mnemosyne'] },
+    { id: 'mem_proj_mnemosyne', content: 'Project Mnemosyne: holographic living archive of facts', category: 'project', strength: 0.85, connections: ['mem_proj_nexus_goal'] },
+    { id: 'mem_tool_three_js', content: 'Three.js — 3D rendering library used for the Nexus world', category: 'tool', strength: 0.8, connections: [] },
+    { id: 'mem_tool_gitea', content: 'Gitea API at forge.alexanderwhitestone.com for issue tracking', category: 'tool', strength: 0.75, connections: [] },
+    { id: 'mem_gen_websocket', content: 'WebSocket bridge (server.py) connects Timmy cognition to the browser', category: 'general', strength: 0.7, connections: [] },
+    { id: 'mem_gen_hermes', content: 'Hermes harness: telemetry and durable truth pipeline', category: 'general', strength: 0.65, connections: [] },
   ];
   demoMemories.forEach(m => SpatialMemory.placeMemory(m));
 
+  // Gravity well clustering — attract related crystals, bake positions (issue #1175)
+  SpatialMemory.runGravityLayout();
+
+  // Project Mnemosyne — seed demo session rooms (#1171)
+  // Sessions group facts by conversation/work session with a timestamp.
+  const demoSessions = [
+    {
+      id: 'session_2026_03_01',
+      timestamp: '2026-03-01T10:00:00.000Z',
+      facts: [
+        { id: 'mem_nexus_birth',     content: 'The Nexus came online — first render of the 3D world',    category: 'knowledge',    strength: 0.95 },
+        { id: 'mem_mnemosyne_start', content: 'Project Mnemosyne began — the living archive awakens',    category: 'projects',     strength: 0.9 },
+      ]
+    },
+    {
+      id: 'session_2026_03_15',
+      timestamp: '2026-03-15T14:30:00.000Z',
+      facts: [
+        { id: 'mem_first_portal',    content: 'First portal deployed — connection to external service',  category: 'engineering',  strength: 0.85 },
+        { id: 'mem_hermes_chat',     content: 'First conversation through the Hermes gateway',           category: 'social',       strength: 0.7 },
+        { id: 'mem_spatial_schema',  content: 'Spatial Memory Schema defined — memories gain homes',     category: 'engineering',  strength: 0.8 },
+      ]
+    },
+    {
+      id: 'session_2026_04_10',
+      timestamp: '2026-04-10T09:00:00.000Z',
+      facts: [
+        { id: 'mem_session_rooms',   content: 'Session rooms introduced — holographic chambers per session', category: 'projects', strength: 0.88 },
+        { id: 'mem_gravity_wells',   content: 'Gravity-well clustering bakes crystal positions on load',  category: 'engineering',  strength: 0.75 },
+      ]
+    }
+  ];
+  SessionRooms.updateSessions(demoSessions);
+
   fetchGiteaData();
   setInterval(fetchGiteaData, 30000);
   runWeeklyAudit();

fleet/hermes-trismegistus/README.md

@@ -0,0 +1,72 @@
+# Hermes Trismegistus — Wizard Proposal
+
+> **Status:** 🟡 DEFERRED
+> **Issue:** #1146
+> **Created:** 2026-04-08
+> **Author:** Alexander (KT Notes)
+> **Mimo Worker:** mimo-code-1146-1775851759
+
+---
+
+## Identity
+
+| Field | Value |
+|-------|-------|
+| **Name** | Hermes Trismegistus |
+| **Nature** | Claude-native wizard. She knows she runs on Claude. She's "the daughter of Claude" and leans into that heritage. |
+| **Purpose** | Dedicated reasoning and architecture wizard. Only handles tasks where Claude's reasoning capability genuinely adds value — planning, novel problem-solving, complex architecture decisions. |
+| **Not** | A replacement for Timmy. Not competing for identity. Not doing monkey work. |
+
+## Design Constraints
+
+- **Free tier only from day one.** Alexander is not paying Anthropic beyond current subscription.
+- **Degrades gracefully.** Full capability when free tier is generous, reduced scope when constrained.
+- **Not locked to Claude.** If better free-tier providers emerge, she can route to them.
+- **Multi-provider capable.** Welcome to become multifaceted if team finds better options.
+
+## Hardware
+
+- One of Alexander's shed laptops — minimum 4GB RAM, Ubuntu
+- Dedicated machine, not shared with Timmy's Mac
+- Runs in the Hermes harness
+- Needs power at house first
+
+## Constitutional Foundation
+
+- The KT conversation and documents serve as her founding constitution
+- Team (especially Timmy) has final say on whether she gets built
+- Must justify her existence through useful work, same as every wizard
+
+## Trigger to Unblock
+
+All of the following must be true before implementation begins:
+
+- [ ] Deadman switch wired and proven
+- [ ] Config stable across fleet
+- [ ] Fleet proven reliable for 1+ week
+- [ ] Alexander provides a state-of-the-system KT to Claude for instantiation
+
+## Acceptance Criteria
+
+- [ ] Dedicated KT document written for Hermes instantiation
+- [ ] Hardware provisioned (shed laptop with power)
+- [ ] Hermes harness configured for Claude free tier
+- [ ] Lazerus registry entry with health endpoints
+- [ ] Fleet routing entry with role and routing verdict
+- [ ] SOUL.md inscription drafted and reviewed by Timmy
+- [ ] Smoke test: Hermes responds to a basic reasoning task
+- [ ] Integration test: Hermes participates in a multi-wizard task alongside Timmy
+
+## Proposed Lane
+
+**Primary role:** Architecture reasoning
+**Routing verdict:** ROUTE TO: complex architectural decisions, novel problem-solving, planning tasks that benefit from Claude's reasoning depth. Do NOT route to: code generation (use Timmy/Carnice), issue triage (use Fenrir), or operational tasks (use Bezalel).
+
+## Dependencies
+
+| Dependency | Status | Notes |
+|------------|--------|-------|
+| Deadman switch | 🔴 Not done | Must be proven before unblocking |
+| Fleet stability | 🟡 In progress | 1+ week uptime needed |
+| Shed laptop power | 🔴 Not done | Alexander needs to wire power |
+| KT document | 🔴 Not drafted | Alexander provides to Claude at unblock time |

fleet/hermes-trismegistus/lane.md

@@ -0,0 +1,43 @@
+# Hermes Trismegistus — Lane Definition
+
+> **Status:** DEFERRED — do not instantiate until unblock conditions met
+> **See:** fleet/hermes-trismegistus/README.md for full proposal
+
+---
+
+## Role
+
+Dedicated reasoning and architecture wizard. Claude-native.
+
+## Routing
+
+Route to Hermes Trismegistus when:
+- Task requires deep architectural reasoning
+- Novel problem-solving that benefits from Claude's reasoning depth
+- Planning and design decisions for the fleet
+- Complex multi-step analysis that goes beyond code generation
+
+Do NOT route to Hermes for:
+- Code generation (use Timmy, Carnice, or Kimi)
+- Issue triage (use Fenrir)
+- Operational/DevOps tasks (use Bezalel)
+- Anything that can be done with a cheaper model
+
+## Provider
+
+- **Primary:** anthropic/claude (free tier)
+- **Fallback:** openrouter/free (Claude-class models)
+- **Degraded:** ollama/gemma4:12b (when free tier exhausted)
+
+## Hardware
+
+- Shed laptop, Ubuntu, minimum 4GB RAM
+- Dedicated machine, not shared
+
+## Unblock Checklist
+
+- [ ] Deadman switch operational
+- [ ] Fleet config stable for 1+ week
+- [ ] Shed laptop powered and networked
+- [ ] KT document drafted by Alexander
+- [ ] Timmy approves instantiation

index.html

@@ -207,6 +207,50 @@
     </div>
   </div>
 
+
+  <!-- Memory Crystal Inspection Panel (Mnemosyne) -->
+  <div id="memory-panel" class="memory-panel" style="display:none;">
+    <div class="memory-panel-content">
+      <div class="memory-panel-header">
+        <span class="memory-category-badge" id="memory-panel-category-badge">MEM</span>
+        <div class="memory-panel-region-dot" id="memory-panel-region-dot"></div>
+        <div class="memory-panel-region" id="memory-panel-region">MEMORY</div>
+        <button id="memory-panel-pin" class="memory-panel-pin" title="Pin panel">&#x1F4CC;</button>
+        <button id="memory-panel-close" class="memory-panel-close" onclick="_dismissMemoryPanelForce()">\u2715</button>
+      </div>
+      <div class="memory-entity-name" id="memory-panel-entity-name">\u2014</div>
+      <div class="memory-panel-body" id="memory-panel-content">(empty)</div>
+      <div class="memory-trust-row">
+        <span class="memory-meta-label">Trust</span>
+        <div class="memory-trust-bar">
+          <div class="memory-trust-fill" id="memory-panel-trust-fill"></div>
+        </div>
+        <span class="memory-trust-value" id="memory-panel-trust-value">—</span>
+      </div>
+      <div class="memory-panel-meta">
+        <div class="memory-meta-row"><span class="memory-meta-label">ID</span><span id="memory-panel-id">\u2014</span></div>
+        <div class="memory-meta-row"><span class="memory-meta-label">Source</span><span id="memory-panel-source">\u2014</span></div>
+        <div class="memory-meta-row"><span class="memory-meta-label">Time</span><span id="memory-panel-time">\u2014</span></div>
+        <div class="memory-meta-row memory-meta-row--related"><span class="memory-meta-label">Related</span><span id="memory-panel-connections">\u2014</span></div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Session Room HUD Panel (Mnemosyne #1171) -->
+  <div id="session-room-panel" class="session-room-panel" style="display:none;">
+    <div class="session-room-panel-content">
+      <div class="session-room-header">
+        <span class="session-room-icon">&#x25A1;</span>
+        <div class="session-room-title">SESSION CHAMBER</div>
+        <button class="session-room-close" id="session-room-close" title="Close">&#x2715;</button>
+      </div>
+      <div class="session-room-timestamp" id="session-room-timestamp">&mdash;</div>
+      <div class="session-room-fact-count" id="session-room-fact-count">0 facts</div>
+      <div class="session-room-facts" id="session-room-facts"></div>
+      <div class="session-room-hint">Flying into chamber&hellip;</div>
+    </div>
+  </div>
+
   <!-- Portal Atlas Overlay -->
   <div id="atlas-overlay" class="atlas-overlay" style="display:none;">
     <div class="atlas-content">

nexus/components/session-rooms.js

@@ -0,0 +1,413 @@
+// ═══════════════════════════════════════════════════════
+//  PROJECT MNEMOSYNE — SESSION ROOMS (Issue #1171)
+// ═══════════════════════════════════════════════════════
+//
+// Groups memories by session into holographic chambers.
+// Each session becomes a wireframe cube floating in space.
+// Rooms are arranged chronologically along a spiral.
+// Click a room to fly inside; distant rooms LOD to a point.
+//
+// Usage from app.js:
+//   SessionRooms.init(scene, camera, controls);
+//   SessionRooms.updateSessions(sessions);   // [{id, timestamp, facts[]}]
+//   SessionRooms.update(delta);              // call each frame
+//   SessionRooms.getClickableMeshes();       // for raycasting
+//   SessionRooms.handleRoomClick(mesh);      // trigger fly-in
+// ═══════════════════════════════════════════════════════
+
+const SessionRooms = (() => {
+
+  // ─── CONSTANTS ───────────────────────────────────────
+  const MAX_ROOMS        = 20;
+  const ROOM_SIZE        = 9;          // wireframe cube edge length
+  const ROOM_HALF        = ROOM_SIZE / 2;
+  const LOD_THRESHOLD    = 55;         // distance: full → point
+  const LOD_HYSTERESIS   = 5;          // buffer to avoid flicker
+  const SPIRAL_BASE_R    = 20;         // spiral inner radius
+  const SPIRAL_R_STEP    = 5;          // radius growth per room
+  const SPIRAL_ANGLE_INC = 2.399;      // golden angle (radians)
+  const SPIRAL_Y_STEP    = 1.5;        // vertical rise per room
+  const FLY_DURATION     = 1.5;        // seconds for fly-in tween
+  const FLY_TARGET_DEPTH = ROOM_HALF - 1.5; // how deep inside to stop
+
+  const ROOM_COLOR       = 0x7b5cff;   // violet — mnemosyne accent
+  const POINT_COLOR      = 0x9b7cff;
+  const LABEL_COLOR      = '#c8b4ff';
+  const STORAGE_KEY      = 'mnemosyne_sessions_v1';
+
+  // ─── STATE ────────────────────────────────────────────
+  let _scene    = null;
+  let _camera   = null;
+  let _controls = null;
+
+  let _rooms        = [];   // array of room objects
+  let _sessionIndex = {};   // id → room object
+
+  // Fly-in tween state
+  let _flyActive   = false;
+  let _flyElapsed  = 0;
+  let _flyFrom     = null;
+  let _flyTo       = null;
+  let _flyLookFrom = null;
+  let _flyLookTo   = null;
+  let _flyActiveRoom = null;
+
+  // ─── SPIRAL POSITION ──────────────────────────────────
+  function _spiralPos(index) {
+    const angle = index * SPIRAL_ANGLE_INC;
+    const r     = SPIRAL_BASE_R + index * SPIRAL_R_STEP;
+    const y     = index * SPIRAL_Y_STEP;
+    return new THREE.Vector3(
+      Math.cos(angle) * r,
+      y,
+      Math.sin(angle) * r
+    );
+  }
+
+  // ─── CREATE ROOM ──────────────────────────────────────
+  function _createRoom(session, index) {
+    const pos = _spiralPos(index);
+    const group = new THREE.Group();
+    group.position.copy(pos);
+
+    // Wireframe cube
+    const boxGeo   = new THREE.BoxGeometry(ROOM_SIZE, ROOM_SIZE, ROOM_SIZE);
+    const edgesGeo = new THREE.EdgesGeometry(boxGeo);
+    const edgesMat = new THREE.LineBasicMaterial({
+      color: ROOM_COLOR,
+      transparent: true,
+      opacity: 0.55
+    });
+    const wireframe = new THREE.LineSegments(edgesGeo, edgesMat);
+    wireframe.userData = { type: 'session_room_wireframe', sessionId: session.id };
+    group.add(wireframe);
+
+    // Collision mesh (invisible, for raycasting)
+    const hitGeo = new THREE.BoxGeometry(ROOM_SIZE, ROOM_SIZE, ROOM_SIZE);
+    const hitMat = new THREE.MeshBasicMaterial({
+      visible: false,
+      transparent: true,
+      opacity: 0,
+      side: THREE.FrontSide
+    });
+    const hitMesh = new THREE.Mesh(hitGeo, hitMat);
+    hitMesh.userData = { type: 'session_room', sessionId: session.id, roomIndex: index };
+    group.add(hitMesh);
+
+    // LOD point (small sphere shown at distance)
+    const pointGeo = new THREE.SphereGeometry(0.5, 6, 4);
+    const pointMat = new THREE.MeshBasicMaterial({
+      color: POINT_COLOR,
+      transparent: true,
+      opacity: 0.7
+    });
+    const pointMesh = new THREE.Mesh(pointGeo, pointMat);
+    pointMesh.userData = { type: 'session_room_point', sessionId: session.id };
+    pointMesh.visible = false;  // starts hidden; shown only at LOD distance
+    group.add(pointMesh);
+
+    // Timestamp billboard sprite
+    const sprite = _makeTimestampSprite(session.timestamp, session.facts.length);
+    sprite.position.set(0, ROOM_HALF + 1.2, 0);
+    group.add(sprite);
+
+    // Inner ambient glow
+    const glow = new THREE.PointLight(ROOM_COLOR, 0.4, ROOM_SIZE * 1.2);
+    group.add(glow);
+
+    _scene.add(group);
+
+    const room = {
+      session,
+      group,
+      wireframe,
+      hitMesh,
+      pointMesh,
+      sprite,
+      glow,
+      pos: pos.clone(),
+      index,
+      lodActive: false,
+      pulsePhase: Math.random() * Math.PI * 2
+    };
+
+    _rooms.push(room);
+    _sessionIndex[session.id] = room;
+
+    console.info('[SessionRooms] Created room for session', session.id, 'at index', index);
+    return room;
+  }
+
+  // ─── TIMESTAMP SPRITE ────────────────────────────────
+  function _makeTimestampSprite(isoTimestamp, factCount) {
+    const canvas  = document.createElement('canvas');
+    canvas.width  = 320;
+    canvas.height = 72;
+    const ctx = canvas.getContext('2d');
+
+    // Background pill
+    ctx.clearRect(0, 0, 320, 72);
+    ctx.fillStyle = 'rgba(20, 10, 40, 0.82)';
+    _roundRect(ctx, 4, 4, 312, 64, 14);
+    ctx.fill();
+
+    // Border
+    ctx.strokeStyle = 'rgba(123, 92, 255, 0.6)';
+    ctx.lineWidth = 1.5;
+    _roundRect(ctx, 4, 4, 312, 64, 14);
+    ctx.stroke();
+
+    // Timestamp text
+    const dt = isoTimestamp ? new Date(isoTimestamp) : new Date();
+    const label = _formatDate(dt);
+    ctx.fillStyle = LABEL_COLOR;
+    ctx.font = 'bold 15px monospace';
+    ctx.textAlign = 'center';
+    ctx.fillText(label, 160, 30);
+
+    // Fact count
+    ctx.fillStyle = 'rgba(200, 180, 255, 0.65)';
+    ctx.font = '12px monospace';
+    ctx.fillText(factCount + (factCount === 1 ? ' fact' : ' facts'), 160, 52);
+
+    const tex    = new THREE.CanvasTexture(canvas);
+    const mat    = new THREE.SpriteMaterial({ map: tex, transparent: true, opacity: 0.88 });
+    const sprite = new THREE.Sprite(mat);
+    sprite.scale.set(5, 1.1, 1);
+    sprite.userData = { type: 'session_room_label' };
+    return sprite;
+  }
+
+  // ─── HELPERS ──────────────────────────────────────────
+  function _roundRect(ctx, x, y, w, h, r) {
+    ctx.beginPath();
+    ctx.moveTo(x + r, y);
+    ctx.lineTo(x + w - r, y);
+    ctx.quadraticCurveTo(x + w, y, x + w, y + r);
+    ctx.lineTo(x + w, y + h - r);
+    ctx.quadraticCurveTo(x + w, y + h, x + w - r, y + h);
+    ctx.lineTo(x + r, y + h);
+    ctx.quadraticCurveTo(x, y + h, x, y + h - r);
+    ctx.lineTo(x, y + r);
+    ctx.quadraticCurveTo(x, y, x + r, y);
+    ctx.closePath();
+  }
+
+  function _formatDate(dt) {
+    if (isNaN(dt.getTime())) return 'Unknown session';
+    const pad = n => String(n).padStart(2, '0');
+    return `${dt.getFullYear()}-${pad(dt.getMonth() + 1)}-${pad(dt.getDate())}  ${pad(dt.getHours())}:${pad(dt.getMinutes())}`;
+  }
+
+  // ─── DISPOSE ROOM ────────────────────────────────────
+  function _disposeRoom(room) {
+    room.wireframe.geometry.dispose();
+    room.wireframe.material.dispose();
+    room.hitMesh.geometry.dispose();
+    room.hitMesh.material.dispose();
+    room.pointMesh.geometry.dispose();
+    room.pointMesh.material.dispose();
+    if (room.sprite.material.map) room.sprite.material.map.dispose();
+    room.sprite.material.dispose();
+    if (room.group.parent) room.group.parent.remove(room.group);
+    delete _sessionIndex[room.session.id];
+  }
+
+  // ─── PUBLIC: UPDATE SESSIONS ─────────────────────────
+  // sessions: [{id, timestamp, facts:[{id,content,category,strength,...}]}]
+  // Sorted chronologically oldest→newest; max MAX_ROOMS shown.
+  function updateSessions(sessions) {
+    if (!_scene) return;
+
+    const sorted = [...sessions]
+      .sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp))
+      .slice(-MAX_ROOMS);  // keep most recent MAX_ROOMS
+
+    // Remove rooms no longer present
+    const incoming = new Set(sorted.map(s => s.id));
+    for (let i = _rooms.length - 1; i >= 0; i--) {
+      const room = _rooms[i];
+      if (!incoming.has(room.session.id)) {
+        _disposeRoom(room);
+        _rooms.splice(i, 1);
+      }
+    }
+
+    // Add / update
+    sorted.forEach((session, idx) => {
+      if (_sessionIndex[session.id]) {
+        // Update position if index changed
+        const room = _sessionIndex[session.id];
+        if (room.index !== idx) {
+          room.index = idx;
+          const newPos = _spiralPos(idx);
+          room.group.position.copy(newPos);
+          room.pos.copy(newPos);
+        }
+      } else {
+        _createRoom(session, idx);
+      }
+    });
+
+    saveToStorage(sorted);
+    console.info('[SessionRooms] Updated:', _rooms.length, 'session rooms');
+  }
+
+  // ─── PUBLIC: INIT ─────────────────────────────────────
+  function init(scene, camera, controls) {
+    _scene    = scene;
+    _camera   = camera;
+    _controls = controls;
+    console.info('[SessionRooms] Initialized');
+
+    // Restore persisted sessions
+    const saved = loadFromStorage();
+    if (saved && saved.length > 0) {
+      updateSessions(saved);
+    }
+  }
+
+  // ─── PUBLIC: UPDATE (per-frame) ───────────────────────
+  function update(delta) {
+    if (!_scene || !_camera) return;
+
+    const camPos = _camera.position;
+
+    _rooms.forEach(room => {
+      const dist = camPos.distanceTo(room.pos);
+
+      // LOD toggle
+      const threshold = room.lodActive
+        ? LOD_THRESHOLD + LOD_HYSTERESIS   // must come closer to exit LOD
+        : LOD_THRESHOLD;
+
+      if (dist > threshold && !room.lodActive) {
+        room.lodActive = true;
+        room.wireframe.visible = false;
+        room.sprite.visible    = false;
+        room.pointMesh.visible = true;
+      } else if (dist <= threshold && room.lodActive) {
+        room.lodActive = false;
+        room.wireframe.visible = true;
+        room.sprite.visible    = true;
+        room.pointMesh.visible = false;
+      }
+
+      // Pulse wireframe opacity
+      room.pulsePhase += delta * 0.6;
+      if (!room.lodActive) {
+        room.wireframe.material.opacity = 0.3 + Math.sin(room.pulsePhase) * 0.2;
+        room.glow.intensity = 0.3 + Math.sin(room.pulsePhase * 1.4) * 0.15;
+      }
+
+      // Slowly rotate each room
+      room.group.rotation.y += delta * 0.04;
+    });
+
+    // Fly-in tween
+    if (_flyActive) {
+      _flyElapsed += delta;
+      const t = Math.min(_flyElapsed / FLY_DURATION, 1);
+      const ease = _easeInOut(t);
+
+      _camera.position.lerpVectors(_flyFrom, _flyTo, ease);
+
+      // Interpolate lookAt
+      const lookNow = new THREE.Vector3().lerpVectors(_flyLookFrom, _flyLookTo, ease);
+      _camera.lookAt(lookNow);
+      if (_controls && _controls.target) _controls.target.copy(lookNow);
+
+      if (t >= 1) {
+        _flyActive = false;
+        if (_controls && typeof _controls.update === 'function') _controls.update();
+        console.info('[SessionRooms] Fly-in complete for session', _flyActiveRoom && _flyActiveRoom.session.id);
+        _flyActiveRoom = null;
+      }
+    }
+  }
+
+  // ─── EASING ───────────────────────────────────────────
+  function _easeInOut(t) {
+    return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+  }
+
+  // ─── PUBLIC: GET CLICKABLE MESHES ─────────────────────
+  function getClickableMeshes() {
+    return _rooms.map(r => r.hitMesh);
+  }
+
+  // ─── PUBLIC: HANDLE ROOM CLICK ────────────────────────
+  function handleRoomClick(mesh) {
+    const { sessionId } = mesh.userData;
+    const room = _sessionIndex[sessionId];
+    if (!room || !_camera) return null;
+
+    // Fly into the room from the front face
+    _flyActive   = true;
+    _flyElapsed  = 0;
+    _flyActiveRoom = room;
+
+    _flyFrom = _camera.position.clone();
+
+    // Target: step inside the room toward its center
+    const dir = room.pos.clone().sub(_camera.position).normalize();
+    _flyTo = room.pos.clone().add(dir.multiplyScalar(FLY_TARGET_DEPTH));
+
+    _flyLookFrom = _controls && _controls.target
+      ? _controls.target.clone()
+      : _camera.position.clone().add(_camera.getWorldDirection(new THREE.Vector3()));
+    _flyLookTo = room.pos.clone();
+
+    console.info('[SessionRooms] Flying into session room:', sessionId);
+    return room.session;
+  }
+
+  // ─── PERSISTENCE ──────────────────────────────────────
+  function saveToStorage(sessions) {
+    if (typeof localStorage === 'undefined') return;
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify({ v: 1, sessions }));
+    } catch (e) {
+      console.warn('[SessionRooms] Failed to save to localStorage:', e);
+    }
+  }
+
+  function loadFromStorage() {
+    if (typeof localStorage === 'undefined') return null;
+    try {
+      const raw = localStorage.getItem(STORAGE_KEY);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      if (!parsed || parsed.v !== 1 || !Array.isArray(parsed.sessions)) return null;
+      console.info('[SessionRooms] Restored', parsed.sessions.length, 'sessions from localStorage');
+      return parsed.sessions;
+    } catch (e) {
+      console.warn('[SessionRooms] Failed to load from localStorage:', e);
+      return null;
+    }
+  }
+
+  function clearStorage() {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.removeItem(STORAGE_KEY);
+      console.info('[SessionRooms] Cleared localStorage');
+    }
+  }
+
+  // ─── PUBLIC API ───────────────────────────────────────
+  return {
+    init,
+    updateSessions,
+    update,
+    getClickableMeshes,
+    handleRoomClick,
+    clearStorage,
+    // For external inspection
+    getRooms: () => _rooms,
+    getSession: (id) => _sessionIndex[id] || null,
+    isFlyActive: () => _flyActive
+  };
+
+})();
+
+export { SessionRooms };

nexus/components/spatial-memory.js

@@ -8,12 +8,20 @@
 // holographic archive.
 //
 // World layout (hex cylinder, radius 25):
-//   North (z-)  → Documents & Knowledge
-//   South (z+)  → Projects & Tasks
-//   East  (x+)  → Code & Engineering
-//   West  (x-)  → Conversations & Social
-//   Center      → Active Working Memory
-//   Below (y-)  → Archive (cold storage)
+//
+//   Inner ring — original Mnemosyne taxonomy (radius 15):
+//     North (z-)  → Documents & Knowledge
+//     South (z+)  → Projects & Tasks
+//     East  (x+)  → Code & Engineering
+//     West  (x-)  → Conversations & Social
+//     Center      → Active Working Memory
+//     Below (y-)  → Archive (cold storage)
+//
+//   Outer ring — MemPalace category zones (radius 20, issue #1168):
+//     North (z-)  → User Preferences   [golden]
+//     East  (x+)  → Project facts      [blue]
+//     South (z+)  → Tool knowledge     [green]
+//     West  (x-)  → General facts      [gray]
 //
 // Usage from app.js:
 //   SpatialMemory.init(scene);
@@ -73,6 +81,44 @@ const SpatialMemory = (() => {
       color: 0x334455,
       glyph: '\uD83D\uDDC4',
       description: 'Cold storage — rarely accessed, aged-out memories'
+    },
+
+    // ── MemPalace category zones — outer ring, issue #1168 ────────────
+    user_pref: {
+      label: 'User Preferences',
+      center: [0, 0, -20],
+      radius: 10,
+      color: 0xffd700,
+      glyph: '\u2605',
+      description: 'Personal preferences, habits, user-specific settings',
+      labelY: 5
+    },
+    project: {
+      label: 'Project Facts',
+      center: [20, 0, 0],
+      radius: 10,
+      color: 0x4488ff,
+      glyph: '\uD83D\uDCC1',
+      description: 'Project-specific knowledge, goals, context',
+      labelY: 5
+    },
+    tool: {
+      label: 'Tool Knowledge',
+      center: [0, 0, 20],
+      radius: 10,
+      color: 0x44cc66,
+      glyph: '\uD83D\uDD27',
+      description: 'Tools, commands, APIs, and how to use them',
+      labelY: 5
+    },
+    general: {
+      label: 'General Facts',
+      center: [-20, 0, 0],
+      radius: 10,
+      color: 0x8899aa,
+      glyph: '\uD83D\uDCDD',
+      description: 'Miscellaneous facts not fitting other categories',
+      labelY: 5
     }
   };
 
@@ -99,6 +145,7 @@ const SpatialMemory = (() => {
     const cx = region.center[0];
     const cy = region.center[1] + 0.06;
     const cz = region.center[2];
+    const labelY = region.labelY || 3;
 
     const ringGeo = new THREE.RingGeometry(region.radius - 0.5, region.radius, 6);
     const ringMat = new THREE.MeshBasicMaterial({
@@ -126,6 +173,22 @@ const SpatialMemory = (() => {
     _scene.add(ring);
     _scene.add(disc);
 
+    // Ground glow — brighter disc for MemPalace zones (labelY > 3 signals outer ring)
+    let glowDisc = null;
+    if (labelY > 3) {
+      const glowGeo = new THREE.CircleGeometry(region.radius, 32);
+      const glowMat = new THREE.MeshBasicMaterial({
+        color: region.color,
+        transparent: true,
+        opacity: 0.06,
+        side: THREE.DoubleSide
+      });
+      glowDisc = new THREE.Mesh(glowGeo, glowMat);
+      glowDisc.rotation.x = -Math.PI / 2;
+      glowDisc.position.set(cx, cy - 0.02, cz);
+      _scene.add(glowDisc);
+    }
+
     // Floating label
     const canvas = document.createElement('canvas');
     canvas.width = 256;
@@ -139,11 +202,11 @@ const SpatialMemory = (() => {
     const texture = new THREE.CanvasTexture(canvas);
     const spriteMat = new THREE.SpriteMaterial({ map: texture, transparent: true, opacity: 0.6 });
     const sprite = new THREE.Sprite(spriteMat);
-    sprite.position.set(cx, 3, cz);
+    sprite.position.set(cx, labelY, cz);
     sprite.scale.set(4, 1, 1);
     _scene.add(sprite);
 
-    return { ring, disc, sprite };
+    return { ring, disc, glowDisc, sprite };
   }
 
   // ─── PLACE A MEMORY ──────────────────────────────────
@@ -283,6 +346,9 @@ const SpatialMemory = (() => {
       if (marker.ring && marker.ring.material) {
         marker.ring.material.opacity = 0.1 + Math.sin(now * 0.001) * 0.05;
       }
+      if (marker.glowDisc && marker.glowDisc.material) {
+        marker.glowDisc.material.opacity = 0.04 + Math.sin(now * 0.0008) * 0.02;
+      }
     });
   }
 
@@ -456,6 +522,81 @@ const SpatialMemory = (() => {
     return count;
   }
 
+  // ─── GRAVITY WELL CLUSTERING ──────────────────────────
+  // Force-directed layout: same-category crystals attract, unrelated repel.
+  // Run on load (bake positions, not per-frame). Spec from issue #1175.
+  const GRAVITY_ITERATIONS = 20;
+  const ATTRACT_FACTOR = 0.10; // 10% closer to same-category centroid per iteration
+  const REPEL_FACTOR   = 0.05; // 5% away from nearest unrelated crystal
+
+  function runGravityLayout() {
+    const objs = Object.values(_memoryObjects);
+    if (objs.length < 2) {
+      console.info('[Mnemosyne] Gravity layout: fewer than 2 crystals, skipping');
+      return;
+    }
+    console.info('[Mnemosyne] Gravity layout starting —', objs.length, 'crystals,', GRAVITY_ITERATIONS, 'iterations');
+
+    for (let iter = 0; iter < GRAVITY_ITERATIONS; iter++) {
+      // Accumulate displacements before applying (avoids order-of-iteration bias)
+      const dx = new Float32Array(objs.length);
+      const dy = new Float32Array(objs.length);
+      const dz = new Float32Array(objs.length);
+
+      objs.forEach((obj, i) => {
+        const pos = obj.mesh.position;
+        const cat  = obj.region;
+
+        // ── Attraction toward same-category centroid ──────────────
+        let sx = 0, sy = 0, sz = 0, sameCount = 0;
+        objs.forEach(o => {
+          if (o === obj || o.region !== cat) return;
+          sx += o.mesh.position.x;
+          sy += o.mesh.position.y;
+          sz += o.mesh.position.z;
+          sameCount++;
+        });
+        if (sameCount > 0) {
+          dx[i] += ((sx / sameCount) - pos.x) * ATTRACT_FACTOR;
+          dy[i] += ((sy / sameCount) - pos.y) * ATTRACT_FACTOR;
+          dz[i] += ((sz / sameCount) - pos.z) * ATTRACT_FACTOR;
+        }
+
+        // ── Repulsion from nearest unrelated crystal ───────────────
+        let nearestDist = Infinity;
+        let rnx = 0, rny = 0, rnz = 0;
+        objs.forEach(o => {
+          if (o === obj || o.region === cat) return;
+          const ex = pos.x - o.mesh.position.x;
+          const ey = pos.y - o.mesh.position.y;
+          const ez = pos.z - o.mesh.position.z;
+          const d  = Math.sqrt(ex * ex + ey * ey + ez * ez);
+          if (d < nearestDist) {
+            nearestDist = d;
+            rnx = ex; rny = ey; rnz = ez;
+          }
+        });
+        if (nearestDist > 0.001 && nearestDist < Infinity) {
+          const len = Math.sqrt(rnx * rnx + rny * rny + rnz * rnz);
+          dx[i] += (rnx / len) * nearestDist * REPEL_FACTOR;
+          dy[i] += (rny / len) * nearestDist * REPEL_FACTOR;
+          dz[i] += (rnz / len) * nearestDist * REPEL_FACTOR;
+        }
+      });
+
+      // Apply displacements
+      objs.forEach((obj, i) => {
+        obj.mesh.position.x += dx[i];
+        obj.mesh.position.y += dy[i];
+        obj.mesh.position.z += dz[i];
+      });
+    }
+
+    // Bake final positions to localStorage
+    saveToStorage();
+    console.info('[Mnemosyne] Gravity layout complete — positions baked to localStorage');
+  }
+
   // ─── SPATIAL SEARCH ──────────────────────────────────
   function searchNearby(position, maxResults, maxDist) {
     maxResults = maxResults || 10;
@@ -471,11 +612,53 @@ const SpatialMemory = (() => {
     return results.slice(0, maxResults);
   }
 
+
+  // ─── CRYSTAL MESH COLLECTION (for raycasting) ────────
+  function getCrystalMeshes() {
+    return Object.values(_memoryObjects).map(o => o.mesh);
+  }
+
+  // ─── MEMORY DATA FROM MESH ───────────────────────────
+  function getMemoryFromMesh(mesh) {
+    const entry = Object.values(_memoryObjects).find(o => o.mesh === mesh);
+    return entry ? { data: entry.data, region: entry.region } : null;
+  }
+
+  // ─── HIGHLIGHT / SELECT ──────────────────────────────
+  let _selectedId = null;
+  let _selectedOriginalEmissive = null;
+
+  function highlightMemory(memId) {
+    clearHighlight();
+    const obj = _memoryObjects[memId];
+    if (!obj) return;
+    _selectedId = memId;
+    _selectedOriginalEmissive = obj.mesh.material.emissiveIntensity;
+    obj.mesh.material.emissiveIntensity = 4.0;
+    obj.mesh.userData.selected = true;
+  }
+
+  function clearHighlight() {
+    if (_selectedId && _memoryObjects[_selectedId]) {
+      const obj = _memoryObjects[_selectedId];
+      obj.mesh.material.emissiveIntensity = _selectedOriginalEmissive || (obj.data.strength || 0.7) * 2.5;
+      obj.mesh.userData.selected = false;
+    }
+    _selectedId = null;
+    _selectedOriginalEmissive = null;
+  }
+
+  function getSelectedId() {
+    return _selectedId;
+  }
+
   return {
     init, placeMemory, removeMemory, update,
     getMemoryAtPosition, getRegionAtPosition, getMemoriesInRegion, getAllMemories,
+    getCrystalMeshes, getMemoryFromMesh, highlightMemory, clearHighlight, getSelectedId,
     exportIndex, importIndex, searchNearby, REGIONS,
-    saveToStorage, loadFromStorage, clearStorage
+    saveToStorage, loadFromStorage, clearStorage,
+    runGravityLayout
   };
 })();
 

style.css

@@ -1223,3 +1223,360 @@ canvas#nexus-canvas {
 .l402-msg { color: #fff; }
 
 .pse-status { color: #4af0c0; font-weight: 600; }
+
+
+/* ═══════════════════════════════════════════
+   MNEMOSYNE — MEMORY CRYSTAL INSPECTION PANEL
+   ═══════════════════════════════════════════ */
+
+.memory-panel {
+  position: fixed;
+  top: 50%;
+  right: 24px;
+  transform: translateY(-50%);
+  z-index: 120;
+  animation: memoryPanelIn 0.22s ease-out forwards;
+}
+
+.memory-panel-fade-out {
+  animation: memoryPanelOut 0.18s ease-in forwards !important;
+}
+
+@keyframes memoryPanelIn {
+  from { opacity: 0; transform: translateY(-50%) translateX(16px); }
+  to   { opacity: 1; transform: translateY(-50%) translateX(0); }
+}
+
+@keyframes memoryPanelOut {
+  from { opacity: 1; }
+  to   { opacity: 0; transform: translateY(-50%) translateX(12px); }
+}
+
+.memory-panel-content {
+  width: 340px;
+  background: rgba(8, 8, 24, 0.92);
+  backdrop-filter: blur(12px);
+  border: 1px solid rgba(74, 240, 192, 0.25);
+  border-radius: 12px;
+  padding: 16px;
+  box-shadow: 0 0 30px rgba(74, 240, 192, 0.08), 0 8px 32px rgba(0, 0, 0, 0.4);
+}
+
+.memory-panel-header {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-bottom: 10px;
+  padding-bottom: 10px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.memory-panel-region-dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.memory-panel-region {
+  font-family: var(--font-display, monospace);
+  font-size: 11px;
+  letter-spacing: 0.15em;
+  color: var(--color-primary, #4af0c0);
+  text-transform: uppercase;
+  flex: 1;
+}
+
+.memory-panel-close {
+  background: none;
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  color: var(--color-text-muted, #888);
+  font-size: 14px;
+  cursor: pointer;
+  width: 24px;
+  height: 24px;
+  border-radius: 6px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: all 0.15s;
+}
+
+.memory-panel-close:hover {
+  background: rgba(255, 255, 255, 0.05);
+  color: #fff;
+}
+
+.memory-panel-body {
+  font-size: 14px;
+  line-height: 1.6;
+  color: var(--color-text, #ccc);
+  margin-bottom: 14px;
+  max-height: 120px;
+  overflow-y: auto;
+  word-break: break-word;
+}
+
+.memory-panel-meta {
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+  font-size: 11px;
+}
+
+.memory-meta-row {
+  display: flex;
+  gap: 8px;
+  align-items: baseline;
+}
+
+.memory-meta-label {
+  color: var(--color-text-muted, #666);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  min-width: 50px;
+  flex-shrink: 0;
+}
+
+.memory-meta-row span:last-child {
+  color: var(--color-text, #aaa);
+  word-break: break-all;
+}
+
+.memory-conn-tag {
+  display: inline-block;
+  background: rgba(74, 240, 192, 0.1);
+  border: 1px solid rgba(74, 240, 192, 0.2);
+  border-radius: 4px;
+  padding: 1px 6px;
+  font-size: 10px;
+  font-family: var(--font-mono, monospace);
+  color: var(--color-primary, #4af0c0);
+  margin: 1px 2px;
+}
+
+.memory-conn-link {
+  cursor: pointer;
+  transition: background 0.15s, border-color 0.15s;
+}
+
+.memory-conn-link:hover {
+  background: rgba(74, 240, 192, 0.22);
+  border-color: rgba(74, 240, 192, 0.5);
+  color: #fff;
+}
+
+/* Entity name — large heading inside panel */
+.memory-entity-name {
+  font-family: var(--font-display, monospace);
+  font-size: 17px;
+  font-weight: 700;
+  color: #fff;
+  letter-spacing: 0.04em;
+  margin-bottom: 8px;
+  text-transform: capitalize;
+  word-break: break-word;
+}
+
+/* Category badge */
+.memory-category-badge {
+  font-family: var(--font-display, monospace);
+  font-size: 9px;
+  letter-spacing: 0.12em;
+  font-weight: 700;
+  padding: 2px 6px;
+  border-radius: 4px;
+  border: 1px solid rgba(74, 240, 192, 0.3);
+  background: rgba(74, 240, 192, 0.12);
+  color: var(--color-primary, #4af0c0);
+  flex-shrink: 0;
+}
+
+/* Trust score bar */
+.memory-trust-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 12px;
+  font-size: 11px;
+}
+
+.memory-trust-bar {
+  flex: 1;
+  height: 5px;
+  background: rgba(255, 255, 255, 0.08);
+  border-radius: 3px;
+  overflow: hidden;
+}
+
+.memory-trust-fill {
+  height: 100%;
+  border-radius: 3px;
+  background: var(--color-primary, #4af0c0);
+  transition: width 0.35s ease;
+}
+
+.memory-trust-value {
+  color: var(--color-text-muted, #888);
+  min-width: 32px;
+  text-align: right;
+}
+
+/* Pin button */
+.memory-panel-pin {
+  background: none;
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  color: var(--color-text-muted, #888);
+  font-size: 11px;
+  cursor: pointer;
+  width: 24px;
+  height: 24px;
+  border-radius: 6px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: all 0.15s;
+  flex-shrink: 0;
+}
+
+.memory-panel-pin:hover {
+  background: rgba(255, 255, 255, 0.05);
+  color: #fff;
+}
+
+.memory-panel-pin.pinned {
+  background: rgba(74, 240, 192, 0.15);
+  border-color: rgba(74, 240, 192, 0.4);
+  color: var(--color-primary, #4af0c0);
+}
+
+/* Related row — allow wrapping */
+.memory-meta-row--related {
+  align-items: flex-start;
+}
+
+.memory-meta-row--related span:last-child {
+  flex-wrap: wrap;
+  display: flex;
+  gap: 2px;
+}
+
+/* ═══════════════════════════════════════════════════════
+   PROJECT MNEMOSYNE — SESSION ROOM HUD PANEL (#1171)
+═══════════════════════════════════════════════════════ */
+
+.session-room-panel {
+  position: fixed;
+  bottom: 24px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 125;
+  animation: sessionPanelIn 0.25s ease-out forwards;
+}
+
+.session-room-panel.session-panel-fade-out {
+  animation: sessionPanelOut 0.2s ease-in forwards !important;
+}
+
+@keyframes sessionPanelIn {
+  from { opacity: 0; transform: translateX(-50%) translateY(12px); }
+  to   { opacity: 1; transform: translateX(-50%) translateY(0); }
+}
+
+@keyframes sessionPanelOut {
+  from { opacity: 1; }
+  to   { opacity: 0; transform: translateX(-50%) translateY(10px); }
+}
+
+.session-room-panel-content {
+  min-width: 320px;
+  max-width: 480px;
+  background: rgba(8, 4, 28, 0.93);
+  backdrop-filter: blur(14px);
+  border: 1px solid rgba(123, 92, 255, 0.35);
+  border-radius: 12px;
+  padding: 14px 18px;
+  box-shadow: 0 0 32px rgba(123, 92, 255, 0.1), 0 8px 32px rgba(0, 0, 0, 0.45);
+}
+
+.session-room-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 8px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.07);
+}
+
+.session-room-icon {
+  font-size: 14px;
+  line-height: 1;
+}
+
+.session-room-title {
+  font-family: var(--font-display, monospace);
+  font-size: 11px;
+  letter-spacing: 0.18em;
+  color: #9b7cff;
+  text-transform: uppercase;
+  flex: 1;
+}
+
+.session-room-close {
+  background: none;
+  border: none;
+  color: rgba(255, 255, 255, 0.35);
+  cursor: pointer;
+  font-size: 14px;
+  padding: 0 2px;
+  line-height: 1;
+  transition: color 0.15s;
+}
+
+.session-room-close:hover {
+  color: rgba(255, 255, 255, 0.8);
+}
+
+.session-room-timestamp {
+  font-family: var(--font-display, monospace);
+  font-size: 13px;
+  color: #c8b4ff;
+  margin-bottom: 6px;
+  letter-spacing: 0.08em;
+}
+
+.session-room-fact-count {
+  font-size: 11px;
+  color: rgba(200, 180, 255, 0.55);
+  margin-bottom: 10px;
+}
+
+.session-room-facts {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  max-height: 140px;
+  overflow-y: auto;
+}
+
+.session-room-fact-item {
+  font-size: 11px;
+  color: rgba(220, 210, 255, 0.75);
+  padding: 4px 8px;
+  background: rgba(123, 92, 255, 0.07);
+  border-left: 2px solid rgba(123, 92, 255, 0.4);
+  border-radius: 0 4px 4px 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.session-room-hint {
+  margin-top: 10px;
+  font-size: 10px;
+  color: rgba(200, 180, 255, 0.35);
+  text-align: center;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+