Nobody has to remember a password.
You come in with your face or your fingerprint, and Mindy takes it from there.
Meet Mindy · What it does · See it · Run it · How it fits together · Safety · No liability · License
Caution
This is simply a student-grade project. It is not a medical device and not medical care. It does not replace a doctor, a mental health professional or a caregiver. It can make mistakes, say the wrong thing, or miss something that matters.
It is provided as it is, with no warranty of any kind. The owner of this project, the student who made it, is not liable or responsible for any injury, loss, damage or other harm, from any cause, that comes from using it or from not being able to use it. Anyone who uses it does so at their own risk.
In an emergency, call your local emergency number.
Mindy is the heart of the app: a gentle face on the screen who talks, listens and remembers. She tells a person what day it is, reminds them of their plans, tells stories, plays word games and asks how yesterday's walk went. If something seems wrong, she tells the caregiver.
Her lips follow the words of her voice. She blinks, her eyes wander, and her face changes with the mood of what is being said.
Losing a word in the middle of a sentence is one of the hardest parts of memory loss. Most apps would answer straight away, or wait for words that never come. Mindy does neither.
Every button carries a picture she chooses herself, so it can be recognised without reading. A drop for water, a cup for tea, a bed for a nap.
The real app, recorded on a real graphics card. Only the seconds she spends thinking are cut out.
These are real screens from the app. The household is made up, and the portraits are illustrations drawn from Mindy's own artwork.
![]() A calm home. Who you are, today, and what comes next. |
![]() The care dashboard. What needs you, most serious first. |
![]() The way in. Two big cards, and Mindy to help. |
![]() On a phone. The same calm, in your hand. |
You need Windows 11 with Docker Desktop, uv, a webcam, and for fingerprints Windows Hello or an Android phone. The AI runs on a graphics card, on an AMD Radeon RX 9060 XT here.
uv run app.pyThat one line starts Docker if needed, then the database, the AI and the voice, then the app at http://localhost:8000. Open it, touch Set up, create the first caregiver, add your face, and you are in.
Settings live in .env, made from .env.example with fresh secrets on the first run. Add your HF_TOKEN there for the model downloads.
Other ways to run it
uv run app.py --no-services # the services are already running
powershell -ExecutionPolicy Bypass -File .\services.ps1 -Status # what is up
powershell -ExecutionPolicy Bypass -File .\services.ps1 -NoAi # the database onlyIf it stops at once with "port 8000 is already in use", Mindfulness is already running. Open http://localhost:8000, or close the other copy first.
Her answers stream over a WebSocket one sentence at a time, each already turned into audio, so she starts speaking while the model is still writing. Word timings from the voice become mouth shapes. Every sentence is also read by the server the moment it arrives, so a threat or talk of self-harm reaches the caregivers before the AI has said a word.
What stays on this computer: the AI, the voice, the face models and the database all run here. Face pictures, conversations and reminders are not sent to any AI company.
What does not: Chrome and Edge listen through the browser's own speech recognition, which can use its maker's online service. Other browsers, like Brave and Firefox, use whisper on this computer instead. The weather comes from Open-Meteo, and when the browser does not share its location, the town is looked up from this computer's address through ipapi.co. Email and text alerts go through whichever service you set up.
| What | How it is looked after |
|---|---|
| The camera | A login needs two or more good pictures, no two the same, and every one must match. Look-alikes are sent to their fingerprint or password. The AI checks that a real person is there, not a photo or a screen. |
| Fingerprints | Passkeys (WebAuthn). The device checks the finger and the app only ever receives a signature. |
| Passwords | Optional. Changing one does not ask for the old one, because people with memory loss forget it. Close the session with "I'm done" on a shared tablet. |
| Limits | One budget per person, 60 requests a minute by default (RATE_LIMIT in .env). A patient sees "Let's take a little break", with the Help button still there. Anyone else is told the exact limit. The alarm is never limited. |
| Caregivers | No caregiver can change another caregiver's login. A caregiver who signs up at the welcome screen waits for approval. |
| The web | A strict Content-Security-Policy with no inline scripts, CSRF on every form, server-side sessions, and known host names only. With ENVIRONMENT=production the app refuses to start with test settings. |
A printed photo can still pass the camera while the AI is away, so a patient then needs a much closer match, and a caregiver's account stays closed to the camera. Fingerprints are the strong login.
Putting it in front of other people
GET /healthzsays the app is up.GET /readyzalso checks the database. Neither counts against the limit.- The app answers only to
ALLOWED_HOSTS. Left empty, that means localhost and 127.0.0.1, plus this computer's name and addresses withHOST=0.0.0.0. When set, it replaces those, so list every name the app is opened by. - Behind a reverse proxy, name it in
TRUSTED_PROXIES, or every visitor looks like the proxy and shares one budget. - Other devices need HTTPS. Without it, passwords and the session cookie cross the network unencrypted, and the app warns about that at startup.
- The limits are counted in memory and start again on a restart. To share the everyday limit between several processes,
uv add redisand pointRATE_LIMIT_STORAGEat a Redis server. - Back up the database and
data/photos. The app copies them nowhere. - Restart after changing
.env, CSS or JS.
Tests
The suites run on a second copy with its own database, so the family's data is never touched. Always pass its address, because some suites default to the live port.
$env:ENVIRONMENT = "test"; $env:PORT = "8010"; $env:POSTGRES_DB = "mindfulness_test"; $env:FACE_LIVENESS = "off"
$env:DATA_DIR = "C:\temp\mindfulness-test" # its own photos folder
$env:RECOVERY_SHOW_CODES = "true"; $env:SMTP_HOST = "localhost"; $env:SMTP_FROM = "test@example.com" # for test_password
$env:EXPOSE_QUERY_COUNT = "true" # for test_queries
$env:RATE_LIMIT = "100000/minute" # "12/minute" for test_limits, and nothing else then
uv run app.py --no-servicesThen, in another window, with a folder holding obama.jpg, obama2.jpg, biden.jpg and two_people.jpg:
| Suite | What it proves |
|---|---|
tests.test_web <faces> <url> |
The whole story on an empty database. Leaves an enrolled caregiver behind. |
tests.test_talk <faces> <url> |
Live talk, cut-off sentences, reminders and Undo, messages, threats and self-harm, alarms, her ears. |
tests.test_password <url> |
Passwords, email and phone login, recovery codes. |
tests.test_carewatch |
The dashboard's warnings and reminders. Needs POSTGRES_DB=mindfulness_test. |
tests.test_queries <faces> <url> |
No N+1: no page runs more statements with more people. Needs POSTGRES_DB=mindfulness_test. |
tests.test_abuse <faces> <url> |
Junk at every entrance: nothing crashes, and no error hides in the server's log. |
tests.test_limits <faces> <url> |
One budget, the words people see, and what is never limited. |
tests.test_face <faces> |
The face engine, and that a changed model file is refused. |
tests.test_liveness <image> |
The AI's check for photos and screens. |
tests.test_passkey <faces> <url> |
Fingerprints with virtual authenticators. Needs uv run --with playwright and http://localhost:8010. |
tests.screenshots <faces> <out> <url> |
Every page, with console errors. Needs uv run --with playwright. |
tests.stress_ai <faces> |
Hard prompts and bursts: is Mindy polite under pressure? |
Run each with uv run python -m. The sign-up limit lives in memory, so restart the copy between suites that sign people up.
Where things are
app.py entry point: services.ps1, then uvicorn
services.ps1 Docker Desktop, database, AI (attach or start)
docker-compose.yml the database and vLLM
vllm_service/ the AMD/NVIDIA vLLM image recipe
mindfulness/
config.py settings from .env
db.py, models.py async engine, tables
security/ headers and CSP, CSRF, sessions, limits, upload ceiling, safe redirects, access log
auth/ login, sign-up, enrolment, face engine, matching, liveness, passkeys, passwords
ai/ Mindy, her memory, voice, ears, reminders and messages, concerns, button pictures
care.py unique IDs and the care circle
carewatch.py the care dashboard
alerts.py distress alerts to caregivers
accounts.py delete account, 30-day retention, purge
guides.py the step-by-step guides Mindy shows
realtime.py Socket.IO live talk
web/ pages, templates, CSS, JS, fonts and icons
tests/ the suites above
docs/TECHNICAL.md the full technical notes
docs/readme/ the pictures on this page, and build_art.py, which draws them
Want every detail? The technical notes cover the AI on an AMD card, the live talk, logging, the database and each security decision.
Mindfulness is simply a student-grade project, and it is not medical care. It is not a medical device, and it has not been reviewed, tested or approved by any doctor, hospital or regulator. It must never be relied on to keep anyone safe. An alarm can fail, a reminder can be missed, and Mindy can be wrong.
To the fullest extent the law allows, the software is provided as it is, with no warranty of any kind, either stated or implied. The owner of this project, the student who made it, is not liable or responsible for any injury, illness, death, loss, damage or other harm, from any cause, that comes from using it, from relying on it, or from not being able to use it. Anyone who uses it, or sets it up for someone else, does so entirely at their own risk and is responsible for that person's care.
Always consult a doctor or a mental health professional. In an emergency, call your local emergency number.
The full wording is in the disclaimer.
Mindfulness is released under the MIT License. Copyright (c) 2026 Dhurjati.
The MIT License covers the code written for this project. The fonts, icons and libraries it bundles, and the AI models it downloads, keep their own licenses, listed in the third-party notices.
Icons by Icons8 · Fonts: Fraunces and Atkinson Hyperlegible · Voice: Kokoro
Made with care, for the people who forget and the people who remember for them.



