---
title: Reachy Mini Minder
emoji: 🤖
colorFrom: purple
colorTo: gray
sdk: static
pinned: false
short_description: Voice-first care companion for Reachy Mini
tags:
  - reachy_mini
  - reachy_mini_python_app
---

# Reachy Mini Minder

A voice-first health companion for [Reachy Mini](https://github.com/pollen-robotics/reachy-mini), helping users log medication, track headaches, and share appointment summaries with their doctor — all through natural conversation.

## Prerequisites

| Requirement                                                       | Version   | Notes                                 |
| ----------------------------------------------------------------- | --------- | ------------------------------------- |
| Python                                                            | **3.10+** | 3.12 recommended                      |
| Node.js                                                           | 18+       | For the React frontend                |
| [uv](https://docs.astral.sh/uv/)                                  | latest    | Python package manager (recommended)  |
| [Reachy Mini SDK](https://github.com/pollen-robotics/reachy-mini) | ≥ 1.2.11  | `pip install reachy-mini`             |
| OpenAI API key                                                    | —         | For the Realtime voice API            |
| Docker _(optional)_                                               | latest    | Only needed for Neo4j knowledge graph |

## Quick Start

```bash
# 1. Clone the repo
git clone <your-repo-url>
cd reachy_mini_minder

# 2. Copy environment file and add your OpenAI key
cp .env.example .env
# Edit .env and set OPENAI_API_KEY=sk-...

# 3. Install Python dependencies
uv sync          # or: pip install -e .

# 4. Install frontend dependencies
cd frontend && npm install && cd ..

# 5. Start everything (daemon + frontend + LangGraph sidecar + app)
./start-dev.sh
```

The app opens at **http://localhost:3000**. The robot starts in wakeword mode — say **"Hey Reachy"** to begin a session.

## Manual Setup (4 terminals)

If you need to debug individual components, run each in its own terminal:

```bash
# Terminal 1 — Robot daemon
source .venv/bin/activate
reachy-mini-daemon

# Terminal 2 — Frontend (Next.js)
cd frontend
npm run dev

# Terminal 3 — LangGraph sidecar (reports, trends, session summary)
source .venv/bin/activate
langgraph dev

# Terminal 4 — Conversation app
source .venv/bin/activate
reachy-mini-minder --react
```

| Service   | URL                   | Purpose                         |
| --------- | --------------------- | ------------------------------- |
| Frontend  | http://localhost:3000 | Main UI                         |
| Daemon    | http://localhost:8000 | Robot hardware control          |
| LangGraph | http://localhost:2024 | Sidecar agent (reports, trends) |

## Environment Variables

Copy `.env.example` to `.env` and configure:

| Variable                     | Required | Description                                                                        |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `OPENAI_API_KEY`             | **Yes**  | OpenAI API key for Realtime voice                                                  |
| `MODEL_NAME`                 | No       | Model name (default: `gpt-realtime`)                                               |
| `REACHY_MINI_CUSTOM_PROFILE` | No       | Custom personality profile folder                                                  |
| `API_TOKEN`                  | No       | Bearer token for LAN deployments                                                   |
| `LANGSMITH_API_KEY`          | No       | For LangGraph tracing (free at [smith.langchain.com](https://smith.langchain.com)) |

## Privacy & Data

Mini Minder stores all health data **locally** in an unencrypted SQLite file (`mini_minder.db`). No data is sent to a remote database.

**Text pipelines** — Session summaries, memory notes, appointment exports, and health-history queries are redacted by [`pii_guard.py`](src/reachy_mini_conversation_app/pii_guard.py) before reaching any cloud LLM. Names are replaced with roles (e.g. _"the patient"_) and medication names are replaced with symptom categories (e.g. _"migraine prevention medication"_).

> [!IMPORTANT]
> **Audio gap:** Microphone audio is streamed directly to the OpenAI Realtime API as raw PCM frames. There is no way to redact speech before it leaves the device. If the user speaks their name, medication names, or other sensitive details aloud, OpenAI's servers will receive that audio. OpenAI's [API data usage policy](https://openai.com/policies/api-data-usage-policies) states that API inputs are not used for model training, but the audio does traverse their infrastructure. Eliminating this gap would require switching to a local speech-to-text model.

## Knowledge Graph (Optional)

For cross-session memory (entity extraction, relationship tracking), you can connect a Neo4j graph database via Docker:

```bash
# Start Neo4j
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5

# Install the memory extras (Presidio PII protection + Neo4j driver)
uv sync --extra memory   # or: pip install -e ".[memory]"
```

The app auto-detects Neo4j on startup (`bolt://localhost:7687`). When connected, it:

- **Extracts entities** (medications, symptoms, people) from each session
- **Injects graph context** into the next session's prompt
- **Browse the graph** at http://localhost:7474

To stop: `docker stop neo4j && docker rm neo4j`

## CLI Flags

```bash
reachy-mini-minder [OPTIONS]
```

| Flag                              | Description                                               |
| --------------------------------- | --------------------------------------------------------- |
| `--react`                         | Enable React frontend mode (requires frontend dev server) |
| `--clear-data`                    | Clear all data (health entries, profile) before starting  |
| `--debug`                         | Enable debug logging                                      |
| `--no-camera`                     | Disable camera usage                                      |
| `--head-tracker {yolo,mediapipe}` | Enable head tracking (requires camera)                    |
| `--local-vision`                  | Use local vision model instead of cloud API               |
| `--robot-name NAME`               | Robot name for Zenoh topics (multi-robot setups)          |

## Project Structure

```
├── src/reachy_mini_conversation_app/
│   ├── main.py                    # Entry point
│   ├── openai_realtime.py         # OpenAI Realtime API handler
│   ├── stream_api.py              # FastAPI WebSocket server
│   ├── database.py                # SQLite health data
│   ├── pii_guard.py               # PII redaction before cloud LLM
│   ├── wakeword_detector.py       # "Hey Reachy" detection (bundled model)
│   ├── profiles/                  # Personality, tools, prompts
│   ├── tools/                     # Voice command implementations
│   ├── langgraph_agent/           # Sidecar agent (reports, trends)
│   └── models/hey_reachy.onnx     # Wakeword model (bundled)
├── frontend/                      # Next.js 16 + React 19 UI
├── tests/                         # pytest test suite
├── start-dev.sh                   # One-command dev launcher
└── .env.example                   # Environment template
```

## Running Tests

```bash
source .venv/bin/activate
python -m pytest tests/ -v
```

## Customization

Use the locked profile folder for personality and tool configuration:

```
src/reachy_mini_conversation_app/profiles/_reachy_mini_minder_locked_profile/
├── instructions.txt    # System prompt personality
├── tools.txt           # Available tool list
└── voice.txt           # Voice settings
```

## License

See [LICENSE](LICENSE) for details.