LetheFS

An autonomous forgetting file system, modelled on human memory.

Version 1.0 · Completed

In Greek myth, Lethe is the river of forgetting. LetheFS applies the same idea to a directory: every file begins fully remembered and its recall score fades over time along the Ebbinghaus forgetting curve. Touch a file and its memory spikes back to full. Leave it untouched and it eventually drops below a threshold, at which point it is moved to quarantine — a reversible holding state you resolve from a live dashboard by either recalling the file or releasing it to a compressed archive.

Nothing is ever deleted silently, and a safety whitelist means system-critical files are never forgotten.

📸 The dashboard

Six files are seeded at full recall, then fade in real time along the curve — aqua to amber to rose —
until the engine drops them into quarantine. One is archived, one is recalled back to full memory.
(Recorded with LETHE_DECAY_UNIT_SECONDS=0.8 so the full cycle fits in one clip.)

Mid-decay: freshly touched files sit at full recall (aqua), older ones fade toward amber,
and forgotten files drop into the quarantine queue awaiting a decision.

The idea

Storage tools usually sort by last modified or size. LetheFS instead asks a more human question — how well do you still remember this file? — and turns that into a continuously decaying score you can watch in real time. It is a small, self-contained study in event-driven systems, background processing, and real-time UI.

Features

• Ebbinghaus decay. Each file's recall score follows R = 100 · e^(−k·t), where t is the time since last access. The score is always recomputed from the last access time, never compounded, so the maths stays exact and idempotent.
• Recall spikes. A watchdog observer streams filesystem events; creating or modifying a file resets its score to 100.
• Reversible quarantine. Files that fall below the threshold are held, not deleted. From the dashboard you can Recall (revive) or Archive (release) each one.
• Compress-or-move archiver. Small files are zipped; files at or above 1 GiB are moved uncompressed to skip a pointless compression pass.
• Guillotine rule. Files that are both large and long-untouched bypass the slow curve and are quarantined directly (thresholds configurable).
• Safety whitelist. Executables, libraries, VCS and dependency folders, OS directories, and LetheFS's own database are never forgotten — enforced by both the engine and the archiver.
• Live dashboard. A WebSocket-driven UI shows every file's recall meter fading in real time, a quarantine queue, running statistics, and an activity log.
• Sandbox by default. The watched directory defaults to a local sandbox/ folder, so the system is always safe to run on a fresh machine.

How it works

1. Watcher — translates filesystem events into memory operations (register new files at full recall; spike the score of touched files).
2. Engine — on a fixed cadence (EPOCH_SECONDS) recomputes every active file's score and quarantines whatever has been forgotten, after clearing the safety gate.
3. Archiver — on your approval, compresses or moves a quarantined file and retires its record.
4. API — a FastAPI app serves the dashboard and pushes a fresh snapshot over a WebSocket every epoch and on every change.

Project structure

LetheFS/
├── run.py                 # entry point (uvicorn)
├── lethe/
│   ├── config.py          # all tunables, env-overridable
│   ├── database.py        # SQLite store: files + activity log
│   ├── security.py        # safety whitelist
│   ├── engine.py          # Ebbinghaus decay + quarantine decisions
│   ├── watcher.py         # watchdog event handler
│   ├── archiver.py        # compress / move quarantined files
│   └── api.py             # FastAPI REST + WebSocket + epoch loop
├── web/index.html         # single-file dashboard (no build step)
├── tests/test_lethe.py    # 13 unit + integration tests
└── docs/architecture.svg

Getting started

Requires Python 3.10+.

pip install -r requirements.txt
python run.py

Then open http://127.0.0.1:8000.

With no files yet, click Seed demo files to create a few sample files in the sandbox, then Fast-forward aging to watch their recall scores drop until they fall into quarantine. From there, Recall revives a file or Archive releases it. You can also drop your own files into the sandbox/ folder and they will be tracked automatically.

Using the dashboard

Control	What it does
Seed demo files	Creates sample files in the sandbox so there is something to forget.
Fast-forward aging	Ages every tracked file so decay is visible immediately instead of waiting.
Reset	Clears the database and rescans the sandbox.
Recall	Resets a quarantined file's score to full and returns it to active tracking.
Archive	Compresses or moves a quarantined file to the archive directory.

Configuration

Every value has a safe default and can be overridden with an environment variable.

Variable	Default	Meaning
LETHE_WATCHED_DIR	./sandbox	Directory to observe.
LETHE_ARCHIVE_DIR	./lethe_archive	Where forgotten files are stored.
LETHE_DECAY_RATE	0.08	Decay constant k in the retention formula.
LETHE_DECAY_UNIT_SECONDS	10	One decay unit in seconds (raise for real-world use).
LETHE_QUARANTINE_THRESHOLD	15.0	Score below which a file is quarantined.
LETHE_EPOCH_SECONDS	3	How often the engine recomputes scores.

Safety

LetheFS is designed so that forgetting can never cause harm:

• it operates only inside the configured watched directory, which is a sandbox by default;
• protected extensions (.exe, .dll, .sys, .db, …) and protected path fragments (.git, node_modules, OS directories, …) are never forgotten;
• quarantine is fully reversible, and archiving compresses rather than deletes.

Testing

pip install -r requirements-dev.txt
pytest -q

The suite covers the decay curve, the safety whitelist, the persistence layer, the archiver, and the HTTP API end to end, and runs on Python 3.10–3.12 in CI (.github/workflows/ci.yml).

Tech stack

Python · FastAPI · Uvicorn · WebSockets · SQLite · watchdog · vanilla JS/CSS dashboard.

Author

Built by Nisa Maaşoğlu, Software Engineer — github.com/nisamaasoglu. Source code available on request.

License

Released under the MIT License © 2026 Hayrunnisa Maaşoğlu.