# ═══════════════════════════════════════════════════════════════
# FEATURES.yaml — Mnemosyne Module Manifest
# ═══════════════════════════════════════════════════════════════
#
# Single source of truth for what exists, what's planned, and
# who owns what. Agents and humans MUST check this before
# creating new PRs for Mnemosyne features.
#
# Statuses: shipped | in-progress | planned | deprecated
# Canon path: nexus/mnemosyne/
#
# Parent epic: #1248 (IaC Workflow)
# Created: 2026-04-12
# ═══════════════════════════════════════════════════════════════

project: mnemosyne
canon_path: nexus/mnemosyne/
description: The Living Holographic Archive — memory persistence, search, and graph analysis

# ─── Backend Modules ───────────────────────────────────────
modules:

  archive:
    status: shipped
    files: [archive.py]
    description: Core MnemosyneArchive class — CRUD, search, graph analysis
    features:
      - add / get / remove entries
      - keyword search (substring match)
      - semantic search (Jaccard + link-boost via HolographicLinker)
      - linked entry traversal (BFS by depth)
      - topic filtering and counts
      - export (JSON/Markdown)
      - graph data export (nodes + edges for 3D viz)
      - graph clusters (connected components)
      - hub entries (highest degree centrality)
      - bridge entries (articulation points via DFS)
      - tag management (add_tags, remove_tags, retag)
      - entry update with content dedup (content_hash)
      - find_duplicate (content hash matching)
      - temporal queries (by_date_range, temporal_neighbors)
      - rebuild_links (re-run linker across all entries)
    merged_prs:
      - "#1217"   # Phase 1 foundation
      - "#1225"   # Semantic search
      - "#1220"   # Export, deletion, richer stats
      - "#1234"   # Graph clusters, hubs, bridges
      - "#1238"   # Tag management
      - "#1241"   # Entry update + content dedup
      - "#1246"   # Temporal queries

  entry:
    status: shipped
    files: [entry.py]
    description: ArchiveEntry dataclass — id, title, content, topics, links, timestamps, content_hash

  ingest:
    status: shipped
    files: [ingest.py]
    description: Document ingestion pipeline — chunking, dedup, auto-linking

  linker:
    status: shipped
    files: [linker.py]
    description: HolographicLinker — Jaccard token similarity, auto-link discovery

  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, path, touch, decay, vitality, fading, vibrant

  tests:
    status: shipped
    files:
      - tests/__init__.py
      - tests/test_archive.py
      - tests/test_graph_clusters.py
    description: Test suite covering archive CRUD, search, graph analysis, clusters

# ─── Frontend Components ───────────────────────────────────
# Located in nexus/components/ (shared with other Nexus features)

frontend:

  spatial_memory:
    status: shipped
    files: [nexus/components/spatial-memory.js]
    description: 3D memory crystal rendering and spatial layout

  memory_search:
    status: shipped
    files: [nexus/components/spatial-memory.js]
    description: searchByContent() — text search through holographic archive
    merged_prs:
      - "#1201"  # Spatial search

  memory_filter:
    status: shipped
    files: [] # inline in index.html
    description: Toggle memory categories by region
    merged_prs:
      - "#1213"

  memory_inspector:
    status: shipped
    files: [nexus/components/memory-inspect.js]
    description: Click-to-inspect detail panel for memory crystals
    merged_prs:
      - "#1229"

  memory_connections:
    status: shipped
    files: [nexus/components/memory-connections.js]
    description: Browse, add, remove memory relationships panel
    merged_prs:
      - "#1247"

  memory_birth:
    status: shipped
    files: [nexus/components/memory-birth.js]
    description: Birth animation when new memories are created
    merged_prs:
      - "#1222"

  memory_particles:
    status: shipped
    files: [nexus/components/memory-particles.js]
    description: Ambient particle system — memory activity visualization
    merged_prs:
      - "#1205"

  memory_optimizer:
    status: shipped
    files: [nexus/components/memory-optimizer.js]
    description: Performance optimization for large memory sets

  timeline_scrubber:
    status: shipped
    files: [nexus/components/timeline-scrubber.js]
    description: Temporal navigation scrubber for memory timeline

  health_dashboard:
    status: shipped
    files: [] # overlay in index.html
    description: Archive statistics overlay panel
    merged_prs:
      - "#1211"

# ─── Planned / Unshipped ──────────────────────────────────

planned:

  memory_decay:
    status: shipped
    files: [entry.py, archive.py]
    description: >
      Memories have living energy that fades with neglect and
      brightens with access. Vitality score based on access
      frequency and recency. Exponential decay with 30-day half-life.
      Touch boost with diminishing returns.
    priority: medium
    merged_prs:
      - "#TBD"  # Will be filled when PR is created

  memory_pulse:
    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.
    priority: medium
    merged_prs:
      - "#1263"

  embedding_backend:
    status: shipped
    files: [embeddings.py]
    description: >
      Pluggable embedding backend for true semantic search.
      Supports Ollama (local models) and TF-IDF fallback.
      Auto-detects best available backend.
    priority: high
    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: 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"