Skip to content

About

Student-grade companion app for people living with dementia. Not medical care: no warranty, no liability. MIT License.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Mindfulness: a calm companion for people living with dementia, and for the people who care for them. Mindy, a friendly animated face, says good morning to Asha, reminds her of a walk in the garden, and promises to remember it for her.

Nobody has to remember a password.
You come in with your face or your fingerprint, and Mindy takes it from there.

Made with Python 3.12, FastAPI, Socket.IO, PostgreSQL, pgvector, Gemma 3, vLLM, Kokoro, faster-whisper, ArcFace and WebAuthn.

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.


Meet Mindy

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.

Five animated faces of Mindy. Talking: her lips follow every word. Listening: the microphone stays on and she waits. Thinking: eyes up and one brow raised. Caring: softer eyes when someone is upset. Happy: a bright smile for good news.

When a word slips away

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.

A person says 'I want to drink' and stops. Mindy waits patiently for about five seconds, then says 'It sounds like the sentence stopped, Asha. Did you mean water?' and shows big picture buttons for water, a cup of tea and some juice. One touch answers for the person.

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.

A recording of the real Talk page. Mindy says 'Would you like water?' with moving lips, then three picture buttons appear: Water, A cup of tea and Some juice.

The real app, recorded on a real graphics card. Only the seconds she spends thinking are cut out.


What it does

For the person


No passwords
Come in with a face or a fingerprint. Nothing to remember.

Today, at a glance
Who you are, the day, the time, and what comes next, in large calm type.

A voice that stays with you
One soft voice across the whole app. Every page can read itself aloud.

Asks, then remembers
"Remind me at five to call Priya" goes on the day, with Undo for 15 minutes.

Your people
Big Call buttons, and "tell my son I'd like to see him" reaches the caregivers.

Help, one touch away
A red button with a slow heartbeat. It works even when everything else is resting.

Games and stories
Stories, gentle word games and a friendly chat, any time.

Show Mindy something
Hold up a photo or an object, and she says what she sees.

Shows the way
Ask how to call your daughter, and she lights up the button to touch.

For the caregiver


What needs you
Every warning for every person, most serious first, with numbered steps.

Told straight away
A scream, a cry for help, a threat or talk of self-harm reaches you in seconds.

Reminders you set
Medicines, meals and walks: daily, on chosen days, or once, with a picture.

Mindy's reflections
Thoughts, feelings and actions from recent talks, with concerns she has noticed.

Messages
What someone asked Mindy to pass on waits on your dashboard until you press Seen.

The care circle
Join someone's circle by ID, by your face, or by your fingerprint.

See it

These are real screens from the app. The household is made up, and the portraits are illustrations drawn from Mindy's own artwork.

The home screen: Good morning, Asha, the day and time, and the next thing on her day: Call Ravi at 12:30 PM, in 34 minutes.
A calm home. Who you are, today, and what comes next.
The care dashboard for Priya: one thing needs you now, with counts for alarms, warnings, people in care and reminders done.
The care dashboard. What needs you, most serious first.
The welcome page: two big cards, My face and My fingerprint, with Mindy's helper panel beside them.
The way in. Two big cards, and Mindy to help.
The same home screen on a phone.
On a phone. The same calm, in your hand.

Run it

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.py

That 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 only

If 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.


How it fits together

The person and the caregiver use a browser. It talks to the Mindfulness app, built with FastAPI, Jinja2 and Socket.IO. On the same computer the app uses Gemma 3 on vLLM to think and see, Kokoro for her voice, faster-whisper for her ears, SCRFD and ArcFace to know a face, and PostgreSQL for memory, reminders and faces.

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.


Safety and privacy

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 /healthz says the app is up. GET /readyz also 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 with HOST=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 redis and point RATE_LIMIT_STORAGE at 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-services

Then, 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.


No liability

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.


License

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.

About

Student-grade companion app for people living with dementia. Not medical care: no warranty, no liability. MIT License.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages