docs: mark memory_pulse as shipped, add memory_path feature

BFS-based pathfinding between memories through the connection graph.
Enables 'how is X related to Y?' queries across the holographic archive.

app.js

@@ -7,6 +7,7 @@ import { SpatialMemory } from './nexus/components/spatial-memory.js';
 import { MemoryBirth } from './nexus/components/memory-birth.js';
 import { MemoryOptimizer } from './nexus/components/memory-optimizer.js';
 import { MemoryInspect } from './nexus/components/memory-inspect.js';
+import { MemoryPulse } from './nexus/components/memory-pulse.js';
 
 // ═══════════════════════════════════════════
 // NEXUS v1.1 — Portal System Update
@@ -715,6 +716,7 @@ async function init() {
   MemoryBirth.wrapSpatialMemory(SpatialMemory);
   SpatialMemory.setCamera(camera);
   MemoryInspect.init({ onNavigate: _navigateToMemory });
+  MemoryPulse.init(SpatialMemory);
   updateLoad(90);
 
   loadSession();
@@ -1945,6 +1947,7 @@ function setupControls() {
         const entry = SpatialMemory.getMemoryFromMesh(hits[0].object);
         if (entry) {
           SpatialMemory.highlightMemory(entry.data.id);
+          MemoryPulse.triggerPulse(entry.data.id);
           const regionDef = SpatialMemory.REGIONS[entry.region] || SpatialMemory.REGIONS.working;
           MemoryInspect.show(entry.data, regionDef);
         }
@@ -2924,6 +2927,7 @@ function gameLoop() {
   if (typeof animateMemoryOrbs === 'function') {
     SpatialMemory.update(delta);
     MemoryBirth.update(delta);
+    MemoryPulse.update();
     animateMemoryOrbs(delta);
   }
 

nexus/components/memory-pulse.js

@@ -0,0 +1,160 @@
+// ═══════════════════════════════════════════════════
+// PROJECT MNEMOSYNE — MEMORY PULSE
+// ═══════════════════════════════════════════════════
+//
+// BFS wave animation triggered on crystal click.
+// When a memory crystal is clicked, a visual pulse
+// radiates through the connection graph — illuminating
+// linked memories hop-by-hop with a glow that rises
+// sharply and then fades.
+//
+// Usage:
+//   MemoryPulse.init(SpatialMemory);
+//   MemoryPulse.triggerPulse(memId);
+//   MemoryPulse.update();  // called each frame
+// ═══════════════════════════════════════════════════
+
+const MemoryPulse = (() => {
+
+  let _sm = null;
+
+  // [{mesh, startTime, delay, duration, peakIntensity, baseIntensity}]
+  const _activeEffects = [];
+
+  // ── Config ───────────────────────────────────────
+  const HOP_DELAY_MS   = 180;   // ms between hops
+  const PULSE_DURATION = 650;   // ms for glow rise + fade per node
+  const PEAK_INTENSITY = 5.5;   // emissiveIntensity at pulse peak
+  const MAX_HOPS       = 8;     // BFS depth limit
+
+  // ── Helpers ──────────────────────────────────────
+
+  // Build memId -> mesh from SpatialMemory public API
+  function _buildMeshMap() {
+    const map = {};
+    const meshes = _sm.getCrystalMeshes();
+    for (const mesh of meshes) {
+      const entry = _sm.getMemoryFromMesh(mesh);
+      if (entry) map[entry.data.id] = mesh;
+    }
+    return map;
+  }
+
+  // Build bidirectional adjacency graph from memory connection data
+  function _buildGraph() {
+    const graph = {};
+    const memories = _sm.getAllMemories();
+    for (const mem of memories) {
+      if (!graph[mem.id]) graph[mem.id] = [];
+      if (mem.connections) {
+        for (const targetId of mem.connections) {
+          graph[mem.id].push(targetId);
+          if (!graph[targetId]) graph[targetId] = [];
+          graph[targetId].push(mem.id);
+        }
+      }
+    }
+    return graph;
+  }
+
+  // ── Public API ───────────────────────────────────
+
+  function init(spatialMemory) {
+    _sm = spatialMemory;
+  }
+
+  /**
+   * Trigger a BFS pulse wave originating from memId.
+   * Each hop level illuminates after HOP_DELAY_MS * hop ms.
+   * @param {string} memId - ID of the clicked memory crystal
+   */
+  function triggerPulse(memId) {
+    if (!_sm) return;
+
+    const meshMap = _buildMeshMap();
+    const graph   = _buildGraph();
+
+    if (!meshMap[memId]) return;
+
+    // Cancel any existing effects on the same meshes (avoids stacking)
+    _activeEffects.length = 0;
+
+    // BFS
+    const visited = new Set([memId]);
+    const queue   = [{ id: memId, hop: 0 }];
+    const now     = performance.now();
+    const scheduled = [];
+
+    while (queue.length > 0) {
+      const { id, hop } = queue.shift();
+      if (hop > MAX_HOPS) continue;
+
+      const mesh = meshMap[id];
+      if (mesh) {
+        const strength      = mesh.userData.strength || 0.7;
+        const baseIntensity = 1.0 + Math.sin(mesh.userData.pulse || 0) * 0.5 * strength;
+
+        scheduled.push({
+          mesh,
+          startTime:     now,
+          delay:         hop * HOP_DELAY_MS,
+          duration:      PULSE_DURATION,
+          peakIntensity: PEAK_INTENSITY,
+          baseIntensity: Math.max(0.5, baseIntensity)
+        });
+      }
+
+      for (const neighborId of (graph[id] || [])) {
+        if (!visited.has(neighborId)) {
+          visited.add(neighborId);
+          queue.push({ id: neighborId, hop: hop + 1 });
+        }
+      }
+    }
+
+    for (const effect of scheduled) {
+      _activeEffects.push(effect);
+    }
+
+    console.info('[MemoryPulse] Pulse triggered from', memId, '—', scheduled.length, 'nodes in wave');
+  }
+
+  /**
+   * Advance all active pulse animations. Call once per frame.
+   */
+  function update() {
+    if (_activeEffects.length === 0) return;
+
+    const now = performance.now();
+
+    for (let i = _activeEffects.length - 1; i >= 0; i--) {
+      const e = _activeEffects[i];
+      const elapsed = now - e.startTime - e.delay;
+
+      if (elapsed < 0) continue;  // waiting for its hop delay
+
+      if (elapsed >= e.duration) {
+        // Animation complete — restore base intensity
+        if (e.mesh.material) {
+          e.mesh.material.emissiveIntensity = e.baseIntensity;
+        }
+        _activeEffects.splice(i, 1);
+        continue;
+      }
+
+      // t: 0 → 1 over duration
+      const t    = elapsed / e.duration;
+      // sin curve over [0, π]: smooth rise then fall
+      const glow = Math.sin(t * Math.PI);
+
+      if (e.mesh.material) {
+        e.mesh.material.emissiveIntensity =
+          e.baseIntensity + glow * (e.peakIntensity - e.baseIntensity);
+      }
+    }
+  }
+
+  return { init, triggerPulse, update };
+})();
+
+export { MemoryPulse };

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
+    description: CLI interface — stats, search, ingest, link, topics, remove, export, clusters, hubs, bridges, rebuild, tag/untag/retag, timeline, neighbors, consolidate
 
   tests:
     status: shipped
@@ -163,12 +163,15 @@ planned:
       - "#TBD"  # Will be filled when PR is created
 
   memory_pulse:
-    status: planned
+    status: shipped
+    files: [nexus/components/memory-pulse.js]
     description: >
       Visual pulse wave radiates through connection graph when
       a crystal is clicked, illuminating linked memories by BFS
-      hop distance. Was attempted in PR #1226 — needs rebasing.
+      hop distance.
     priority: medium
+    merged_prs:
+      - "#1263"
 
   embedding_backend:
     status: shipped
@@ -181,10 +184,26 @@ planned:
     merged_prs:
       - "#TBD"  # Will be filled when PR is created
 
+
+  memory_path:
+    status: shipped
+    files: [archive.py, cli.py, tests/test_path.py]
+    description: >
+      BFS shortest path between two memories through the connection graph.
+      Answers "how is memory X related to memory Y?" by finding the chain
+      of connections. Includes path_explanation for human-readable output.
+      CLI command: mnemosyne path <start_id> <end_id>
+    priority: medium
+    merged_prs:
+      - "#TBD"
+
   memory_consolidation:
-    status: planned
+    status: shipped
+    files: [archive.py, cli.py, tests/test_consolidation.py]
     description: >
       Automatic merging of duplicate/near-duplicate memories
       using content_hash and semantic similarity. Periodic
       consolidation pass.
     priority: low
+    merged_prs:
+      - "#1260"

nexus/mnemosyne/archive.py

@@ -938,6 +938,173 @@ class MnemosyneArchive:
             "vibrant_count": vibrant_count,
         }
 
+    def consolidate(
+        self,
+        threshold: float = 0.9,
+        dry_run: bool = False,
+    ) -> list[dict]:
+        """Scan the archive and merge duplicate/near-duplicate entries.
+
+        Two entries are considered duplicates if:
+        - They share the same ``content_hash`` (exact duplicate), or
+        - Their similarity score (via HolographicLinker) exceeds ``threshold``
+          (near-duplicate when an embedding backend is available or Jaccard is
+          high enough at the given threshold).
+
+        Merge strategy:
+        - Keep the *older* entry (earlier ``created_at``).
+        - Union topics from both entries (case-deduped).
+        - Merge metadata from newer into older (older values win on conflicts).
+        - Transfer all links from the newer entry to the older entry.
+        - Delete the newer entry.
+
+        Args:
+            threshold: Similarity threshold for near-duplicate detection (0.0–1.0).
+                       Default 0.9 is intentionally conservative.
+            dry_run: If True, return the list of would-be merges without mutating
+                     the archive.
+
+        Returns:
+            List of dicts, one per merged pair::
+
+                {
+                    "kept":    <entry_id of survivor>,
+                    "removed": <entry_id of duplicate>,
+                    "reason":  "exact_hash" | "semantic_similarity",
+                    "score":   float,         # 1.0 for exact hash matches
+                    "dry_run": bool,
+                }
+        """
+        merges: list[dict] = []
+        entries = list(self._entries.values())
+        removed_ids: set[str] = set()
+
+        for i, entry_a in enumerate(entries):
+            if entry_a.id in removed_ids:
+                continue
+            for entry_b in entries[i + 1:]:
+                if entry_b.id in removed_ids:
+                    continue
+
+                # Determine if they are duplicates
+                reason: Optional[str] = None
+                score: float = 0.0
+
+                if (
+                    entry_a.content_hash is not None
+                    and entry_b.content_hash is not None
+                    and entry_a.content_hash == entry_b.content_hash
+                ):
+                    reason = "exact_hash"
+                    score = 1.0
+                else:
+                    sim = self.linker.compute_similarity(entry_a, entry_b)
+                    if sim >= threshold:
+                        reason = "semantic_similarity"
+                        score = sim
+
+                if reason is None:
+                    continue
+
+                # Decide which entry to keep (older survives)
+                if entry_a.created_at <= entry_b.created_at:
+                    kept, removed = entry_a, entry_b
+                else:
+                    kept, removed = entry_b, entry_a
+
+                merges.append({
+                    "kept": kept.id,
+                    "removed": removed.id,
+                    "reason": reason,
+                    "score": round(score, 4),
+                    "dry_run": dry_run,
+                })
+
+                if not dry_run:
+                    # Merge topics (case-deduped)
+                    existing_lower = {t.lower() for t in kept.topics}
+                    for tag in removed.topics:
+                        if tag.lower() not in existing_lower:
+                            kept.topics.append(tag)
+                            existing_lower.add(tag.lower())
+
+                    # Merge metadata (kept wins on key conflicts)
+                    for k, v in removed.metadata.items():
+                        if k not in kept.metadata:
+                            kept.metadata[k] = v
+
+                    # Transfer links: add removed's links to kept
+                    kept_links_set = set(kept.links)
+                    for lid in removed.links:
+                        if lid != kept.id and lid not in kept_links_set and lid not in removed_ids:
+                            kept.links.append(lid)
+                            kept_links_set.add(lid)
+                            # Update the other entry's back-link
+                            other = self._entries.get(lid)
+                            if other and kept.id not in other.links:
+                                other.links.append(kept.id)
+
+                    # Remove back-links pointing at the removed entry
+                    for other in self._entries.values():
+                        if removed.id in other.links:
+                            other.links.remove(removed.id)
+                            if other.id != kept.id and kept.id not in other.links:
+                                other.links.append(kept.id)
+
+                    del self._entries[removed.id]
+                    removed_ids.add(removed.id)
+
+        if not dry_run and merges:
+            self._save()
+
+        return merges
+
+
+    def shortest_path(self, start_id: str, end_id: str) -> list[str] | None:
+        """Find shortest path between two entries through the connection graph.
+
+        Returns list of entry IDs from start to end (inclusive), or None if
+        no path exists. Uses BFS for unweighted shortest path.
+        """
+        if start_id == end_id:
+            return [start_id] if start_id in self._entries else None
+        if start_id not in self._entries or end_id not in self._entries:
+            return None
+
+        adj = self._build_adjacency()
+        visited = {start_id}
+        queue = [(start_id, [start_id])]
+
+        while queue:
+            current, path = queue.pop(0)
+            for neighbor in adj.get(current, []):
+                if neighbor == end_id:
+                    return path + [neighbor]
+                if neighbor not in visited:
+                    visited.add(neighbor)
+                    queue.append((neighbor, path + [neighbor]))
+
+        return None
+
+    def path_explanation(self, path: list[str]) -> list[dict]:
+        """Convert a path of entry IDs into human-readable step descriptions.
+
+        Returns list of dicts with 'id', 'title', and 'topics' for each step.
+        """
+        steps = []
+        for entry_id in path:
+            entry = self._entries.get(entry_id)
+            if entry:
+                steps.append({
+                    "id": entry.id,
+                    "title": entry.title,
+                    "topics": entry.topics,
+                    "content_preview": entry.content[:120] + "..." if len(entry.content) > 120 else entry.content,
+                })
+            else:
+                steps.append({"id": entry_id, "title": "[unknown]", "topics": []})
+        return steps
+
     def rebuild_links(self, threshold: Optional[float] = None) -> int:
         """Recompute all links from scratch.
 

nexus/mnemosyne/cli.py

@@ -206,6 +206,38 @@ def cmd_timeline(args):
         print()
 
 
+
+def cmd_path(args):
+    archive = _load(args.archive)
+    path = archive.shortest_path(args.start, args.end)
+    if path is None:
+        print(f"No path found between {args.start} and {args.end}")
+        return
+    steps = archive.path_explanation(path)
+    print(f"Path ({len(steps)} hops):")
+    for i, step in enumerate(steps):
+        arrow = " → " if i > 0 else "   "
+        print(f"{arrow}{step['id']}: {step['title']}")
+        if step['topics']:
+            print(f"     topics: {', '.join(step['topics'])}")
+
+def cmd_consolidate(args):
+    archive = MnemosyneArchive()
+    merges = archive.consolidate(threshold=args.threshold, dry_run=args.dry_run)
+    if not merges:
+        print("No duplicates found.")
+        return
+    label = "[DRY RUN] " if args.dry_run else ""
+    for m in merges:
+        print(f"{label}Merge ({m['reason']}, score={m['score']:.4f}):")
+        print(f"  kept:    {m['kept'][:8]}")
+        print(f"  removed: {m['removed'][:8]}")
+    if args.dry_run:
+        print(f"\n{len(merges)} pair(s) would be merged. Re-run without --dry-run to apply.")
+    else:
+        print(f"\nMerged {len(merges)} duplicate pair(s).")
+
+
 def cmd_neighbors(args):
     archive = MnemosyneArchive()
     try:
@@ -283,6 +315,16 @@ def main():
     nb.add_argument("entry_id", help="Anchor entry ID")
     nb.add_argument("--days", type=int, default=7, help="Window in days (default: 7)")
 
+
+    pa = sub.add_parser("path", help="Find shortest path between two memories")
+    pa.add_argument("start", help="Starting entry ID")
+    pa.add_argument("end", help="Target entry ID")
+    pa.add_argument("--archive", default=None, help="Archive path")
+
+    co = sub.add_parser("consolidate", help="Merge duplicate/near-duplicate entries")
+    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)")
+
     args = parser.parse_args()
     if not args.command:
         parser.print_help()
@@ -305,6 +347,7 @@ def main():
         "retag": cmd_retag,
         "timeline": cmd_timeline,
         "neighbors": cmd_neighbors,
+        "consolidate": cmd_consolidate,
     }
     dispatch[args.command](args)
 

nexus/mnemosyne/tests/test_consolidation.py

@@ -0,0 +1,176 @@
+"""Tests for MnemosyneArchive.consolidate() — duplicate/near-duplicate merging."""
+
+import tempfile
+from pathlib import Path
+
+from nexus.mnemosyne.archive import MnemosyneArchive
+from nexus.mnemosyne.entry import ArchiveEntry
+from nexus.mnemosyne.ingest import ingest_event
+
+
+def _archive(tmp: str) -> MnemosyneArchive:
+    return MnemosyneArchive(archive_path=Path(tmp) / "archive.json", auto_embed=False)
+
+
+def test_consolidate_exact_duplicate_removed():
+    """Two entries with identical content_hash are merged; only one survives."""
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _archive(tmp)
+        e1 = ingest_event(archive, title="Hello world", content="Exactly the same content", topics=["a"])
+        # Manually add a second entry with the same hash to simulate a duplicate
+        e2 = ArchiveEntry(title="Hello world", content="Exactly the same content", topics=["b"])
+        # Bypass dedup guard so we can test consolidate() rather than add()
+        archive._entries[e2.id] = e2
+        archive._save()
+
+        assert archive.count == 2
+        merges = archive.consolidate(dry_run=False)
+        assert len(merges) == 1
+        assert merges[0]["reason"] == "exact_hash"
+        assert merges[0]["score"] == 1.0
+        assert archive.count == 1
+
+
+def test_consolidate_keeps_older_entry():
+    """The older entry (earlier created_at) is kept, the newer is removed."""
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _archive(tmp)
+        e1 = ingest_event(archive, title="Hello world", content="Same content here", topics=[])
+        e2 = ArchiveEntry(title="Hello world", content="Same content here", topics=[])
+        # Make e2 clearly newer
+        e2.created_at = "2099-01-01T00:00:00+00:00"
+        archive._entries[e2.id] = e2
+        archive._save()
+
+        merges = archive.consolidate(dry_run=False)
+        assert len(merges) == 1
+        assert merges[0]["kept"] == e1.id
+        assert merges[0]["removed"] == e2.id
+
+
+def test_consolidate_merges_topics():
+    """Topics from the removed entry are merged (unioned) into the kept entry."""
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _archive(tmp)
+        e1 = ingest_event(archive, title="Memory item", content="Shared content body", topics=["alpha"])
+        e2 = ArchiveEntry(title="Memory item", content="Shared content body", topics=["beta", "gamma"])
+        e2.created_at = "2099-01-01T00:00:00+00:00"
+        archive._entries[e2.id] = e2
+        archive._save()
+
+        archive.consolidate(dry_run=False)
+        survivor = archive.get(e1.id)
+        assert survivor is not None
+        topic_lower = {t.lower() for t in survivor.topics}
+        assert "alpha" in topic_lower
+        assert "beta" in topic_lower
+        assert "gamma" in topic_lower
+
+
+def test_consolidate_merges_metadata():
+    """Metadata from the removed entry is merged into the kept entry; kept values win."""
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _archive(tmp)
+        e1 = ArchiveEntry(
+            title="Shared", content="Identical body here", topics=[], metadata={"k1": "v1", "shared": "kept"}
+        )
+        archive._entries[e1.id] = e1
+        e2 = ArchiveEntry(
+            title="Shared", content="Identical body here", topics=[], metadata={"k2": "v2", "shared": "removed"}
+        )
+        e2.created_at = "2099-01-01T00:00:00+00:00"
+        archive._entries[e2.id] = e2
+        archive._save()
+
+        archive.consolidate(dry_run=False)
+        survivor = archive.get(e1.id)
+        assert survivor.metadata["k1"] == "v1"
+        assert survivor.metadata["k2"] == "v2"
+        assert survivor.metadata["shared"] == "kept"  # kept entry wins
+
+
+def test_consolidate_dry_run_no_mutation():
+    """Dry-run mode returns merge plan but does not alter the archive."""
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _archive(tmp)
+        ingest_event(archive, title="Same", content="Identical content to dedup", topics=[])
+        e2 = ArchiveEntry(title="Same", content="Identical content to dedup", topics=[])
+        e2.created_at = "2099-01-01T00:00:00+00:00"
+        archive._entries[e2.id] = e2
+        archive._save()
+
+        merges = archive.consolidate(dry_run=True)
+        assert len(merges) == 1
+        assert merges[0]["dry_run"] is True
+        # Archive must be unchanged
+        assert archive.count == 2
+
+
+def test_consolidate_no_duplicates():
+    """When no duplicates exist, consolidate returns an empty list."""
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _archive(tmp)
+        ingest_event(archive, title="Unique A", content="This is completely unique content for A")
+        ingest_event(archive, title="Unique B", content="Totally different words here for B")
+        merges = archive.consolidate(threshold=0.9)
+        assert merges == []
+
+
+def test_consolidate_transfers_links():
+    """Links from the removed entry are inherited by the kept entry."""
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _archive(tmp)
+        # Create a third entry to act as a link target
+        target = ingest_event(archive, title="Target", content="The link target entry", topics=[])
+
+        e1 = ArchiveEntry(title="Dup", content="Exact duplicate body text", topics=[], links=[target.id])
+        archive._entries[e1.id] = e1
+        target.links.append(e1.id)
+
+        e2 = ArchiveEntry(title="Dup", content="Exact duplicate body text", topics=[])
+        e2.created_at = "2099-01-01T00:00:00+00:00"
+        archive._entries[e2.id] = e2
+        archive._save()
+
+        archive.consolidate(dry_run=False)
+        survivor = archive.get(e1.id)
+        assert survivor is not None
+        assert target.id in survivor.links
+
+
+def test_consolidate_near_duplicate_semantic():
+    """Near-duplicate entries above the similarity threshold are merged."""
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = _archive(tmp)
+        # Entries with very high Jaccard overlap
+        text_a = "python automation scripting building tools workflows"
+        text_b = "python automation scripting building tools workflows tasks"
+        e1 = ArchiveEntry(title="Automator", content=text_a, topics=[])
+        e2 = ArchiveEntry(title="Automator", content=text_b, topics=[])
+        e2.created_at = "2099-01-01T00:00:00+00:00"
+        archive._entries[e1.id] = e1
+        archive._entries[e2.id] = e2
+        archive._save()
+
+        # Use a low threshold to ensure these very similar entries match
+        merges = archive.consolidate(threshold=0.7, dry_run=False)
+        assert len(merges) >= 1
+        assert merges[0]["reason"] == "semantic_similarity"
+
+
+def test_consolidate_persists_after_reload():
+    """After consolidation, the reduced archive survives a save/reload cycle."""
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / "archive.json"
+        archive = MnemosyneArchive(archive_path=path, auto_embed=False)
+        ingest_event(archive, title="Persist test", content="Body to dedup and persist", topics=[])
+        e2 = ArchiveEntry(title="Persist test", content="Body to dedup and persist", topics=[])
+        e2.created_at = "2099-01-01T00:00:00+00:00"
+        archive._entries[e2.id] = e2
+        archive._save()
+
+        archive.consolidate(dry_run=False)
+        assert archive.count == 1
+
+        reloaded = MnemosyneArchive(archive_path=path, auto_embed=False)
+        assert reloaded.count == 1

nexus/mnemosyne/tests/test_path.py

@@ -0,0 +1,106 @@
+"""Tests for MnemosyneArchive.shortest_path and path_explanation."""
+
+from nexus.mnemosyne.archive import MnemosyneArchive
+from nexus.mnemosyne.entry import ArchiveEntry
+
+
+def _make_archive(tmp_path):
+    archive = MnemosyneArchive(str(tmp_path / "test_archive.json"))
+    return archive
+
+
+class TestShortestPath:
+    def test_direct_connection(self, tmp_path):
+        archive = _make_archive(tmp_path)
+        a = archive.add("Alpha", "first entry", topics=["start"])
+        b = archive.add("Beta", "second entry", topics=["end"])
+        # Manually link
+        a.links.append(b.id)
+        b.links.append(a.id)
+        archive._entries[a.id] = a
+        archive._entries[b.id] = b
+        archive._save()
+
+        path = archive.shortest_path(a.id, b.id)
+        assert path == [a.id, b.id]
+
+    def test_multi_hop_path(self, tmp_path):
+        archive = _make_archive(tmp_path)
+        a = archive.add("A", "alpha", topics=["x"])
+        b = archive.add("B", "beta", topics=["y"])
+        c = archive.add("C", "gamma", topics=["z"])
+        # Chain: A -> B -> C
+        a.links.append(b.id)
+        b.links.extend([a.id, c.id])
+        c.links.append(b.id)
+        archive._entries[a.id] = a
+        archive._entries[b.id] = b
+        archive._entries[c.id] = c
+        archive._save()
+
+        path = archive.shortest_path(a.id, c.id)
+        assert path == [a.id, b.id, c.id]
+
+    def test_no_path(self, tmp_path):
+        archive = _make_archive(tmp_path)
+        a = archive.add("A", "isolated", topics=[])
+        b = archive.add("B", "also isolated", topics=[])
+        path = archive.shortest_path(a.id, b.id)
+        assert path is None
+
+    def test_same_entry(self, tmp_path):
+        archive = _make_archive(tmp_path)
+        a = archive.add("A", "lonely", topics=[])
+        path = archive.shortest_path(a.id, a.id)
+        assert path == [a.id]
+
+    def test_nonexistent_entry(self, tmp_path):
+        archive = _make_archive(tmp_path)
+        a = archive.add("A", "exists", topics=[])
+        path = archive.shortest_path("fake-id", a.id)
+        assert path is None
+
+    def test_shortest_of_multiple(self, tmp_path):
+        """When multiple paths exist, BFS returns shortest."""
+        archive = _make_archive(tmp_path)
+        a = archive.add("A", "a", topics=[])
+        b = archive.add("B", "b", topics=[])
+        c = archive.add("C", "c", topics=[])
+        d = archive.add("D", "d", topics=[])
+        # A -> B -> D (short)
+        # A -> C -> B -> D (long)
+        a.links.extend([b.id, c.id])
+        b.links.extend([a.id, d.id, c.id])
+        c.links.extend([a.id, b.id])
+        d.links.append(b.id)
+        for e in [a, b, c, d]:
+            archive._entries[e.id] = e
+        archive._save()
+
+        path = archive.shortest_path(a.id, d.id)
+        assert len(path) == 3  # A -> B -> D, not A -> C -> B -> D
+
+
+class TestPathExplanation:
+    def test_returns_step_details(self, tmp_path):
+        archive = _make_archive(tmp_path)
+        a = archive.add("Alpha", "the beginning", topics=["origin"])
+        b = archive.add("Beta", "the middle", topics=["process"])
+        a.links.append(b.id)
+        b.links.append(a.id)
+        archive._entries[a.id] = a
+        archive._entries[b.id] = b
+        archive._save()
+
+        path = [a.id, b.id]
+        steps = archive.path_explanation(path)
+        assert len(steps) == 2
+        assert steps[0]["title"] == "Alpha"
+        assert steps[1]["title"] == "Beta"
+        assert "origin" in steps[0]["topics"]
+
+    def test_content_preview_truncation(self, tmp_path):
+        archive = _make_archive(tmp_path)
+        a = archive.add("A", "x" * 200, topics=[])
+        steps = archive.path_explanation([a.id])
+        assert len(steps[0]["content_preview"]) <= 123  # 120 + "..."