No description
  • Java 50.7%
  • TypeScript 13.9%
  • Python 12.3%
  • Kotlin 11.9%
  • Svelte 10.3%
  • Other 0.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
chris 73aae2695a
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Android Release / Build and publish Android release (push) Successful in 5m27s
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Run scoped PR tests (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Deploy review instance (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Merge pull request 'docs(known-issues): resolve ISSUE-237 — viewer rotation empty state (fixed via PR#1538)' (#1539) from docs/issue-237-resolve into main
2026-11-16 20:16:59 +01:00
.forgejo/workflows chore(android): enable R8 minification + resource shrinking for releases 2026-11-15 19:11:10 +01:00
.opencode refactor(discovery): backfill face bbox into occurrence_ref for generic pipeline 2026-07-20 23:22:23 +02:00
.specify docs: define pre-live legacy removal policy 2026-05-31 20:28:51 +02:00
apps fix(android): don't wipe viewer lists on rotation — reset only on genuine session change 2026-11-16 20:05:42 +01:00
deploy chore(review): trigger review-stack redeploy to pick up spec 070 (PR #1519) 2026-11-15 16:14:58 +01:00
docs chore: release upload-session activity redesign (server 1.21.93, android 0.10.24) 2026-11-15 23:18:29 +01:00
gradle/wrapper Implement v1 baseline foundation 2026-05-10 22:37:57 +02:00
scripts fix(logo): drop photo-card overlays, render tile at target resolution 2026-11-15 11:29:19 +01:00
spec-md feat(backup): re-backup button for purged entries — per-file INV-2 override (ISSUE-190) 2026-10-25 16:50:27 +01:00
specs docs(spec): spec 070 complete — T004 via integration test 2026-11-15 16:50:32 +01:00
tools feat(version): automate version computation from git tags (#292) 2026-06-10 15:34:10 +02:00
workers feat(adr-0123-v7): pool_min_sharpness — independent crop-sharpness floor 2026-11-14 21:14:11 +01:00
.dockerignore Add local Docker Compose build support 2026-05-10 22:56:27 +02:00
.gitignore docs(design): Ausschluss-Timeline Nicht-in-Memories (Ordner+Fotos, Revert, Variante B) 2026-10-25 08:52:49 +01:00
AGENTS.md docs: document Forgejo CLI access for agents in AGENTS.md 2026-10-22 22:20:47 +02:00
build.gradle.kts fix(build): pin Testcontainers docker client API 1.44 (ISSUE-076 root cause) 2026-10-03 10:39:49 +02:00
DEPLOY_TRIGGER.md chore: trigger plants worker redeploy after #445 2026-06-22 22:41:31 +02:00
gradle.properties chore: version 1.21.116 2026-11-12 18:04:41 +01:00
gradlew Implement v1 baseline foundation 2026-05-10 22:37:57 +02:00
gradlew.bat Implement v1 baseline foundation 2026-05-10 22:37:57 +02:00
KNOWN_ISSUES.md docs(known-issues): resolve ISSUE-237 — viewer rotation empty state (fixed via PR#1538) 2026-11-16 20:16:06 +01:00
opencode.json chore(opencode): commit team config (6 agents, opencode.json, feedback log, .gitignore updates) (#193) 2026-06-05 10:05:02 +02:00
README.md feat(deploy): replace leaf storage binds with single stable /srv mount (spec 054) 2026-10-11 13:36:11 +02:00
settings.gradle.kts fix: allow insecure protocol for local build cache 2026-07-10 11:02:23 +02:00
skills-lock.json feat(agent-state): SQLite-backed worktree tracking with crash recovery 2026-06-20 09:37:24 +02:00
test_output.txt feat(core): namespace-scoped plant discovery (T007-T009) 2026-06-17 23:09:57 +02:00
test_results.txt feat(core): namespace-scoped plant discovery (T007-T009) 2026-06-17 23:09:57 +02: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