# mama

**M**edia **A**rchive **M**eets **A**utomation — a self-hosted system for
ingesting, deduplicating, and organizing personal media (photos, videos, music,
documents) on top of ZFS.

## ⚠️ Project Status

**Pre-alpha. Not ready for use by anyone but the author.**

- Database schema, CLI surface, on-disk layout, and HTTP API are unstable and
  will change without migration paths.
- Most features described below are planned, not implemented.
- Documentation lags behind code.

Do not point mama at irreplaceable data. Keep independent backups of anything
mama touches.

## Concept

mama indexes files placed in configured scan folders, stores file contents in a
content-addressed blob store, and exposes them through hardlinked filesystem
views consumable by specialized viewers (Immich for photos and video, Navidrome
for music, Paperless-ngx for documents).

Identical content is stored only once. Per-file context — original path, source
device, scan timestamp, embedded metadata (EXIF, ID3, sidecar files) — is
preserved as *observations* linked to the underlying blob, so duplicates
contribute information instead of clutter.

### Workflow

1. `mama-scan PATH` — index files into the database (no copies, no moves)
2. `mama-apply` — materialize approved observations into the archive
   (blob into CAS, hardlink into view)
3. `mama-web` — browse, merge duplicates, filter, export, delete

## Tech Stack

- Python 3.13, FastAPI, SQLAlchemy 2.x (async), Alembic
- PostgreSQL 16 (JSONB for embedded metadata)
- Vue 3, Vite
- ZFS (single archive dataset, snapshots, NFS export), Caddy
- ExifTool, BLAKE3, ffmpeg, Pillow
- Docker Compose for companion viewers (Immich, Navidrome, Paperless-ngx)

## Disclaimer

mama is provided as-is for personal use. The author assumes no responsibility
for data loss, corruption, mis-deduplication, accidental deletion, or any other
adverse outcome arising from its use. Use at your own risk and only on data you
can afford to lose.

## License

[MIT](LICENSE)