DESIGN.md

@@ -0,0 +1,36 @@
+# Project Mnemosyne: Spatial Memory Schema
+
+## Overview
+Project Mnemosyne transforms the Nexus from a static environment into a real-time visualization of Timmy's holographic memory (fact_store).
+
+## 1. Room Mapping (Categories)
+Memory categories are mapped to specific spatial zones in the Nexus to provide cognitive structure.
+
+| Category | Nexus Room | Visual Theme |
+| :--- | :--- | :--- |
+| user_pref | The Library | Archive shelves, soft lighting, velvet |
+| project | The Workshop | Drafting tables, holographic blueprints, metal |
+| tool | The Armory | Server racks, neon circuitry, chrome |
+| general | The Commons | Open garden, floating islands, eclectic |
+
+## 2. Object Mapping (Facts)
+Every single fact in the holographic memory is represented as a 3D object.
+
+- **Object Type:** Depending on the fact's content, it is rendered as a primitive (sphere, cube, pyramid) or a specific asset.
+- **Luminosity (Trust):** The glow intensity of the object is tied to its trust score (0.0 - 1.0).
+- **Scale (Importance):** The size of the object is tied to the number of relations it has to other facts.
+
+## 3. Spatial Distribution (Coordinates)
+Coordinates are calculated based on semantic adjacency.
+
+- **Clustering:** Facts that are 'related' (via the fact_store adjacency graph) are placed closer together.
+- **Layout Algorithm:** A 3D force-directed graph layout is used within each room.
+- **Centroid:** The most 'central' fact (highest connectivity) is placed at the room's center.
+
+## 4. Lifecycle Events
+The Nexus responds to real-time memory updates:
+- **FACT_CREATED:** A new object fades into existence at the calculated coordinate.
+- **FACT_UPDATED:** The object pulses and adjusts its luminosity/scale.
+- **FACT_REMOVED:** The object dissolves into particles.
+- **FACT_RECALLED:** The object emits a beam of light toward the User/Agent, signaling active use.
+