- Java 50.7%
- TypeScript 13.9%
- Python 12.3%
- Kotlin 11.9%
- Svelte 10.3%
- Other 0.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
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
|
||
| .forgejo/workflows | ||
| .opencode | ||
| .specify | ||
| apps | ||
| deploy | ||
| docs | ||
| gradle/wrapper | ||
| scripts | ||
| spec-md | ||
| specs | ||
| tools | ||
| workers | ||
| .dockerignore | ||
| .gitignore | ||
| AGENTS.md | ||
| build.gradle.kts | ||
| DEPLOY_TRIGGER.md | ||
| gradle.properties | ||
| gradlew | ||
| gradlew.bat | ||
| KNOWN_ISSUES.md | ||
| opencode.json | ||
| README.md | ||
| settings.gradle.kts | ||
| skills-lock.json | ||
| test_output.txt | ||
| test_results.txt | ||
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