For additional context about technologies to be used, project structure,
shell commands, and other important information, use spec-query tool for spec artifacts.
Project Context
Memories is a privacy-first, self-hosted/local-first alternative to Immich for personal and family photo/video management.
Use spec-driven development. The constitution, specs, plans, tasks, and ADRs are source-of-truth artifacts, not disposable notes.
Before implementation, clarify architecture decisions that affect long-term data ownership, migration cost, backup/restore, privacy, or operational complexity.
Prefer boring, inspectable technology and a future-aligned domain model delivered in small, testable increments over broad feature parity or throwaway simplifications.
Use docs/product-vision.md for current product intent and docs/adr/ for architecture decisions.
Project Tooling
Build: Gradle 8.13 (Kotlin DSL) — NOT Maven. Multi-module: apps:api, apps:worker-media. Use rtk ./gradlew <task> for all builds/tests.
CI/CD: Forgejo Actions (.forgejo/workflows/).
Infra: Docker Compose + Traefik.
DB: PostgreSQL with Flyway migrations.
Frontend: SvelteKit 2 + Svelte 5 + Tailwind CSS v4 + shadcn-svelte.
Backend: Java 21 + Spring Boot 3.x.
Workers: Python 3 + ONNX Runtime.
Full canonical tech stack: specs/techstack.json (via spec-query).
Code Navigation — Use CodeGraph
This repo is indexed by CodeGraph (.codegraph/ at the repo root, live file watcher, ~1s sync lag).
All agents must prefer CodeGraph over broad grep/find/read loops when locating or understanding code. Expensive pattern searches over the whole tree are a last resort, not a starting point.
- Primary: MCP tool
codegraph_explore. One call returns the relevant symbols' verbatim line-numbered source, the call paths between them (including dynamic-dispatch/callback/JSX hops grep cannot follow), a blast radius (callers + test coverage), and an index-freshness banner. - Fallback (MCP unavailable): shell
codegraph context "<task or question>"(markdown brief, primary fallback). More specific:codegraph query <search>(symbol search),codegraph callers|callees <symbol>,codegraph impact <symbol>,codegraph files. There is NOcodegraph exploresubcommand — do not call it. - Use it for: "where is X", "how does X work", "who calls X", "what breaks if I change X", and reading any named file/symbol before editing it.
Rules of use:
- Treat returned source as already
Read— do not re-read the file to verify it. - Trust the index instead of re-confirming results with grep/ripgrep; it comes from a full AST parse.
- Re-read only files listed under a
⚠ …changed on disk after the last index syncbanner, then continue using CodeGraph. - Do not run
codegraph init— indexing is the user's decision.
Fall back to normal tools when CodeGraph does not cover the target: configs and docs (.forgejo/workflows/, specs/*.json, deploy/compose.yaml, *.gradle.kts, *.md, *.sql), anything not yet indexed, or when you need semantics rather than structure — the compiler and test suite remain authoritative for correctness.
Agent Workflow
Work is coordinated by an orchestrator that plans, delegates to specialist agents, and verifies results. Specialists: explorer (codebase recon), librarian (external docs/research), oracle (architecture, review, debugging escalation), designer (UI/UX), fixer (bounded mechanical implementation).
Concurrent agent work must use separate git worktrees and separate branches. Do not run multiple agents in the same checkout. All task worktrees must be created under .worktrees/ (relative to repo root, e.g., memories/.worktrees/<task-name>/).
Before creating any agent branch or pull request, fetch the remote and base the branch on the latest remote main (or the active integration branch if it is not main). Do not branch from a stale local main.
At session start, run git branch --show-current. If on main/master/the active integration branch, code and runtime changes require a separate worktree + branch, created autonomously from the latest remote base unless the user explicitly asks otherwise.
Each agent session owns exactly one worktree and one branch. Code and runtime changes always require a separate worktree + branch + PR. Non-deployment files (docs, agent configs, specs, skills, memory files) may be committed directly to main — the pre-commit hook enforces the safe-file list, but note the remote rejects ALL direct pushes to main in practice: route everything through PRs. When in doubt, use a branch. Agents may merge PRs into main or the active integration branch when the PR is ready: branch current with target, conflicts resolved locally, CI/build green, version bumped per release policy.
At session start, check the latest daily full-tests CI run (workflow Daily Full Tests). If failures found → report to user with summary, offer to dispatch fixes.
Implementation flow: implementer creates the PR after local verification; orchestrator reviews/tests and merges when ready; after merge, verify post-merge CI on main (forgejo skill: actions run-list + actions run-view). If the build fails, report immediately and do not clean up the worktree.
Known Issues Maintenance
All agents must maintain KNOWN_ISSUES.md at repo root.
Rules:
- Append new issues with
ISSUE-NNNprefix (sequential numbering, find next available). - One line per issue. Format:
[ISSUE-NNN]criticalitystatusarea:NAMEdescription [ref] - Criticality:
low(cosmetic),med(workaround exists, user-visible),high(broken feature or data risk). - Status:
open|mitigated|resolved. - Area: matches module/subsystem (e.g.
area:timeline,area:auth). - Ref:
spec:NNNorPR#NNNor commit hash. - Never edit another agent's entry without explicit consent.
- On
resolved: move entry to Archived section with date prefix(YYYY-MM-DD). - The orchestrator consolidates/archives periodically.
Deployment Policy
All deployments must go through the Forgejo CI/CD workflow. Never deploy manually.
- Do NOT run
docker compose up,docker pull,docker restart,docker rm, or any other docker commands to deploy or update services. - The only valid deployment path is: push/merge to
main→ CI workflow builds + deploys automatically. - The workflow uses scoped detection (
scripts/ci/detect-scopes.sh) and only rebuilds/redeploys services whose source files changed. This is intentional — unchanged services are not redeployed. - If a service appears stale after a merge, the correct fix is to touch a relevant file in that service (or trigger a full rebuild by modifying
.forgejo/workflows/ordeploy/compose.yaml) and merge via PR — not to run docker commands manually. - Manual docker operations are allowed ONLY for non-deployment purposes: reading logs (
docker compose logs), inspecting container state, or debugging — never for deploying new images.
Docs hygiene — public repository, operational security
This repository is public. When writing or editing documentation:
- Public docs must not contain network topology, host roles/hardware, tunnel/proxy/edge details, internal IPs, or port layouts.
- Operator infrastructure detail belongs in the private local ops notes under
~/.config/memories/(never committed). - Describe WHAT exists and HOW to operate it via repo-relative paths and env vars — not WHERE it runs or HOW it is exposed.
- Reachability of operator-run instances is stated as a public URL only ("is reachable at "); the routing behind it is the operator's private concern.
- If you find a leak of this class in docs, sanitize it the same way: keep the runbook usable, move the specifics to the private note.
Forgejo access for agents
- Forgejo REST operations (PRs, issues, releases, Actions) go through the local CLI:
python3 ~/.agents/skills/forgejo/scripts/forgejo.py(there is no MCP forgejo tool and nogh/teaCLI on this machine). It reads its token from~/.config/fgj/config.yaml. - Always pass
--hostname git.wiwie.dk -R chris/memorieson every command — do not rely on defaults. ci statustakes a PR NUMBER, not a commit SHA; to scope CI runs by commit, useactions run-list --jsonand filter byhead_sha, then inspect jobs withactions run-jobs <run_id>.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference