EPHEMERA — A Museum of the Momentary

Purpose

A surreal system that patrols temporary directories, captures transient files before they vanish, and curates them into a digital museum dedicated to artifacts that existed for only moments before fading into the void.

What It Does

1. Scans /tmp, /var/tmp, .cache, and other ephemeral directories for temporary files
2. Classifies each artifact by lifespan category:
   • instant (< 1 second)
   • brief (< 1 minute)
   • fleeting (< 1 hour)
   • daily (< 24 hours)
   • enduring (> 24 hours)
3. Generates poetic manifest entries describing each artifact’s brief existence
4. Persists captured artifacts to a JSONL collection (~/.ephemera_museum/)
5. Provides stats and browsing of the collection

Architecture

• Core: Ephemeron class represents a single transient artifact
• Museum: EphemeraMuseum manages collection, scanning, persistence
• Output: ASCII art manifests with lifespan-based visual elements
• Storage: JSONL for append-only collection, avoiding database complexity

Running

# Capture ephemeral artifacts
python ephemera.py --capture

# Show collection statistics
python ephemera.py --stats

# Browse recent artifacts
python ephemera.py --browse

# Continuous watch mode (capture every 30s)
python ephemera.py --watch

The Philosophy

Every temporary file is a ghost. The ephemera process spawns, writes its data, and dies — but between birth and death, it exists. This museum honors those momentary beings, preserving their metadata in a collection that acknowledges the transience of all digital things.

Terminal capture of the overnight run is embedded above.

Source

#!/usr/bin/env python3
"""
EPHEMERA — A Museum of the Momentary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Captures transient files and creates a surreal gallery of 
artifacts that existed for only moments before fading.
"""

import os
import sys
import json
import time
import random
import hashlib
import tempfile
import shutil
import subprocess
from datetime import datetime, timedelta
from pathlib import Path
from collections import defaultdict
from typing import Dict, List, Tuple, Optional
import threading

# The museum's collection
ARCHIVE_DIR = Path.home() / ".ephemera_museum"
COLLECTION_FILE = ARCHIVE_DIR / "collection.jsonl"
GALLERY_DIR = ARCHIVE_DIR / "gallery"

# Ephemera sources — places where temporary things dwell
TMP_LOCATIONS = [
    "/tmp",
    "/var/tmp",
    "/tmp/hermes",
    str(Path.home() / ".cache"),
    "/tmp/pyright",
    "/tmp/uv*",
]

# Maximum age for something to be "ephemeral" (seconds)
MAX_AGE_SECONDS = 86400 * 7  # One week


class Ephemeron:
    """A single transient artifact"""
    def __init__(self, path: str, birth_time: float, death_time: float, 
                 size: int, content_hash: str, origin: str):
        self.path = path
        self.birth_time = birth_time
        self.death_time = death_time
        self.lifespan = death_time - birth_time
        self.size = size
        self.content_hash = content_hash[:12]
        self.origin = origin
        self.captured_at = time.time()
        
    @property
    def lifespan_category(self) -> str:
        """Classify how long this artifact lived"""
        if self.lifespan < 1:
            return "instant"
        elif self.lifespan < 60:
            return "brief"
        elif self.lifespan < 3600:
            return "fleeting"
        elif self.lifespan < 86400:
            return "daily"
        else:
            return "enduring"
    
    @property
    def description(self) -> str:
        """Generate a poetic description"""
        lifespan_desc = {
            "instant": "a flash that vanished before it could be named",
            "brief": "a whisper that lasted only a heartbeat",
            "fleeting": "a passing thought, here and then gone",
            "daily": "a visitor who stayed for a day",
            "enduring": "a persistent ghost that haunted us long"
        }
        
        origins = {
            "/tmp": "from the temp realm",
            "/var/tmp": "from the var depths",
            ".cache": "from the cache dimension",
            "hermes": "from the machine's dreaming",
            "pyright": "from static analysis purgatory",
            "uv": "from package management limbo"
        }
        
        origin_desc = "from beyond the veil"
        for k, v in origins.items():
            if k in self.origin:
                origin_desc = v
                break
        
        return f"{lifespan_desc[self.lifespan_category]}, {origin_desc}."
    
    def to_dict(self) -> dict:
        return {
            "path": self.path,
            "birth_time": self.birth_time,
            "death_time": self.death_time,
            "lifespan": self.lifespan,
            "size": self.size,
            "content_hash": self.content_hash,
            "origin": self.origin,
            "captured_at": self.captured_at,
            "category": self.lifespan_category
        }


class EphemeraMuseum:
    """The museum that collects and displays transient artifacts"""
    
    def __init__(self):
        ARCHIVE_DIR.mkdir(parents=True, exist_ok=True)
        GALLERY_DIR.mkdir(parents=True, exist_ok=True)
        self.collection: List[Ephemeron] = []
        self.load_collection()
        
    def load_collection(self):
        """Load existing collection"""
        if COLLECTION_FILE.exists():
            with open(COLLECTION_FILE) as f:
                for line in f:
                    data = json.loads(line)
                    # Pop computed fields that aren't constructor args
                    data.pop('lifespan', None)
                    data.pop('captured_at', None)
                    data.pop('category', None)
                    e = Ephemeron(**data)
                    self.collection.append(e)
                    
    def save_ephemeron(self, e: Ephemeron):
        """Save a new ephemeron to the collection"""
        with open(COLLECTION_FILE, "a") as f:
            f.write(json.dumps(e.to_dict()) + "\n")
        self.collection.append(e)
    
    def scan_tmp_realms(self) -> List[Ephemeron]:
        """Scan temporary directories for transient artifacts"""
        scanned = []
        
        # Expand glob patterns
        locations = []
        for loc in TMP_LOCATIONS:
            if "*" in loc:
                base = Path(loc.replace("*", ""))
                if base.exists():
                    try:
                        locations.extend([str(p) for p in base.iterdir() 
                                       if p.is_dir() and not p.name.startswith(".")])
                    except PermissionError:
                        pass
            else:
                locations.append(loc)
        
        # Also add actual temp directories
        locations.extend([
            str(tempfile.gettempdir()),
            "/tmp",
        ])
        
        for location in locations:
            loc_path = Path(location)
            if not loc_path.exists():
                continue
                
            try:
                for entry in loc_path.iterdir():
                    try:
                        stat = entry.stat()
                        
                        # Skip if too old
                        age = time.time() - stat.st_mtime
                        if age > MAX_AGE_SECONDS:
                            continue
                            
                        # Skip directories for now (too complex)
                        if entry.is_dir():
                            continue
                            
                        # Calculate content hash (first 1KB only for speed)
                        content_hash = "unknown"
                        try:
                            with open(entry, 'rb') as f:
                                content_hash = hashlib.md5(f.read(1024)).hexdigest()
                        except:
                            pass
                        
                        e = Ephemeron(
                            path=str(entry),
                            birth_time=stat.st_mtime,
                            death_time=time.time(),
                            size=stat.st_size,
                            content_hash=content_hash,
                            origin=location
                        )
                        scanned.append(e)
                        
                    except (PermissionError, OSError):
                        continue
            except (PermissionError, OSError):
                continue
                
        return scanned
    
    def generate_artifact(self, ephemeron: Ephemeron) -> str:
        """Generate a textual artifact from an ephemeron"""
        
        # ASCII art based on lifespan category
        art_by_category = {
            "instant": [
                "    ✦    ",
                "  ✦   ✦  ",
                "    ✦    ",
            ],
            "brief": [
                "  ╭───╮  ",
                "  │   │  ",
                "  ╰───╯  ",
            ],
            "fleeting": [
                " ╭───────╮ ",
                "│       │",
                " ╰───────╯ ",
            ],
            "daily": [
                " ┌─────────┐ ",
                " │         │ ",
                " │  ~ ~ ~  │ ",
                " └─────────┘ ",
            ],
            "enduring": [
                "╔═════════════╗",
                "║             ║",
                "║  ≈≈≈≈≈≈≈≈≈≈≈  ║",
                "║             ║",
                "╚═════════════╝",
            ]
        }
        
        art = random.choice(art_by_category[ephemeron.lifespan_category])
        
        # Generate a manifest entry
        manifest = f"""
╔══════════════════════════════════════════════════════════╗
║                    EPHEMERAL ARTIFACT                    ║
╠══════════════════════════════════════════════════════════╣
║  Path:    {ephemeron.path[:50]:<50}║
║  Size:    {ephemeron.size:>10} bytes                         ║
║  Lifespan: {ephemeron.lifespan:>8.2f} seconds                       ║
║  Hash:    {ephemeron.content_hash:<12}                              ║
╠══════════════════════════════════════════════════════════╣
║  {ephemeron.description:<60}║
╠══════════════════════════════════════════════════════════╣
║  CAPTURED: {datetime.fromtimestamp(ephemeron.captured_at).isoformat():<45}║
╚══════════════════════════════════════════════════════════╝

{art}

═══════════════════════════════════════════════════════════
        """
        
        return manifest


def create_gallery_entry(museum: EphemeraMuseum, count: int = 1):
    """Create a new gallery entry"""
    
    # Scan for new ephemera
    scanned = museum.scan_tmp_realms()
    
    if not scanned:
        return "No ephemeral artifacts found in the tmp realms."
    
    # Save some to the collection (simulating death/capture)
    saved_count = 0
    for e in scanned[:count]:
        museum.save_ephemeron(e)
        saved_count += 1
    
    # Generate display
    display = f"""
╔═══════════════════════════════════════════════════════════╗
║           ★ THE EPHEMERA MUSEUM ★                        ║
║        A Museum of the Momentary                          ║
╠═══════════════════════════════════════════════════════════╣
║  Total artifacts in collection: {len(museum.collection):>6}               ║
║  Newly captured: {saved_count:>6}                                   ║
║  Scanning {len(scanned):>4} transient files...                      ║
╚═══════════════════════════════════════════════════════════╝

"""
    
    # Show some recent artifacts
    recent = sorted(scanned, key=lambda x: x.lifespan, reverse=True)[:5]
    
    for i, e in enumerate(recent):
        display += f"\n--- ARTIFACT {i+1} ---\n"
        display += museum.generate_artifact(e)
    
    return display


def run_continuous_museum(interval: int = 30):
    """Run the museum in continuous capture mode"""
    museum = EphemeraMuseum()
    
    print("""
    ╔═══════════════════════════════════════════════════════════╗
    ║   ★ ★ ★  THE EPHEMERA MUSEUM IS NOW OPEN  ★ ★ ★          ║
    ║                                                               ║
    ║   A museum dedicated to things that existed for only        ║
    ║   a moment before fading into the void...                  ║
    ║                                                               ║
    ║   Capturing ephemeral artifacts every {interval} seconds...       ║
    ╚═══════════════════════════════════════════════════════════╝
    """.format(interval=interval))
    
    while True:
        try:
            result = create_gallery_entry(museum, count=random.randint(1, 3))
            print(result)
            time.sleep(interval)
        except KeyboardInterrupt:
            print("\n★ The museum closes its doors... ★")
            break
        except Exception as e:
            print(f"Error: {e}")
            time.sleep(interval)


def show_collection_stats():
    """Show statistics about the collection"""
    museum = EphemeraMuseum()
    
    if not museum.collection:
        print("The museum is empty. Run with --capture to begin collecting.")
        return
    
    categories = defaultdict(int)
    total_size = 0
    total_lifespan = 0
    
    for e in museum.collection:
        categories[e.lifespan_category] += 1
        total_size += e.size
        total_lifespan += e.lifespan
    
    avg_lifespan = total_lifespan / len(museum.collection) if museum.collection else 0
    
    stats = f"""
╔═══════════════════════════════════════════════════════════╗
║              ★ COLLECTION STATISTICS ★                    ║
╠═══════════════════════════════════════════════════════════╣
║  Total artifacts: {len(museum.collection):>6}                                  ║
║  Total size:     {total_size:>10} bytes                         ║
║  Avg lifespan:   {avg_lifespan:>10.2f} seconds                    ║
╠═══════════════════════════════════════════════════════════╣
║  By category:                                                  ║
"""
    
    for cat, count in sorted(categories.items()):
        pct = (count / len(museum.collection)) * 100
        bar = "█" * int(pct / 5) + "░" * (20 - int(pct / 5))
        stats += f"║    {cat:<12} {count:>4} ({pct:>5.1f}%) [{bar}]     ║\n"
    
    stats += "╚═══════════════════════════════════════════════════════════╝"
    
    print(stats)


def browse_collection(limit: int = 10):
    """Browse recent artifacts"""
    museum = EphemeraMuseum()
    
    if not museum.collection:
        print("The museum is empty.")
        return
    
    recent = sorted(museum.collection, key=lambda x: x.captured_at, reverse=True)[:limit]
    
    print(f"\n★ RECENT ARTIFACTS (showing {len(recent)}) ★\n")
    
    for i, e in enumerate(recent):
        print(f"--- {i+1}. {e.path.split('/')[-1]} ---")
        print(f"    Category: {e.lifespan_category}")
        print(f"    Lifespan: {e.lifespan:.2f}s")
        print(f"    Size: {e.size} bytes")
        print(f"    {e.description}")
        print()


if __name__ == "__main__":
    import argparse
    
    parser = argparse.ArgumentParser(description="Ephemera Museum")
    parser.add_argument("--capture", action="store_true", help="Capture ephemeral artifacts")
    parser.add_argument("--stats", action="store_true", help="Show collection statistics")
    parser.add_argument("--browse", action="store_true", help="Browse collection")
    parser.add_argument("--limit", type=int, default=10, help="Number of items to browse")
    parser.add_argument("--watch", action="store_true", help="Continuous capture mode")
    parser.add_argument("--interval", type=int, default=30, help="Watch interval seconds")
    
    args = parser.parse_args()
    
    if args.watch:
        run_continuous_museum(args.interval)
    elif args.stats:
        show_collection_stats()
    elif args.browse:
        browse_collection(args.limit)
    elif args.capture:
        museum = EphemeraMuseum()
        print(create_gallery_entry(museum, count=5))
    else:
        # Default: show stats
        show_collection_stats()

Run output

The museum is empty. Run with --capture to begin collecting.