2 Readme
Forgejo Actions edited this page 2026-10-11 12:53:05 +00:00

Memories

Memories is a privacy-first, self-hosted photo and video library for households.

It helps you keep a family media archive durable, browsable, searchable, and understandable without handing originals, metadata, faces, or location history to a cloud provider. Originals are stored as immutable app-managed objects, while thumbnails, previews, ML results, albums, sharing state, and exports are managed around them.

What It Does

  • Imports photos and videos through the web UI, API, or CLI.
  • Preserves original media bytes and uses content-addressed storage for exact-byte deduplication.
  • Provides a responsive web app for timeline browsing, media detail, fullscreen viewing, albums, Explore, Map, Search, Sharing, Library, and account settings.
  • Runs local background workers for metadata extraction, thumbnails/previews, face workflows, visual discovery, and other long-running media tasks.
  • Supports household collaboration with local accounts, sharing groups, contribution workflows, and owner-controlled metadata sharing policies.
  • Exposes backup/export, processing issues, maintenance mode, and operator visibility so a self-hoster can understand what the system is doing.

Feature Set

Library And Ingestion

  • Browser upload with upload status and class-aware import issues.
  • Authenticated API and CLI upload using the same Core-owned upload session model.
  • App-managed filesystem library with immutable stored objects and regenerable derived assets.
  • Exact-byte deduplication without collapsing ownership, sharing, metadata, people, or lifecycle records across owners.
  • Timeline and media detail views backed by PostgreSQL metadata and local filesystem media storage.

Browsing And Organization

  • Photo-app style navigation for Photos, Explore, Map, Search, Albums, Sharing, and Library.
  • Albums with normal owner-owned media references rather than copied files.
  • Map browsing over Core-authorized visible coordinates with configurable tile-provider infrastructure.
  • Filename/title/description search, with local semantic search support when compatible embeddings are available.
  • Automatic album suggestion work for owner-reviewed time/location clusters, with provenance and explicit acceptance before creating normal albums.

People, Faces, And Discovery

  • Local people and face workflows with owner-private curation, tentative candidates, merge/remove/dissolve actions, and provenance.
  • Owner-controlled auto-approval and retargeting behavior for recognized people.
  • Shared-person collaboration paths that keep owner-local people distinct from shared identities.
  • Worker-generated ML candidates that Core validates before they become authoritative metadata.
  • Detector-backed visual discovery and typed discovery-domain architecture for future local-first domains.

Sharing And Household Controls

  • Local household accounts with first-admin bootstrap.
  • Sharing groups with explicit roles and contribution policies.
  • Owner-controlled sharing of metadata such as location, people, ratings, titles, descriptions, and original-download permission.
  • Admin roles do not bypass media-owner privacy controls.
  • Contribution review and revocation flows for shared libraries.

Operations And Data Ownership

  • Docker Compose deployment for local/self-hosted Linux servers.
  • PostgreSQL as authoritative runtime metadata storage.
  • Inspectable JSON/JSONL metadata export as an exit artifact.
  • Fidelity restore path based on PostgreSQL dump, stored objects, and restore-relevant configuration.
  • Maintenance mode, processing issue retry flows, worker degraded-mode behavior, and read-only operator dashboard.

Self-Hosting Quick Start

cd deploy
cp example.env .env
# edit .env secrets; set MEMORIES_ADMIN_USERNAME for fresh installs
# (storage paths are configured in the Admin UI after first login — spec 054)
docker compose --env-file .env -f compose.yaml up --build -d

Default local ports:

  • Web: http://localhost:13000
  • API: http://localhost:18080

See deploy/README.md for deployment details, model configuration, tile-provider notes, and operational guidance.

Current Boundaries

Memories is intentionally local-first and self-hosted. It is not trying to be a cloud SaaS, public social network, or full Immich-compatible clone.

Still deferred or intentionally limited:

  • Native mobile backup apps.
  • Server-side watched imports and external-library indexing.
  • Production-grade preview/transcode robustness for every real-world codec and malformed file.
  • Automated scheduled backups and restore UI.
  • Worker-assisted/chunked export generation.
  • Generic plugin framework, cloud sync, and public social-network sharing.

Technology

  • Core API: Java 21, Spring Boot, PostgreSQL, Flyway.
  • Web app: SvelteKit, TypeScript, Tailwind CSS, shadcn-svelte/Bits UI.
  • Workers: JVM media worker plus Python ML worker behind Core-owned worker contracts.
  • Deployment: Docker Compose with API, web, PostgreSQL, media worker, and ML worker services.

Development And Documentation

This repository is developed spec-first. Specs, ADRs, and product documents are source-of-truth artifacts, not disposable notes.

  • Product intent: docs/product-vision.md
  • Architecture decisions: docs/adr/
  • Accepted v1 baseline: specs/001-v1-baseline/
  • Post-v1 feature specs: specs/002-generalized-discovery-pipeline/, specs/003-automatic-album-suggestions/, specs/004-reverse-place-lookup/
  • Agent workflow: docs/dev/agent-workflow.md

Common validation commands:

./gradlew :apps:api:test :apps:worker-media:test --no-daemon
cd apps/web
npm run check
npm run build
cd workers/ml
PYTHONPATH=src python -m unittest discover -s tests