Cimmich

Complete the picture: a local-first memory layer for Immich.

Comment

Inspiration

Conventional face recognition works best when a face is clear. Real memories are messier: people turn away, wear helmets, appear partly obscured or are simply known by the owner to have been present. Treating all of those situations as face evidence damages matching quality. Ignoring them leaves the archive incomplete.

Cimmich began with a simple question: can a private photo library preserve the complete human memory without pretending every observation is a face match?

What Cimmich does

Cimmich is an unofficial, open-source, local-first companion for Immich. It adds a separately stored memory and intelligence layer without replacing Immich or writing directly to its database or source media.

Its central idea is to keep four kinds of identity evidence separate:

  • Face - a visible face that can support matching.
  • Head - a visible head without claiming usable face evidence.
  • Body - somebody located through their body without contaminating face scoring.
  • Presence - the owner knows somebody was there, without inventing biometric evidence.

This lets Cimmich connect every genuine appearance to a person while keeping matching evidence clean.

People become more than face clusters. Their photos, details, connections and documents live together. The same local memory graph connects Pets, Places, Things, Events, Trips, Activities and Life periods, with Smart Search across the archive.

Standard, Personal and password-gated Private viewing modes let the owner control what appears. Core remains useful with the people and media already in Immich. Enhanced is an included local matching layer that is off by default and controlled by the owner.

Optional local evidence providers can contribute Face, Body, pose, OCR, object or vision observations. Guided provides a neutral HTTP/JSON access point through which an operator can connect a local model or a frontier harness such as Codex. The operator controls its permissions and maximum viewing tier. Models may propose; only the archive owner decides identity.

How I built it

I work in value creation and transformation, not software engineering. Before Codex, I could identify gaps like this but had no practical way to turn an idea of this complexity into a public product.

During OpenAI Build Week, I used Codex powered by GPT-5.6 Sol as a coordinated development environment.

We began by challenging the concept, mapping user stories, establishing north stars and definitions of done, and iterating until the experience felt right. Once the direction was clear, I divided the work across coordinated Backend, UI/UX and Controller tasks.

Backend implemented and stress-tested the service. UI/UX used the browser to operate Cimmich as a real user. The Controller maintained the shared plan and routed findings between tasks using task-to-task messaging.

This was more than code generation. During a recorded run, the UI task added the six-photo Space Trip extension to the existing synthetic library and walked the resulting journey. It exposed a synchronization defect, routed it to Backend, and continued testing while Backend repaired the problem and returned proof.

Sol was useful well beyond writing code. It helped me navigate unfamiliar engineering decisions, challenge product choices, debug failures and prepare the final release. It also helped plan and direct the photorealistic synthetic archive, allowing me to demonstrate the complete product without exposing the real people whose photographs were used during development.

The final release candidate targets Immich 3.0.3 and stores its data separately in PostgreSQL 17 with pgvector. It has its own credentials, migrations, backup and recovery boundary. It passes 595 service tests and 768 web tests, alongside migration, formatting, lint, Svelte, TypeScript, production-build and clean-install checks.

The public demonstration contains 57 wholly synthetic images: 51 Cedar House scenes and the six-image Space Trip extension. They demonstrate product behaviour, not biometric accuracy or demographic fairness.

Prior work

Cimmich grew out of a problem I had already been trying to solve for myself.

Before Build Week, I had spent a few months experimenting with Immich around my own photo archive - roughly 600 GB covering 15 years. It is exactly the kind of library that gives recognition systems trouble: crowded photos, poor lighting, hidden faces and years of inconsistent organisation.

What existed then was research and a rough prototype: some early model and semantic-search experiments, identity-matching work and a basic UI shell. For the most part, I was approaching the problem from the model side - using local models to identify the hardest photos, including contextual clues when a face alone was not enough.

Build Week is when it became Cimmich. I shifted from experimenting with models to building the product that could make their output genuinely useful.

Using Codex and GPT-5.6 Sol, I turned that early work into the product shown here: a separate service and database, the Face/Head/Body/Presence system, connected memories across people and the rest of the archive, privacy views, Enhanced matching, Guided access, a synthetic public demo, installation and recovery tools, and a much larger testing programme.

I have included a dated Build Week ledger in the repository so the line between the earlier experiments and the work completed for this challenge is clear.

Challenges

The biggest challenge was compressing an enormous scope into less than a week. I constantly had to decide what genuinely needed to ship and what belonged on the roadmap, without cutting away the parts that made Cimmich worth building.

The new cross-task messaging system was another learning curve. At its best, it was incredibly useful: one task could discover a problem, route it to the right place and continue working while another task fixed it.

At its worst, I lost roughly six hours on the final day when several tasks fell into a loop of updating one another without moving the product forward. That taught me that directing AI tasks still requires clear ownership, bounded handoffs and firm stopping conditions. Coordination can multiply the work, but unmanaged coordination can multiply the noise.

What I learned

GPT-5.6 Sol feels even more capable than previous models, which can make it surprisingly easy to become lazy with my own input and oversight.

I found Codex agents work best when treated like extremely eager graduates. At times they deliver brilliant ideas and outcomes that make you want to leave them running overnight. At other times -even with clear goals and structure - they can disappear down a side quest that burns hours and pulls the project in the wrong direction.

The best results came from giving them room to work while still watching closely: setting clear ownership, checking outcomes rather than activity, and being willing to stop and recenter the work when necessary.

The biggest lesson was not to mistake motion for progress.

What’s next

Cimmich is intended as an open contribution to the Immich ecosystem, not a competing commercial photo platform.

The next steps are public owner feedback, installation hardening and upstream-friendly discussion. If the Immich team eventually chooses to reimplement useful parts of the concept natively, I would consider that a successful outcome.

Cimmich is not affiliated with or endorsed by Immich or OpenAI. Its source is prepared under AGPL-3.0-only, with preserved upstream notices. Its synthetic demonstration material has separate CC BY 4.0 attribution and provenance.

Built With

Share this project:

Updates