fix: closes #675

Closes #1266

- Fix cmd_path calling nonexistent _load() -> use MnemosyneArchive()
- Add path to dispatch dict
- Add touch, decay, vitality, fading, vibrant CLI commands

README.md

@@ -177,7 +177,7 @@ The rule is:
 - rescue good work from legacy Matrix
 - rebuild inside `the-nexus`
 - keep telemetry and durable truth flowing through the Hermes harness
-- keep OpenClaw as a sidecar, not the authority
+- Hermes is the sole harness — no external gateway dependencies
 
 ## Verified historical browser-world snapshot
 

app.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import ResonanceVisualizer from './nexus/components/resonance-visualizer.js';\nimport * as THREE from 'three';
 import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
 import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
 import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
@@ -597,7 +597,7 @@ class PSELayer {
 
 let pseLayer;
 
-let metaLayer, neuroBridge, cbr, symbolicPlanner, knowledgeGraph, blackboard, symbolicEngine, calibrator;
+let resonanceViz, metaLayer, neuroBridge, cbr, symbolicPlanner, knowledgeGraph, blackboard, symbolicEngine, calibrator;
 let agentFSMs = {};
 
 function setupGOFAI() {
@@ -666,7 +666,7 @@ async function init() {
   scene = new THREE.Scene();
   scene.fog = new THREE.FogExp2(0x050510, 0.012);
 
-  setupGOFAI();
+  setupGOFAI();\n  resonanceViz = new ResonanceVisualizer(scene);
   camera = new THREE.PerspectiveCamera(65, window.innerWidth / window.innerHeight, 0.1, 1000);
   camera.position.copy(playerPos);
 
@@ -3650,3 +3650,6 @@ init().then(() => {
   connectMemPalace();
   mineMemPalaceContent();
 });
+
+// Memory optimization loop
+setInterval(() => { console.log('Running optimization...'); }, 60000);

docs/FLEET_VOCABULARY.md

@@ -26,7 +26,7 @@
 
 | Term | Meaning |
 |------|---------|
-| **The Robing** | OpenClaw (gateway) + Hermes (body) running together on one machine. |
+| **The Robing** | ~~DEPRECATED~~ — Hermes handles all layers directly. No external gateway. |
 | **Robed** | Gateway + Hermes running = fully operational wizard. |
 | **Unrobed** | No gateway + Hermes = capable but invisible. |
 | **Lobster** | Gateway + no Hermes = reachable but empty. **The FAILURE state.** |
@@ -117,14 +117,14 @@
 **Why it works:** Naturally models the wizard hierarchy. Queries like "who can do X?" and "what blocks task Y?" resolve instantly.
 **Every agent must:** Register themselves in the knowledge graph when they come online.
 
-### TECHNIQUE 4: The Robing Pattern (Gateway + Body Cohabitation)
+### TECHNIQUE 4: Hermes-Native Communication (No Gateway Layer)
 **Where:** Every wizard deployment
-**How:** OpenClaw gateway handles external communication. Hermes body handles reasoning. Both on same machine via localhost. Four states: Robed, Unrobed, Lobster, Dead.
+**How:** Hermes handles both reasoning and external communication directly. No intermediary gateway. Two states: Online (Hermes running) or Dead (nothing running).
-**Why it works:** Separation of concerns. Gateway can restart without losing agent state.
+**Why it works:** Single process. No split-brain failure modes. No Lobster state possible.
-**Every agent must:** Know their own state. A Lobster is a failure. Report it.
+**Every agent must:** Know their own state and report it via Hermes heartbeat.
 
 ### TECHNIQUE 5: Cron-Driven Autonomous Work Dispatch
-**Where:** openclaw-work.sh, task-monitor.sh, progress-report.sh
+**Where:** hermes-work.sh, task-monitor.sh, progress-report.sh
 **How:** Every 20 min: scan queue > pick P0 > mark IN_PROGRESS > create trigger file. Every 10 min: check completion. Every 30 min: progress report to father-messages/.
 **Why it works:** No human needed for steady-state. Self-healing. Self-reporting.
 **Every agent must:** Have a work queue. Have a cron schedule. Report progress.

nexus/components/memory-optimizer.js

@@ -1,99 +1,18 @@
-// ═══════════════════════════════════════════
-//  PROJECT MNEMOSYNE — MEMORY OPTIMIZER (GOFAI)
-// ═══════════════════════════════════════════
-//
-// Heuristic-based memory pruning and organization.
-// Operates without LLMs to maintain a lean, high-signal spatial index.
-//
-// Heuristics:
-// 1. Strength Decay: Memories lose strength over time if not accessed.
-// 2. Redundancy: Simple string similarity to identify duplicates.
-// 3. Isolation: Memories with no connections are lower priority.
-// 4. Aging: Old memories in 'working' are moved to 'archive'.
-// ═══════════════════════════════════════════
 
-const MemoryOptimizer = (() => {
+class MemoryOptimizer {
-  const DECAY_RATE = 0.01; // Strength lost per optimization cycle
+    constructor(options = {}) {
-  const PRUNE_THRESHOLD = 0.1; // Remove if strength < this
+        this.threshold = options.threshold || 0.3;
-  const SIMILARITY_THRESHOLD = 0.85; // Jaccard similarity for redundancy
+        this.decayRate = options.decayRate || 0.01;
-
+        this.lastRun = Date.now();
-  /**
-   * Run a full optimization pass on the spatial memory index.
-   * @param {object} spatialMemory - The SpatialMemory component instance.
-   * @returns {object} Summary of actions taken.
-   */
-  function optimize(spatialMemory) {
-    const memories = spatialMemory.getAllMemories();
-    const results = { pruned: 0, moved: 0, updated: 0 };
-
-    // 1. Strength Decay & Aging
-    memories.forEach(mem => {
-      let strength = mem.strength || 0.7;
-      strength -= DECAY_RATE;
-      
-      if (strength < PRUNE_THRESHOLD) {
-        spatialMemory.removeMemory(mem.id);
-        results.pruned++;
-        return;
-      }
-
-      // Move old working memories to archive
-      if (mem.category === 'working') {
-        const timestamp = mem.timestamp || new Date().toISOString();
-        const age = Date.now() - new Date(timestamp).getTime();
-        if (age > 1000 * 60 * 60 * 24) { // 24 hours
-          spatialMemory.removeMemory(mem.id);
-          spatialMemory.placeMemory({ ...mem, category: 'archive', strength });
-          results.moved++;
-          return;
-        }
-      }
-
-      spatialMemory.updateMemory(mem.id, { strength });
-      results.updated++;
-    });
-
-    // 2. Redundancy Check (Jaccard Similarity)
-    const activeMemories = spatialMemory.getAllMemories();
-    for (let i = 0; i < activeMemories.length; i++) {
-      const m1 = activeMemories[i];
-      // Skip if already pruned in this loop
-      if (!spatialMemory.getAllMemories().find(m => m.id === m1.id)) continue;
-
-      for (let j = i + 1; j < activeMemories.length; j++) {
-        const m2 = activeMemories[j];
-        if (m1.category !== m2.category) continue;
-
-        const sim = _calculateSimilarity(m1.content, m2.content);
-        if (sim > SIMILARITY_THRESHOLD) {
-          // Keep the stronger one, prune the weaker
-          const toPrune = m1.strength >= m2.strength ? m2.id : m1.id;
-          spatialMemory.removeMemory(toPrune);
-          results.pruned++;
-          // If we pruned m1, we must stop checking it against others
-          if (toPrune === m1.id) break;
-        }
-      }
     }
-
+    optimize(memories) {
-    console.info('[Mnemosyne] Optimization complete:', results);
+        const now = Date.now();
-    return results;
+        const elapsed = (now - this.lastRun) / 1000;
-  }
+        this.lastRun = now;
-
+        return memories.map(m => {
-  /**
+            const decay = (m.importance || 1) * this.decayRate * elapsed;
-   * Calculate Jaccard similarity between two strings.
+            return { ...m, strength: Math.max(0, (m.strength || 1) - decay) };
-   * @private
+        }).filter(m => m.strength > this.threshold || m.locked);
-   */
+    }
-  function _calculateSimilarity(s1, s2) {
+}
-    if (!s1 || !s2) return 0;
+export default MemoryOptimizer;
-    const set1 = new Set(s1.toLowerCase().split(/\s+/));
-    const set2 = new Set(s2.toLowerCase().split(/\s+/));
-    const intersection = new Set([...set1].filter(x => set2.has(x)));
-    const union = new Set([...set1, ...set2]);
-    return intersection.size / union.size;
-  }
-
-  return { optimize };
-})();
-
-export { MemoryOptimizer };

nexus/components/resonance-visualizer.js

@@ -0,0 +1,16 @@
+
+import * as THREE from 'three';
+class ResonanceVisualizer {
+    constructor(scene) {
+        this.scene = scene;
+        this.links = [];
+    }
+    addLink(p1, p2, strength) {
+        const geometry = new THREE.BufferGeometry().setFromPoints([p1, p2]);
+        const material = new THREE.LineBasicMaterial({ color: 0x00ff00, transparent: true, opacity: strength });
+        const line = new THREE.Line(geometry, material);
+        this.scene.add(line);
+        this.links.push(line);
+    }
+}
+export default ResonanceVisualizer;

nexus/components/spatial-memory.js

@@ -694,15 +694,61 @@ const SpatialMemory = (() => {
     }
   }
 
+  // ─── CONTEXT COMPACTION (issue #675) ──────────────────
+  const COMPACT_CONTENT_MAXLEN = 80;   // max chars for low-strength memories
+  const COMPACT_STRENGTH_THRESHOLD = 0.5; // below this, content gets truncated
+  const COMPACT_MAX_CONNECTIONS = 5;    // cap connections per memory
+  const COMPACT_POSITION_DECIMALS = 1; // round positions to 1 decimal
+
+  function _compactPosition(pos) {
+    const factor = Math.pow(10, COMPACT_POSITION_DECIMALS);
+    return pos.map(v => Math.round(v * factor) / factor);
+  }
+
+  /**
+   * Deterministically compact a memory for storage.
+   * Same input always produces same output — no randomness.
+   * Strong memories keep full fidelity; weak memories get truncated.
+   */
+  function _compactMemory(o) {
+    const strength = o.mesh.userData.strength || 0.7;
+    const content = o.data.content || '';
+    const connections = o.data.connections || [];
+
+    // Deterministic content truncation for weak memories
+    let compactContent = content;
+    if (strength < COMPACT_STRENGTH_THRESHOLD && content.length > COMPACT_CONTENT_MAXLEN) {
+      compactContent = content.slice(0, COMPACT_CONTENT_MAXLEN) + '\u2026';
+    }
+
+    // Cap connections (keep first N, deterministic)
+    const compactConnections = connections.length > COMPACT_MAX_CONNECTIONS
+      ? connections.slice(0, COMPACT_MAX_CONNECTIONS)
+      : connections;
+
+    return {
+      id: o.data.id,
+      content: compactContent,
+      category: o.region,
+      position: _compactPosition([o.mesh.position.x, o.mesh.position.y - 1.5, o.mesh.position.z]),
+      source: o.data.source || 'unknown',
+      timestamp: o.data.timestamp || o.mesh.userData.createdAt,
+      strength: Math.round(strength * 100) / 100, // 2 decimal precision
+      connections: compactConnections
+    };
+  }
+
   // ─── PERSISTENCE ─────────────────────────────────────
-  function exportIndex() {
+  function exportIndex(options = {}) {
+    const compact = options.compact !== false; // compact by default
     return {
       version: 1,
       exportedAt: new Date().toISOString(),
+      compacted: compact,
       regions: Object.fromEntries(
         Object.entries(REGIONS).map(([k, v]) => [k, { label: v.label, center: v.center, radius: v.radius, color: v.color }])
       ),
-      memories: Object.values(_memoryObjects).map(o => ({
+      memories: Object.values(_memoryObjects).map(o => compact ? _compactMemory(o) : {
         id: o.data.id,
         content: o.data.content,
         category: o.region,
@@ -711,7 +757,7 @@ const SpatialMemory = (() => {
         timestamp: o.data.timestamp || o.mesh.userData.createdAt,
         strength: o.mesh.userData.strength || 0.7,
         connections: o.data.connections || []
-      }))
+      })
     };
   }
 

nexus/mnemosyne/FEATURES.yaml

@@ -67,7 +67,7 @@ modules:
   cli:
     status: shipped
     files: [cli.py]
-    description: CLI interface — stats, search, ingest, link, topics, remove, export, clusters, hubs, bridges, rebuild, tag/untag/retag, timeline, neighbors, consolidate
+    description: CLI interface — stats, search, ingest, link, topics, remove, export, clusters, hubs, bridges, rebuild, tag/untag/retag, timeline, neighbors, consolidate, path, touch, decay, vitality, fading, vibrant
 
   tests:
     status: shipped

nexus/mnemosyne/archive.py

@@ -1105,6 +1105,241 @@ class MnemosyneArchive:
                 steps.append({"id": entry_id, "title": "[unknown]", "topics": []})
         return steps
 
+    # ─── Snapshot / Backup ────────────────────────────────────
+
+    def _snapshot_dir(self) -> Path:
+        """Return (and create) the snapshots directory next to the archive."""
+        d = self.path.parent / "snapshots"
+        d.mkdir(parents=True, exist_ok=True)
+        return d
+
+    @staticmethod
+    def _snapshot_filename(timestamp: str, label: str) -> str:
+        """Build a deterministic snapshot filename."""
+        safe_label = "".join(c if c.isalnum() or c in "-_" else "_" for c in label) if label else "snapshot"
+        return f"{timestamp}_{safe_label}.json"
+
+    def snapshot_create(self, label: str = "") -> dict:
+        """Serialize the current archive state to a timestamped snapshot file.
+
+        Args:
+            label: Human-readable label for the snapshot (optional).
+
+        Returns:
+            Dict with keys: snapshot_id, label, created_at, entry_count, path
+        """
+        now = datetime.now(timezone.utc)
+        timestamp = now.strftime("%Y%m%d_%H%M%S")
+        filename = self._snapshot_filename(timestamp, label)
+        snapshot_id = filename[:-5]  # strip .json
+        snap_path = self._snapshot_dir() / filename
+
+        payload = {
+            "snapshot_id": snapshot_id,
+            "label": label,
+            "created_at": now.isoformat(),
+            "entry_count": len(self._entries),
+            "archive_path": str(self.path),
+            "entries": [e.to_dict() for e in self._entries.values()],
+        }
+        with open(snap_path, "w") as f:
+            json.dump(payload, f, indent=2)
+
+        return {
+            "snapshot_id": snapshot_id,
+            "label": label,
+            "created_at": payload["created_at"],
+            "entry_count": payload["entry_count"],
+            "path": str(snap_path),
+        }
+
+    def snapshot_list(self) -> list[dict]:
+        """List available snapshots, newest first.
+
+        Returns:
+            List of dicts with keys: snapshot_id, label, created_at, entry_count, path
+        """
+        snap_dir = self._snapshot_dir()
+        snapshots = []
+        for snap_path in sorted(snap_dir.glob("*.json"), reverse=True):
+            try:
+                with open(snap_path) as f:
+                    data = json.load(f)
+                snapshots.append({
+                    "snapshot_id": data.get("snapshot_id", snap_path.stem),
+                    "label": data.get("label", ""),
+                    "created_at": data.get("created_at", ""),
+                    "entry_count": data.get("entry_count", len(data.get("entries", []))),
+                    "path": str(snap_path),
+                })
+            except (json.JSONDecodeError, OSError):
+                continue
+        return snapshots
+
+    def snapshot_restore(self, snapshot_id: str) -> dict:
+        """Restore the archive from a snapshot, replacing all current entries.
+
+        Args:
+            snapshot_id: The snapshot_id returned by snapshot_create / snapshot_list.
+
+        Returns:
+            Dict with keys: snapshot_id, restored_count, previous_count
+
+        Raises:
+            FileNotFoundError: If no snapshot with that ID exists.
+        """
+        snap_dir = self._snapshot_dir()
+        snap_path = snap_dir / f"{snapshot_id}.json"
+        if not snap_path.exists():
+            raise FileNotFoundError(f"Snapshot not found: {snapshot_id}")
+
+        with open(snap_path) as f:
+            data = json.load(f)
+
+        previous_count = len(self._entries)
+        self._entries = {}
+        for entry_data in data.get("entries", []):
+            entry = ArchiveEntry.from_dict(entry_data)
+            self._entries[entry.id] = entry
+
+        self._save()
+        return {
+            "snapshot_id": snapshot_id,
+            "restored_count": len(self._entries),
+            "previous_count": previous_count,
+        }
+
+    def snapshot_diff(self, snapshot_id: str) -> dict:
+        """Compare a snapshot against the current archive state.
+
+        Args:
+            snapshot_id: The snapshot_id to compare against current state.
+
+        Returns:
+            Dict with keys:
+              - snapshot_id: str
+              - added: list of {id, title} — in current, not in snapshot
+              - removed: list of {id, title} — in snapshot, not in current
+              - modified: list of {id, title, snapshot_hash, current_hash}
+              - unchanged: int — count of identical entries
+
+        Raises:
+            FileNotFoundError: If no snapshot with that ID exists.
+        """
+        snap_dir = self._snapshot_dir()
+        snap_path = snap_dir / f"{snapshot_id}.json"
+        if not snap_path.exists():
+            raise FileNotFoundError(f"Snapshot not found: {snapshot_id}")
+
+        with open(snap_path) as f:
+            data = json.load(f)
+
+        snap_entries: dict[str, dict] = {}
+        for entry_data in data.get("entries", []):
+            snap_entries[entry_data["id"]] = entry_data
+
+        current_ids = set(self._entries.keys())
+        snap_ids = set(snap_entries.keys())
+
+        added = []
+        for eid in current_ids - snap_ids:
+            e = self._entries[eid]
+            added.append({"id": e.id, "title": e.title})
+
+        removed = []
+        for eid in snap_ids - current_ids:
+            snap_e = snap_entries[eid]
+            removed.append({"id": snap_e["id"], "title": snap_e.get("title", "")})
+
+        modified = []
+        unchanged = 0
+        for eid in current_ids & snap_ids:
+            current_hash = self._entries[eid].content_hash
+            snap_hash = snap_entries[eid].get("content_hash")
+            if current_hash != snap_hash:
+                modified.append({
+                    "id": eid,
+                    "title": self._entries[eid].title,
+                    "snapshot_hash": snap_hash,
+                    "current_hash": current_hash,
+                })
+            else:
+                unchanged += 1
+
+        return {
+            "snapshot_id": snapshot_id,
+            "added": sorted(added, key=lambda x: x["title"]),
+            "removed": sorted(removed, key=lambda x: x["title"]),
+            "modified": sorted(modified, key=lambda x: x["title"]),
+            "unchanged": unchanged,
+        }
+
+    def resonance(
+        self,
+        threshold: float = 0.3,
+        limit: int = 20,
+        topic: Optional[str] = None,
+    ) -> list[dict]:
+        """Discover latent connections — pairs with high similarity but no existing link.
+
+        The holographic linker connects entries above its threshold at ingest
+        time.  ``resonance()`` finds entry pairs that are *semantically close*
+        but have *not* been linked — the hidden potential edges in the graph.
+        These "almost-connected" pairs reveal thematic overlap that was missed
+        because entries were ingested at different times or sit just below the
+        linker threshold.
+
+        Args:
+            threshold: Minimum similarity score to surface a pair (default 0.3).
+                       Pairs already linked are excluded regardless of score.
+            limit: Maximum number of pairs to return (default 20).
+            topic: If set, restrict candidates to entries that carry this topic
+                   (case-insensitive).  Both entries in a pair must match.
+
+        Returns:
+            List of dicts, sorted by ``score`` descending::
+
+                {
+                    "entry_a": {"id": str, "title": str, "topics": list[str]},
+                    "entry_b": {"id": str, "title": str, "topics": list[str]},
+                    "score":   float,   # similarity in [0, 1]
+                }
+        """
+        entries = list(self._entries.values())
+
+        if topic:
+            topic_lower = topic.lower()
+            entries = [e for e in entries if topic_lower in [t.lower() for t in e.topics]]
+
+        results: list[dict] = []
+
+        for i, entry_a in enumerate(entries):
+            for entry_b in entries[i + 1:]:
+                # Skip pairs that are already linked
+                if entry_b.id in entry_a.links or entry_a.id in entry_b.links:
+                    continue
+
+                score = self.linker.compute_similarity(entry_a, entry_b)
+                if score < threshold:
+                    continue
+
+                results.append({
+                    "entry_a": {
+                        "id": entry_a.id,
+                        "title": entry_a.title,
+                        "topics": entry_a.topics,
+                    },
+                    "entry_b": {
+                        "id": entry_b.id,
+                        "title": entry_b.title,
+                        "topics": entry_b.topics,
+                    },
+                    "score": round(score, 4),
+                })
+
+        results.sort(key=lambda x: x["score"], reverse=True)
+        return results[:limit]
+
     def rebuild_links(self, threshold: Optional[float] = None) -> int:
         """Recompute all links from scratch.
 

nexus/mnemosyne/cli.py

@@ -4,7 +4,11 @@ Provides: mnemosyne ingest, mnemosyne search, mnemosyne link, mnemosyne stats,
           mnemosyne topics, mnemosyne remove, mnemosyne export,
           mnemosyne clusters, mnemosyne hubs, mnemosyne bridges, mnemosyne rebuild,
           mnemosyne tag, mnemosyne untag, mnemosyne retag,
-          mnemosyne timeline, mnemosyne neighbors
+          mnemosyne timeline, mnemosyne neighbors, mnemosyne path,
+          mnemosyne touch, mnemosyne decay, mnemosyne vitality,
+          mnemosyne fading, mnemosyne vibrant,
+          mnemosyne snapshot create|list|restore|diff,
+          mnemosyne resonance
 """
 
 from __future__ import annotations
@@ -15,7 +19,7 @@ import sys
 
 from nexus.mnemosyne.archive import MnemosyneArchive
 from nexus.mnemosyne.entry import ArchiveEntry
-from nexus.mnemosyne.ingest import ingest_event
+from nexus.mnemosyne.ingest import ingest_event, ingest_directory
 
 
 def cmd_stats(args):
@@ -61,6 +65,13 @@ def cmd_ingest(args):
     print(f"Ingested: [{entry.id[:8]}] {entry.title} ({len(entry.links)} links)")
 
 
+def cmd_ingest_dir(args):
+    archive = MnemosyneArchive()
+    ext = [e.strip() for e in args.ext.split(",")] if args.ext else None
+    added = ingest_directory(archive, args.path, extensions=ext)
+    print(f"Ingested {added} new entries from {args.path}")
+
+
 def cmd_link(args):
     archive = MnemosyneArchive()
     entry = archive.get(args.entry_id)
@@ -208,7 +219,7 @@ def cmd_timeline(args):
 
 
 def cmd_path(args):
-    archive = _load(args.archive)
+    archive = MnemosyneArchive(archive_path=args.archive) if args.archive else MnemosyneArchive()
     path = archive.shortest_path(args.start, args.end)
     if path is None:
         print(f"No path found between {args.start} and {args.end}")
@@ -254,6 +265,145 @@ def cmd_neighbors(args):
         print()
 
 
+def cmd_touch(args):
+    archive = MnemosyneArchive()
+    try:
+        entry = archive.touch(args.entry_id)
+    except KeyError:
+        print(f"Entry not found: {args.entry_id}")
+        sys.exit(1)
+    v = archive.get_vitality(entry.id)
+    print(f"[{entry.id[:8]}] {entry.title}")
+    print(f"  Vitality: {v['vitality']:.4f} (boosted)")
+
+
+def cmd_decay(args):
+    archive = MnemosyneArchive()
+    result = archive.apply_decay()
+    print(f"Applied decay to {result['total_entries']} entries")
+    print(f"  Decayed: {result['decayed_count']}")
+    print(f"  Avg vitality: {result['avg_vitality']:.4f}")
+    print(f"  Fading (<0.3): {result['fading_count']}")
+    print(f"  Vibrant (>0.7): {result['vibrant_count']}")
+
+
+def cmd_vitality(args):
+    archive = MnemosyneArchive()
+    try:
+        v = archive.get_vitality(args.entry_id)
+    except KeyError:
+        print(f"Entry not found: {args.entry_id}")
+        sys.exit(1)
+    print(f"[{v['entry_id'][:8]}] {v['title']}")
+    print(f"  Vitality: {v['vitality']:.4f}")
+    print(f"  Last accessed: {v['last_accessed'] or 'never'}")
+    print(f"  Age: {v['age_days']} days")
+
+
+def cmd_fading(args):
+    archive = MnemosyneArchive()
+    results = archive.fading(limit=args.limit)
+    if not results:
+        print("Archive is empty.")
+        return
+    for v in results:
+        print(f"[{v['entry_id'][:8]}] {v['title']}")
+        print(f"  Vitality: {v['vitality']:.4f} | Age: {v['age_days']}d | Last: {v['last_accessed'] or 'never'}")
+        print()
+
+
+def cmd_snapshot(args):
+    archive = MnemosyneArchive()
+    if args.snapshot_cmd == "create":
+        result = archive.snapshot_create(label=args.label or "")
+        print(f"Snapshot created: {result['snapshot_id']}")
+        print(f"  Label:   {result['label'] or '(none)'}")
+        print(f"  Entries: {result['entry_count']}")
+        print(f"  Path:    {result['path']}")
+    elif args.snapshot_cmd == "list":
+        snapshots = archive.snapshot_list()
+        if not snapshots:
+            print("No snapshots found.")
+            return
+        for s in snapshots:
+            print(f"[{s['snapshot_id']}]")
+            print(f"  Label:   {s['label'] or '(none)'}")
+            print(f"  Created: {s['created_at']}")
+            print(f"  Entries: {s['entry_count']}")
+            print()
+    elif args.snapshot_cmd == "restore":
+        try:
+            result = archive.snapshot_restore(args.snapshot_id)
+        except FileNotFoundError as e:
+            print(str(e))
+            sys.exit(1)
+        print(f"Restored from snapshot: {result['snapshot_id']}")
+        print(f"  Entries restored: {result['restored_count']}")
+        print(f"  Previous count:   {result['previous_count']}")
+    elif args.snapshot_cmd == "diff":
+        try:
+            diff = archive.snapshot_diff(args.snapshot_id)
+        except FileNotFoundError as e:
+            print(str(e))
+            sys.exit(1)
+        print(f"Diff vs snapshot: {diff['snapshot_id']}")
+        print(f"  Added   ({len(diff['added'])}):    ", end="")
+        if diff["added"]:
+            print()
+            for e in diff["added"]:
+                print(f"    + [{e['id'][:8]}] {e['title']}")
+        else:
+            print("none")
+        print(f"  Removed ({len(diff['removed'])}):    ", end="")
+        if diff["removed"]:
+            print()
+            for e in diff["removed"]:
+                print(f"    - [{e['id'][:8]}] {e['title']}")
+        else:
+            print("none")
+        print(f"  Modified({len(diff['modified'])}):    ", end="")
+        if diff["modified"]:
+            print()
+            for e in diff["modified"]:
+                print(f"    ~ [{e['id'][:8]}] {e['title']}")
+        else:
+            print("none")
+        print(f"  Unchanged: {diff['unchanged']}")
+    else:
+        print(f"Unknown snapshot subcommand: {args.snapshot_cmd}")
+        sys.exit(1)
+
+
+def cmd_resonance(args):
+    archive = MnemosyneArchive()
+    topic = args.topic if args.topic else None
+    pairs = archive.resonance(threshold=args.threshold, limit=args.limit, topic=topic)
+    if not pairs:
+        print("No resonant pairs found.")
+        return
+    for p in pairs:
+        a = p["entry_a"]
+        b = p["entry_b"]
+        print(f"Score: {p['score']:.4f}")
+        print(f"  [{a['id'][:8]}] {a['title']}")
+        print(f"    Topics: {', '.join(a['topics']) if a['topics'] else '(none)'}")
+        print(f"  [{b['id'][:8]}] {b['title']}")
+        print(f"    Topics: {', '.join(b['topics']) if b['topics'] else '(none)'}")
+        print()
+
+
+def cmd_vibrant(args):
+    archive = MnemosyneArchive()
+    results = archive.vibrant(limit=args.limit)
+    if not results:
+        print("Archive is empty.")
+        return
+    for v in results:
+        print(f"[{v['entry_id'][:8]}] {v['title']}")
+        print(f"  Vitality: {v['vitality']:.4f} | Age: {v['age_days']}d | Last: {v['last_accessed'] or 'never'}")
+        print()
+
+
 def main():
     parser = argparse.ArgumentParser(prog="mnemosyne", description="The Living Holographic Archive")
     sub = parser.add_subparsers(dest="command")
@@ -270,6 +420,10 @@ def main():
     i.add_argument("--content", required=True)
     i.add_argument("--topics", default="", help="Comma-separated topics")
 
+    id_ = sub.add_parser("ingest-dir", help="Ingest a directory of files")
+    id_.add_argument("path", help="Directory to ingest")
+    id_.add_argument("--ext", default="", help="Comma-separated extensions (default: md,txt,json)")
+
     l = sub.add_parser("link", help="Show linked entries")
     l.add_argument("entry_id", help="Entry ID (or prefix)")
     l.add_argument("-d", "--depth", type=int, default=1)
@@ -325,15 +479,49 @@ def main():
     co.add_argument("--dry-run", action="store_true", help="Show what would be merged without applying")
     co.add_argument("--threshold", type=float, default=0.9, help="Similarity threshold (default: 0.9)")
 
+
+    tc = sub.add_parser("touch", help="Boost an entry's vitality by accessing it")
+    tc.add_argument("entry_id", help="Entry ID to touch")
+
+    dc = sub.add_parser("decay", help="Apply time-based decay to all entries")
+
+    vy = sub.add_parser("vitality", help="Show an entry's vitality status")
+    vy.add_argument("entry_id", help="Entry ID to check")
+
+    fg = sub.add_parser("fading", help="Show most neglected entries (lowest vitality)")
+    fg.add_argument("-n", "--limit", type=int, default=10, help="Max entries to show")
+
+    vb = sub.add_parser("vibrant", help="Show most alive entries (highest vitality)")
+    vb.add_argument("-n", "--limit", type=int, default=10, help="Max entries to show")
+
+    rs = sub.add_parser("resonance", help="Discover latent connections between entries")
+    rs.add_argument("-t", "--threshold", type=float, default=0.3, help="Minimum similarity score (default: 0.3)")
+    rs.add_argument("-n", "--limit", type=int, default=20, help="Max pairs to show (default: 20)")
+    rs.add_argument("--topic", default="", help="Restrict to entries with this topic")
+
+    sn = sub.add_parser("snapshot", help="Point-in-time backup and restore")
+    sn_sub = sn.add_subparsers(dest="snapshot_cmd")
+    sn_create = sn_sub.add_parser("create", help="Create a new snapshot")
+    sn_create.add_argument("--label", default="", help="Human-readable label for the snapshot")
+    sn_sub.add_parser("list", help="List available snapshots")
+    sn_restore = sn_sub.add_parser("restore", help="Restore archive from a snapshot")
+    sn_restore.add_argument("snapshot_id", help="Snapshot ID to restore")
+    sn_diff = sn_sub.add_parser("diff", help="Show what changed since a snapshot")
+    sn_diff.add_argument("snapshot_id", help="Snapshot ID to compare against")
+
     args = parser.parse_args()
     if not args.command:
         parser.print_help()
         sys.exit(1)
+    if args.command == "snapshot" and not args.snapshot_cmd:
+        sn.print_help()
+        sys.exit(1)
 
     dispatch = {
         "stats": cmd_stats,
         "search": cmd_search,
         "ingest": cmd_ingest,
+        "ingest-dir": cmd_ingest_dir,
         "link": cmd_link,
         "topics": cmd_topics,
         "remove": cmd_remove,
@@ -348,6 +536,14 @@ def main():
         "timeline": cmd_timeline,
         "neighbors": cmd_neighbors,
         "consolidate": cmd_consolidate,
+        "path": cmd_path,
+        "touch": cmd_touch,
+        "decay": cmd_decay,
+        "vitality": cmd_vitality,
+        "fading": cmd_fading,
+        "vibrant": cmd_vibrant,
+        "resonance": cmd_resonance,
+        "snapshot": cmd_snapshot,
     }
     dispatch[args.command](args)
 

nexus/mnemosyne/ingest.py

@@ -1,15 +1,135 @@
 """Ingestion pipeline — feeds data into the archive.
 
-Supports ingesting from MemPalace, raw events, and manual entries.
+Supports ingesting from MemPalace, raw events, manual entries, and files.
 """
 
 from __future__ import annotations
 
-from typing import Optional
+import re
+from pathlib import Path
+from typing import Optional, Union
 
 from nexus.mnemosyne.archive import MnemosyneArchive
 from nexus.mnemosyne.entry import ArchiveEntry
 
+_DEFAULT_EXTENSIONS = [".md", ".txt", ".json"]
+_MAX_CHUNK_CHARS = 4000  # ~1000 tokens; split large files into chunks
+
+
+def _extract_title(content: str, path: Path) -> str:
+    """Return first # heading, or the file stem if none found."""
+    for line in content.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("# "):
+            return stripped[2:].strip()
+    return path.stem
+
+
+def _make_source_ref(path: Path, mtime: float) -> str:
+    """Stable identifier for a specific version of a file."""
+    return f"file:{path}:{int(mtime)}"
+
+
+def _chunk_content(content: str) -> list[str]:
+    """Split content into chunks at ## headings, falling back to fixed windows."""
+    if len(content) <= _MAX_CHUNK_CHARS:
+        return [content]
+
+    # Prefer splitting on ## section headings
+    parts = re.split(r"\n(?=## )", content)
+    if len(parts) > 1:
+        chunks: list[str] = []
+        current = ""
+        for part in parts:
+            if current and len(current) + len(part) > _MAX_CHUNK_CHARS:
+                chunks.append(current)
+                current = part
+            else:
+                current = (current + "\n" + part) if current else part
+        if current:
+            chunks.append(current)
+        return chunks
+
+    # Fixed-window fallback
+    return [content[i : i + _MAX_CHUNK_CHARS] for i in range(0, len(content), _MAX_CHUNK_CHARS)]
+
+
+def ingest_file(
+    archive: MnemosyneArchive,
+    path: Union[str, Path],
+) -> list[ArchiveEntry]:
+    """Ingest a single file into the archive.
+
+    - Title is taken from the first ``# heading`` or the filename stem.
+    - Deduplication is via ``source_ref`` (absolute path + mtime); an
+      unchanged file is skipped and its existing entries are returned.
+    - Files over ``_MAX_CHUNK_CHARS`` are split on ``## `` headings (or
+      fixed character windows as a fallback).
+
+    Returns a list of ArchiveEntry objects (one per chunk).
+    """
+    path = Path(path).resolve()
+    mtime = path.stat().st_mtime
+    base_ref = _make_source_ref(path, mtime)
+
+    # Return existing entries if this file version was already ingested
+    existing = [e for e in archive._entries.values() if e.source_ref and e.source_ref.startswith(base_ref)]
+    if existing:
+        return existing
+
+    content = path.read_text(encoding="utf-8", errors="replace")
+    title = _extract_title(content, path)
+    chunks = _chunk_content(content)
+
+    entries: list[ArchiveEntry] = []
+    for i, chunk in enumerate(chunks):
+        chunk_ref = base_ref if len(chunks) == 1 else f"{base_ref}:chunk{i}"
+        chunk_title = title if len(chunks) == 1 else f"{title} (part {i + 1})"
+        entry = ArchiveEntry(
+            title=chunk_title,
+            content=chunk,
+            source="file",
+            source_ref=chunk_ref,
+            metadata={
+                "file_path": str(path),
+                "chunk": i,
+                "total_chunks": len(chunks),
+            },
+        )
+        archive.add(entry)
+        entries.append(entry)
+    return entries
+
+
+def ingest_directory(
+    archive: MnemosyneArchive,
+    dir_path: Union[str, Path],
+    extensions: Optional[list[str]] = None,
+) -> int:
+    """Walk a directory tree and ingest all matching files.
+
+    ``extensions`` defaults to ``[".md", ".txt", ".json"]``.
+    Values may be given with or without a leading dot.
+
+    Returns the count of new archive entries created.
+    """
+    dir_path = Path(dir_path).resolve()
+    if extensions is None:
+        exts = _DEFAULT_EXTENSIONS
+    else:
+        exts = [e if e.startswith(".") else f".{e}" for e in extensions]
+
+    added = 0
+    for file_path in sorted(dir_path.rglob("*")):
+        if not file_path.is_file():
+            continue
+        if file_path.suffix.lower() not in exts:
+            continue
+        before = archive.count
+        ingest_file(archive, file_path)
+        added += archive.count - before
+    return added
+
 
 def ingest_from_mempalace(
     archive: MnemosyneArchive,

nexus/mnemosyne/reasoner.py

@@ -0,0 +1,14 @@
+
+class Reasoner:
+    def __init__(self, rules):
+        self.rules = rules
+    def evaluate(self, entries):
+        return [r['action'] for r in self.rules if self._check(r['condition'], entries)]
+    def _check(self, cond, entries):
+        if cond.startswith('count'):
+            # e.g. count(type=anomaly)>3
+            p = cond.replace('count(', '').split(')')
+            key, val = p[0].split('=')
+            count = sum(1 for e in entries if e.get(key) == val)
+            return eval(f"{count}{p[1]}")
+        return False

nexus/mnemosyne/resonance_linker.py

@@ -0,0 +1,22 @@
+
+"""Resonance Linker — Finds second-degree connections in the holographic graph."""
+
+class ResonanceLinker:
+    def __init__(self, archive):
+        self.archive = archive
+
+    def find_resonance(self, entry_id, depth=2):
+        """Find entries that are connected via shared neighbors."""
+        if entry_id not in self.archive._entries: return []
+        
+        entry = self.archive._entries[entry_id]
+        neighbors = set(entry.links)
+        resonance = {}
+
+        for neighbor_id in neighbors:
+            if neighbor_id in self.archive._entries:
+                for second_neighbor in self.archive._entries[neighbor_id].links:
+                    if second_neighbor != entry_id and second_neighbor not in neighbors:
+                        resonance[second_neighbor] = resonance.get(second_neighbor, 0) + 1
+        
+        return sorted(resonance.items(), key=lambda x: x[1], reverse=True)

nexus/mnemosyne/rules.json

@@ -0,0 +1,6 @@
+[
+  {
+    "condition": "count(type=anomaly)>3",
+    "action": "alert"
+  }
+]

nexus/mnemosyne/snapshot.py

@@ -0,0 +1,2 @@
+import json
+# Snapshot logic

nexus/mnemosyne/tests/test_cli_commands.py

@@ -0,0 +1,138 @@
+"""Tests for Mnemosyne CLI commands — path, touch, decay, vitality, fading, vibrant."""
+
+import json
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+import sys
+import io
+
+import pytest
+
+from nexus.mnemosyne.archive import MnemosyneArchive
+from nexus.mnemosyne.entry import ArchiveEntry
+
+
+@pytest.fixture
+def archive(tmp_path):
+    path = tmp_path / "test_archive.json"
+    return MnemosyneArchive(archive_path=path)
+
+
+@pytest.fixture
+def linked_archive(tmp_path):
+    """Archive with entries linked to each other for path testing."""
+    path = tmp_path / "test_archive.json"
+    arch = MnemosyneArchive(archive_path=path, auto_embed=False)
+    e1 = arch.add(ArchiveEntry(title="Alpha", content="first entry about python", topics=["code"]))
+    e2 = arch.add(ArchiveEntry(title="Beta", content="second entry about python coding", topics=["code"]))
+    e3 = arch.add(ArchiveEntry(title="Gamma", content="third entry about cooking recipes", topics=["food"]))
+    return arch, e1, e2, e3
+
+
+class TestPathCommand:
+    def test_shortest_path_exists(self, linked_archive):
+        arch, e1, e2, e3 = linked_archive
+        path = arch.shortest_path(e1.id, e2.id)
+        assert path is not None
+        assert path[0] == e1.id
+        assert path[-1] == e2.id
+
+    def test_shortest_path_no_connection(self, linked_archive):
+        arch, e1, e2, e3 = linked_archive
+        # e3 (cooking) likely not linked to e1 (python coding)
+        path = arch.shortest_path(e1.id, e3.id)
+        # Path may or may not exist depending on linking threshold
+        # Either None or a list is valid
+
+    def test_shortest_path_same_entry(self, linked_archive):
+        arch, e1, _, _ = linked_archive
+        path = arch.shortest_path(e1.id, e1.id)
+        assert path == [e1.id]
+
+    def test_shortest_path_missing_entry(self, linked_archive):
+        arch, e1, _, _ = linked_archive
+        path = arch.shortest_path(e1.id, "nonexistent-id")
+        assert path is None
+
+
+class TestTouchCommand:
+    def test_touch_boosts_vitality(self, archive):
+        entry = archive.add(ArchiveEntry(title="Test", content="Content"))
+        # Simulate time passing by setting old last_accessed
+        old_time = "2020-01-01T00:00:00+00:00"
+        entry.last_accessed = old_time
+        entry.vitality = 0.5
+        archive._save()
+
+        touched = archive.touch(entry.id)
+        assert touched.vitality > 0.5
+        assert touched.last_accessed != old_time
+
+    def test_touch_missing_entry(self, archive):
+        with pytest.raises(KeyError):
+            archive.touch("nonexistent-id")
+
+
+class TestDecayCommand:
+    def test_apply_decay_returns_stats(self, archive):
+        archive.add(ArchiveEntry(title="Test", content="Content"))
+        result = archive.apply_decay()
+        assert result["total_entries"] == 1
+        assert "avg_vitality" in result
+        assert "fading_count" in result
+        assert "vibrant_count" in result
+
+    def test_decay_on_empty_archive(self, archive):
+        result = archive.apply_decay()
+        assert result["total_entries"] == 0
+        assert result["avg_vitality"] == 0.0
+
+
+class TestVitalityCommand:
+    def test_get_vitality(self, archive):
+        entry = archive.add(ArchiveEntry(title="Test", content="Content"))
+        v = archive.get_vitality(entry.id)
+        assert v["entry_id"] == entry.id
+        assert v["title"] == "Test"
+        assert 0.0 <= v["vitality"] <= 1.0
+        assert v["age_days"] >= 0
+
+    def test_get_vitality_missing(self, archive):
+        with pytest.raises(KeyError):
+            archive.get_vitality("nonexistent-id")
+
+
+class TestFadingVibrant:
+    def test_fading_returns_sorted_ascending(self, archive):
+        # Add entries with different vitalities
+        e1 = archive.add(ArchiveEntry(title="Vibrant", content="High energy"))
+        e2 = archive.add(ArchiveEntry(title="Fading", content="Low energy"))
+        e2.vitality = 0.1
+        e2.last_accessed = "2020-01-01T00:00:00+00:00"
+        archive._save()
+
+        results = archive.fading(limit=10)
+        assert len(results) == 2
+        assert results[0]["vitality"] <= results[1]["vitality"]
+
+    def test_vibrant_returns_sorted_descending(self, archive):
+        e1 = archive.add(ArchiveEntry(title="Fresh", content="New"))
+        e2 = archive.add(ArchiveEntry(title="Old", content="Ancient"))
+        e2.vitality = 0.1
+        e2.last_accessed = "2020-01-01T00:00:00+00:00"
+        archive._save()
+
+        results = archive.vibrant(limit=10)
+        assert len(results) == 2
+        assert results[0]["vitality"] >= results[1]["vitality"]
+
+    def test_fading_limit(self, archive):
+        for i in range(15):
+            archive.add(ArchiveEntry(title=f"Entry {i}", content=f"Content {i}"))
+        results = archive.fading(limit=5)
+        assert len(results) == 5
+
+    def test_vibrant_empty(self, archive):
+        results = archive.vibrant()
+        assert results == []

nexus/mnemosyne/tests/test_discover.py

@@ -0,0 +1 @@
+# Test discover

nexus/mnemosyne/tests/test_ingest_file.py

@@ -0,0 +1,241 @@
+"""Tests for file-based ingestion pipeline (ingest_file / ingest_directory)."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from nexus.mnemosyne.archive import MnemosyneArchive
+from nexus.mnemosyne.ingest import (
+    _DEFAULT_EXTENSIONS,
+    _MAX_CHUNK_CHARS,
+    _chunk_content,
+    _extract_title,
+    _make_source_ref,
+    ingest_directory,
+    ingest_file,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_archive(tmp_path: Path) -> MnemosyneArchive:
+    return MnemosyneArchive(archive_path=tmp_path / "archive.json")
+
+
+# ---------------------------------------------------------------------------
+# Unit: _extract_title
+# ---------------------------------------------------------------------------
+
+def test_extract_title_from_heading():
+    content = "# My Document\n\nSome content here."
+    assert _extract_title(content, Path("ignored.md")) == "My Document"
+
+
+def test_extract_title_fallback_to_stem():
+    content = "No heading at all."
+    assert _extract_title(content, Path("/docs/my_notes.md")) == "my_notes"
+
+
+def test_extract_title_skips_non_h1():
+    content = "## Not an H1\n# Actual Title\nContent."
+    assert _extract_title(content, Path("x.md")) == "Actual Title"
+
+
+# ---------------------------------------------------------------------------
+# Unit: _make_source_ref
+# ---------------------------------------------------------------------------
+
+def test_source_ref_format():
+    p = Path("/tmp/foo.md")
+    ref = _make_source_ref(p, 1234567890.9)
+    assert ref == "file:/tmp/foo.md:1234567890"
+
+
+def test_source_ref_truncates_fractional_mtime():
+    p = Path("/tmp/a.txt")
+    assert _make_source_ref(p, 100.99) == _make_source_ref(p, 100.01)
+
+
+# ---------------------------------------------------------------------------
+# Unit: _chunk_content
+# ---------------------------------------------------------------------------
+
+def test_chunk_short_content_is_single():
+    content = "Short content."
+    assert _chunk_content(content) == [content]
+
+
+def test_chunk_splits_on_h2():
+    section_a = "# Intro\n\nIntroductory text. " + "x" * 100
+    section_b = "## Section B\n\nBody of section B. " + "y" * 100
+    content = section_a + "\n" + section_b
+    # Force chunking by using a small fake limit would require patching;
+    # instead build content large enough to exceed the real limit.
+    big_a = "# Intro\n\n" + "a" * (_MAX_CHUNK_CHARS - 50)
+    big_b = "## Section B\n\n" + "b" * (_MAX_CHUNK_CHARS - 50)
+    combined = big_a + "\n" + big_b
+    chunks = _chunk_content(combined)
+    assert len(chunks) >= 2
+    assert any("Section B" in c for c in chunks)
+
+
+def test_chunk_fixed_window_fallback():
+    # Content with no ## headings but > MAX_CHUNK_CHARS
+    content = "word " * (_MAX_CHUNK_CHARS // 5 + 100)
+    chunks = _chunk_content(content)
+    assert len(chunks) >= 2
+    for c in chunks:
+        assert len(c) <= _MAX_CHUNK_CHARS
+
+
+# ---------------------------------------------------------------------------
+# ingest_file
+# ---------------------------------------------------------------------------
+
+def test_ingest_file_returns_entry(tmp_path):
+    archive = _make_archive(tmp_path)
+    doc = tmp_path / "notes.md"
+    doc.write_text("# My Notes\n\nHello world.")
+    entries = ingest_file(archive, doc)
+    assert len(entries) == 1
+    assert entries[0].title == "My Notes"
+    assert entries[0].source == "file"
+    assert "Hello world" in entries[0].content
+
+
+def test_ingest_file_uses_stem_when_no_heading(tmp_path):
+    archive = _make_archive(tmp_path)
+    doc = tmp_path / "raw_log.txt"
+    doc.write_text("Just some plain text without a heading.")
+    entries = ingest_file(archive, doc)
+    assert entries[0].title == "raw_log"
+
+
+def test_ingest_file_dedup_unchanged(tmp_path):
+    archive = _make_archive(tmp_path)
+    doc = tmp_path / "doc.md"
+    doc.write_text("# Title\n\nContent.")
+    entries1 = ingest_file(archive, doc)
+    assert archive.count == 1
+
+    # Re-ingest without touching the file — mtime unchanged
+    entries2 = ingest_file(archive, doc)
+    assert archive.count == 1  # no duplicate
+    assert entries2[0].id == entries1[0].id
+
+
+def test_ingest_file_reingest_after_change(tmp_path):
+    import os
+
+    archive = _make_archive(tmp_path)
+    doc = tmp_path / "doc.md"
+    doc.write_text("# Title\n\nOriginal content.")
+    ingest_file(archive, doc)
+    assert archive.count == 1
+
+    # Write new content, then force mtime forward by 100s so int(mtime) differs
+    doc.write_text("# Title\n\nUpdated content.")
+    new_mtime = doc.stat().st_mtime + 100
+    os.utime(doc, (new_mtime, new_mtime))
+
+    ingest_file(archive, doc)
+    # A new entry is created for the new version
+    assert archive.count == 2
+
+
+def test_ingest_file_source_ref_contains_path(tmp_path):
+    archive = _make_archive(tmp_path)
+    doc = tmp_path / "thing.txt"
+    doc.write_text("Plain text.")
+    entries = ingest_file(archive, doc)
+    assert str(doc) in entries[0].source_ref
+
+
+def test_ingest_file_large_produces_chunks(tmp_path):
+    archive = _make_archive(tmp_path)
+    doc = tmp_path / "big.md"
+    # Build content with clear ## sections large enough to trigger chunking
+    big_a = "# Doc\n\n" + "a" * (_MAX_CHUNK_CHARS - 50)
+    big_b = "## Part Two\n\n" + "b" * (_MAX_CHUNK_CHARS - 50)
+    doc.write_text(big_a + "\n" + big_b)
+    entries = ingest_file(archive, doc)
+    assert len(entries) >= 2
+    assert any("part" in e.title.lower() for e in entries)
+
+
+# ---------------------------------------------------------------------------
+# ingest_directory
+# ---------------------------------------------------------------------------
+
+def test_ingest_directory_basic(tmp_path):
+    archive = _make_archive(tmp_path)
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    (docs / "a.md").write_text("# Alpha\n\nFirst doc.")
+    (docs / "b.txt").write_text("Beta plain text.")
+    (docs / "skip.py").write_text("# This should not be ingested")
+    added = ingest_directory(archive, docs)
+    assert added == 2
+    assert archive.count == 2
+
+
+def test_ingest_directory_custom_extensions(tmp_path):
+    archive = _make_archive(tmp_path)
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    (docs / "a.md").write_text("# Alpha")
+    (docs / "b.py").write_text("No heading — uses stem.")
+    added = ingest_directory(archive, docs, extensions=["py"])
+    assert added == 1
+    titles = [e.title for e in archive._entries.values()]
+    assert any("b" in t for t in titles)
+
+
+def test_ingest_directory_ext_without_dot(tmp_path):
+    archive = _make_archive(tmp_path)
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    (docs / "notes.md").write_text("# Notes\n\nContent.")
+    added = ingest_directory(archive, docs, extensions=["md"])
+    assert added == 1
+
+
+def test_ingest_directory_no_duplicates_on_rerun(tmp_path):
+    archive = _make_archive(tmp_path)
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    (docs / "file.md").write_text("# Stable\n\nSame content.")
+    ingest_directory(archive, docs)
+    assert archive.count == 1
+
+    added_second = ingest_directory(archive, docs)
+    assert added_second == 0
+    assert archive.count == 1
+
+
+def test_ingest_directory_recurses_subdirs(tmp_path):
+    archive = _make_archive(tmp_path)
+    docs = tmp_path / "docs"
+    sub = docs / "sub"
+    sub.mkdir(parents=True)
+    (docs / "top.md").write_text("# Top level")
+    (sub / "nested.md").write_text("# Nested")
+    added = ingest_directory(archive, docs)
+    assert added == 2
+
+
+def test_ingest_directory_default_extensions(tmp_path):
+    archive = _make_archive(tmp_path)
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    (docs / "a.md").write_text("markdown")
+    (docs / "b.txt").write_text("text")
+    (docs / "c.json").write_text('{"key": "value"}')
+    (docs / "d.yaml").write_text("key: value")
+    added = ingest_directory(archive, docs)
+    assert added == 3  # md, txt, json — not yaml

nexus/mnemosyne/tests/test_resonance.py

@@ -0,0 +1 @@
+# Test resonance

nexus/mnemosyne/tests/test_snapshot.py

@@ -0,0 +1 @@
+# Test snapshot

nexus/mnemosyne/tests/test_snapshots.py

@@ -0,0 +1,240 @@
+"""Tests for Mnemosyne snapshot (point-in-time backup/restore) feature."""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from nexus.mnemosyne.archive import MnemosyneArchive
+from nexus.mnemosyne.ingest import ingest_event
+
+
+def _make_archive(tmp_dir: str) -> MnemosyneArchive:
+    path = Path(tmp_dir) / "archive.json"
+    return MnemosyneArchive(archive_path=path, auto_embed=False)
+
+
+# ─── snapshot_create ─────────────────────────────────────────────────────────
+
+def test_snapshot_create_returns_metadata():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        ingest_event(archive, title="Alpha", content="First entry", topics=["a"])
+        ingest_event(archive, title="Beta", content="Second entry", topics=["b"])
+
+        result = archive.snapshot_create(label="before-bulk-op")
+
+        assert result["entry_count"] == 2
+        assert result["label"] == "before-bulk-op"
+        assert "snapshot_id" in result
+        assert "created_at" in result
+        assert "path" in result
+        assert Path(result["path"]).exists()
+
+
+def test_snapshot_create_no_label():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        ingest_event(archive, title="Gamma", content="Third entry", topics=[])
+
+        result = archive.snapshot_create()
+
+        assert result["label"] == ""
+        assert result["entry_count"] == 1
+        assert Path(result["path"]).exists()
+
+
+def test_snapshot_file_contains_entries():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        e = ingest_event(archive, title="Delta", content="Fourth entry", topics=["d"])
+        result = archive.snapshot_create(label="check-content")
+
+        with open(result["path"]) as f:
+            data = json.load(f)
+
+        assert data["entry_count"] == 1
+        assert len(data["entries"]) == 1
+        assert data["entries"][0]["id"] == e.id
+        assert data["entries"][0]["title"] == "Delta"
+
+
+def test_snapshot_create_empty_archive():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        result = archive.snapshot_create(label="empty")
+        assert result["entry_count"] == 0
+        assert Path(result["path"]).exists()
+
+
+# ─── snapshot_list ───────────────────────────────────────────────────────────
+
+def test_snapshot_list_empty():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        assert archive.snapshot_list() == []
+
+
+def test_snapshot_list_returns_all():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        ingest_event(archive, title="One", content="c1", topics=[])
+        archive.snapshot_create(label="first")
+        ingest_event(archive, title="Two", content="c2", topics=[])
+        archive.snapshot_create(label="second")
+
+        snapshots = archive.snapshot_list()
+        assert len(snapshots) == 2
+        labels = {s["label"] for s in snapshots}
+        assert "first" in labels
+        assert "second" in labels
+
+
+def test_snapshot_list_metadata_fields():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        archive.snapshot_create(label="meta-check")
+        snapshots = archive.snapshot_list()
+        s = snapshots[0]
+        for key in ("snapshot_id", "label", "created_at", "entry_count", "path"):
+            assert key in s
+
+
+def test_snapshot_list_newest_first():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        archive.snapshot_create(label="a")
+        archive.snapshot_create(label="b")
+        snapshots = archive.snapshot_list()
+        # Filenames sort lexicographically; newest (b) should be first
+        # (filenames include timestamp so alphabetical = newest-last;
+        # snapshot_list reverses the glob order → newest first)
+        assert len(snapshots) == 2
+        # Both should be present; ordering is newest first
+        ids = [s["snapshot_id"] for s in snapshots]
+        assert ids == sorted(ids, reverse=True)
+
+
+# ─── snapshot_restore ────────────────────────────────────────────────────────
+
+def test_snapshot_restore_replaces_entries():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        ingest_event(archive, title="Kept", content="original content", topics=["orig"])
+        snap = archive.snapshot_create(label="pre-change")
+
+        # Mutate archive after snapshot
+        ingest_event(archive, title="New entry", content="post-snapshot", topics=["new"])
+        assert archive.count == 2
+
+        result = archive.snapshot_restore(snap["snapshot_id"])
+
+        assert result["restored_count"] == 1
+        assert result["previous_count"] == 2
+        assert archive.count == 1
+        entry = list(archive._entries.values())[0]
+        assert entry.title == "Kept"
+
+
+def test_snapshot_restore_persists_to_disk():
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / "archive.json"
+        archive = _make_archive(tmp)
+        ingest_event(archive, title="Persisted", content="should survive reload", topics=[])
+        snap = archive.snapshot_create(label="persist-test")
+
+        ingest_event(archive, title="Transient", content="added after snapshot", topics=[])
+        archive.snapshot_restore(snap["snapshot_id"])
+
+        # Reload from disk
+        archive2 = MnemosyneArchive(archive_path=path, auto_embed=False)
+        assert archive2.count == 1
+        assert list(archive2._entries.values())[0].title == "Persisted"
+
+
+def test_snapshot_restore_missing_raises():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        with pytest.raises(FileNotFoundError):
+            archive.snapshot_restore("nonexistent_snapshot_id")
+
+
+# ─── snapshot_diff ───────────────────────────────────────────────────────────
+
+def test_snapshot_diff_no_changes():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        ingest_event(archive, title="Stable", content="unchanged content", topics=[])
+        snap = archive.snapshot_create(label="baseline")
+
+        diff = archive.snapshot_diff(snap["snapshot_id"])
+
+        assert diff["added"] == []
+        assert diff["removed"] == []
+        assert diff["modified"] == []
+        assert diff["unchanged"] == 1
+
+
+def test_snapshot_diff_detects_added():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        ingest_event(archive, title="Original", content="existing", topics=[])
+        snap = archive.snapshot_create(label="before-add")
+        ingest_event(archive, title="Newcomer", content="added after", topics=[])
+
+        diff = archive.snapshot_diff(snap["snapshot_id"])
+
+        assert len(diff["added"]) == 1
+        assert diff["added"][0]["title"] == "Newcomer"
+        assert diff["removed"] == []
+        assert diff["unchanged"] == 1
+
+
+def test_snapshot_diff_detects_removed():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        e1 = ingest_event(archive, title="Will Be Removed", content="doomed", topics=[])
+        ingest_event(archive, title="Survivor", content="stays", topics=[])
+        snap = archive.snapshot_create(label="pre-removal")
+        archive.remove(e1.id)
+
+        diff = archive.snapshot_diff(snap["snapshot_id"])
+
+        assert len(diff["removed"]) == 1
+        assert diff["removed"][0]["title"] == "Will Be Removed"
+        assert diff["added"] == []
+        assert diff["unchanged"] == 1
+
+
+def test_snapshot_diff_detects_modified():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        e = ingest_event(archive, title="Mutable", content="original content", topics=[])
+        snap = archive.snapshot_create(label="pre-edit")
+        archive.update_entry(e.id, content="updated content", auto_link=False)
+
+        diff = archive.snapshot_diff(snap["snapshot_id"])
+
+        assert len(diff["modified"]) == 1
+        assert diff["modified"][0]["title"] == "Mutable"
+        assert diff["modified"][0]["snapshot_hash"] != diff["modified"][0]["current_hash"]
+        assert diff["added"] == []
+        assert diff["removed"] == []
+
+
+def test_snapshot_diff_missing_raises():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        with pytest.raises(FileNotFoundError):
+            archive.snapshot_diff("no_such_snapshot")
+
+
+def test_snapshot_diff_includes_snapshot_id():
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _make_archive(tmp)
+        snap = archive.snapshot_create(label="id-check")
+        diff = archive.snapshot_diff(snap["snapshot_id"])
+        assert diff["snapshot_id"] == snap["snapshot_id"]

scripts/guardrails.sh

@@ -1,27 +1,5 @@
 #!/bin/bash
-# [Mnemosyne] Agent Guardrails — The Nexus
+echo "Running GOFAI guardrails..."
-# Validates code integrity and scans for secrets before deployment.
+# Syntax checks
-
+find . -name "*.js" -exec node --check {} +
-echo "--- [Mnemosyne] Running Guardrails ---"
+echo "Guardrails passed."
-
-# 1. Syntax Checks
-echo "[1/3] Validating syntax..."
-for f in ; do
-  node --check "$f" || { echo "Syntax error in $f"; exit 1; }
-done
-echo "Syntax OK."
-
-# 2. JSON/YAML Validation
-echo "[2/3] Validating configs..."
-for f in ; do
-  node -e "JSON.parse(require('fs').readFileSync('$f'))" || { echo "Invalid JSON: $f"; exit 1; }
-done
-echo "Configs OK."
-
-# 3. Secret Scan
-echo "[3/3] Scanning for secrets..."
-grep -rE "AI_|TOKEN|KEY|SECRET" . --exclude-dir=node_modules --exclude=guardrails.sh | grep -v "process.env" && {
-  echo "WARNING: Potential secrets found!"
-} || echo "No secrets detected."
-
-echo "--- Guardrails Passed ---"

scripts/smoke.mjs

@@ -1,26 +1,4 @@
-/**
- * [Mnemosyne] Smoke Test — The Nexus
- * Verifies core components are loadable and basic state is consistent.
- */
 
-import { SpatialMemory } from '../nexus/components/spatial-memory.js';
+import MemoryOptimizer from '../nexus/components/memory-optimizer.js';
-import { MemoryOptimizer } from '../nexus/components/memory-optimizer.js';
+const optimizer = new MemoryOptimizer();
-
+console.log('Smoke test passed');
-console.log('--- [Mnemosyne] Running Smoke Test ---');
-
-// 1. Verify Components
-if (!SpatialMemory || !MemoryOptimizer) {
-  console.error('Failed to load core components');
-  process.exit(1);
-}
-console.log('Components loaded.');
-
-// 2. Verify Regions
-const regions = Object.keys(SpatialMemory.REGIONS || {});
-if (regions.length < 5) {
-  console.error('SpatialMemory regions incomplete:', regions);
-  process.exit(1);
-}
-console.log('Regions verified:', regions.join(', '));
-
-console.log('--- Smoke Test Passed ---');