# AionsHome: a self-hosted AI companion with memory, camera and voice

> AionsHome is a personal AI companion and camera monitoring system that runs entirely on your own machine: a FastAPI and SQLite backend, a dependency free browser front end that installs as a PWA, and an Android shell that bridges to the microphone and camera. The judgement is that it is a well organised single user project rather than a product, and its documentation is a file tree rather than a manual.

**death34018-hue/AionsHome** — Aion — 一个支持长期记忆、语音交互、摄像头视觉的伴侣。 A self-hosted AI companion with long-term memory, voice interaction, camera vision, and smart home integration.

- Repository: https://github.com/death34018-hue/AionsHome
- Stars: 909 · Forks: 206
- Language: Python
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/death34018-hue-aionshome

## A companion that keeps every record on your own machine

The positioning is stated in one line at the top of the project documentation: a local network plus external network through Tailscale grouping, multi-device synchronised AI chat program, combined with a camera based intelligent monitoring system. Two claims in that sentence define the project. First, it is an assistant, not a service, and the data stays on the local computer, with a browser front end that works on PC and phone and installs as a PWA so it runs full screen without an address bar. Second, the camera is not a gimmick bolted on for a demo, it is half the product, since the module list shows a monitoring system that watches activity, reasons about it and wakes the assistant. The audience for something like this is narrow and obvious: a person who wants a companion that is always available, sees and hears, and keeps a private history that no service provider holds.

## FastAPI, SQLite and WebSocket behind a framework free front end

The stack is worth knowing because it explains the deployment story. The backend is Python FastAPI with SQLite through aiosqlite, and WebSocket carries the live traffic. The front end is a multi page architecture in plain JavaScript with no framework, a warm light theme, adaptive layout for phone and PC, and chat.html, chat.css and chat.js kept separate for structure, styling and logic, while the separate feature pages share common.css and common.js for styling and utility functions. That choice has consequences. A browser that loads chat.html and a couple of scripts needs no build step, no node_modules tree and no bundler, which is why the project can be started by double clicking a file on a Windows machine. The cost is that features are pages rather than components, and the module list in the project documentation runs to a dozen route files for chat, music, schedules, camera, location, files, settings, memories, activity, voice, gifts, funds, the playground and wallpapers.

## The voice path from wake word to streamed speech

Voice is the part with the most moving pieces, and the module split makes the flow visible. Voice detection uses WebRTC VAD, the speech recognition goes to an OpenAI compatible provider with a SenseVoiceSmall model, and the reply is synthesised with CosyVoice2, alongside a hold to record voice message mode. The server side TTS module is the interesting design choice: instead of waiting for a full utterance to be synthesised, it splits the text into chunks of 100 to 200 characters, synthesises them asynchronously in parallel, and pushes the audio segments over the WebSocket, with an HTTP fallback path tracked in the WebSocket connection manager. The voice module handles wake word detection and half duplex conversation, carrying the TTS parameters during a call. The consequence for the user is latency that scales with sentence length rather than paragraph length, and the consequence for a developer is that audio is a stream of segments your client has to order and play back.

## Two camera paths and a Sentinel that watches

Camera work happens in parallel through two routes. On the PC, OpenCV with the cv2 DirectShow backend captures frames in a background thread, and an ESP32-CAM can be polled over HTTP for remote frames, giving a dual camera arrangement with switching between the two and a bridge mode for the phone app. The camera module holds a CameraMonitor class, a Sentinel analysis step that injects a summary of device activity into the conversation, a Core wake action, and a CAM_CHECK trigger, alongside the ESP32-CAM switching and the frame bridge. The phone side is where a real workaround appears: the Android shell uses the legacy Camera API, rotates the NV21 bytes and converts to JPEG, then hands the frames to JavaScript by polling, and the documentation says the reason is to get around WebView HTTPS restrictions, with the audio bridge and the video bridge sharing frame data so a recording uses the same source as the live view. The video bridge encodes with MediaCodec for H.264 and AAC and muxes to MP4.

## Memory is embeddings, scored recall and merged summaries

Long term memory is the feature the rest of the system exists to serve, and the memory module shows a layered approach rather than one store. Embeddings come from a Gemini model producing 3072 dimension vectors, retrieved with cosine similarity, and the recall is refined by a composite score rather than pure vector distance. On top of that sit manual and automatic summaries, where an automatic summary merges the private chat and the group chat messages, and an instant sentinel that routes retrieval. Traces of the original text are kept so a memory can be traced back to its source. The context builder is the piece that assembles what the model actually sees: it fetches a merged timeline of private and group messages, renders scenario change markers, builds the ability and memory blocks, and strips tool commands out of the text. That last function is a small detail with a large effect, since it keeps internal directives such as music or alarm markers from being read as conversation.

## One provider layer with CLI backends and REST APIs

The AI provider module keeps every backend behind a single call path, with streaming and non-streaming modes and multimodal message construction. On the list are an OpenAI compatible provider, Google Gemini over its REST API, another OpenAI compatible relay service, and two local subprocess integrations, one for a Gemini CLI with free OAuth authentication and one for a Codex CLI that the documentation marks as dedicated to a particular person. Image generation is separate again, calling a Gemini image preview model through generateContent with an image response modality, and a companion module handles a selfie mode with a reference anchor image for keeping the generated character consistent. The provider abstraction is what makes the rest of the system replaceable: nothing else in the code needs to know whether the reply came from a hosted API or a local CLI subprocess.

## Schedules, location and fund tracking widen it beyond chat

Several modules push the project well past a chat wrapper, and each one is a small self-contained mechanism. The schedule manager handles calendars, alarms and timed monitoring, parsing text commands, triggering the Core wake on an alarm, and taking a screenshot for analysis when a timed monitoring task fires, again injecting a summary of device activity. The location module works from a GPS heartbeat through a map provider, applies a three level judgement, and maintains a state machine with at_home and outside states plus nearby point of interest search, with sentinel notifications when something happens while you are out. A fund module pulls Chinese A share and fund data, computes positions and profit and loss, tracks an index and history, generates a prompt for analysis, and runs a daily task at 14:45. Reading these together, the pattern is consistent: scheduled or sensed events are converted into a short textual summary and injected into the conversation, so the assistant reacts to the world rather than only to chat.

## Installation scripts, an Android shell and no release history

Getting this running is a Windows affair, and the repository root carries a set of one-click batch scripts: one to install the environment, one to install it offline, one to start the service, one to close it, one to restart it, one to clear personal data, and one to launch a dynamic wallpaper in Chrome app mode. A separate deployment tutorial document is written for friends who want their own copy, and there is a vendored dependency directory. Two practical warnings come out of the file listing. The start script contains absolute paths and the documentation says it must be edited after you move the folder, and the personal data script is the thing to run before you hand a copy to someone else. The Android shell is a separate Java project in the tree, built with Gradle 8.5 and AGP 8.2.2, OkHttp 4.12.0, compileSdk 34 and minSdk 24, with a foreground push service holding its own WebSocket, reconnect logic and wake locks, plus an ESP32-CAM bridge that pulls frames and uploads them to the server. On maintenance, the licence field on the repository says MIT, the last push was on 2026-10-11, the repository is not archived, and it publishes no GitHub releases, so there is no version history to pin against.

## Conclusion

AionsHome suits one person who wants an assistant that remembers across sessions, sees through a webcam, speaks and answers on a phone, and keeps every conversation on hardware they control, and it suits a reader who wants to see how such a system is put together, since the module split is unusually legible. It does not suit a team that needs multi-user accounts, a documented API contract or a release cadence, because the repository publishes no releases and the documentation is a directory listing. Before you base anything on it, read config.py and database.py in the aion-chat package to see how settings and the SQLite tables are laid out, and check that the one-click start script still points at your installation path, since it carries absolute paths that break when the folder moves.

## FAQ

### What does AionsHome run on and where is the data stored?

The backend is Python FastAPI with SQLite through aiosqlite and WebSocket, the front end is plain JavaScript pages with no framework, and the documentation states that all data is stored on the local computer. One-click Windows batch scripts in the repository root install the environment and start the service.

### Can I reach AionsHome outside my home network?

Yes, the design combines local network access with external access over Tailscale grouping. The Android launcher offers a choice between the home WiFi address and the Tailscale address, and remembers which one you picked.

### Which AI backends can AionsHome talk to?

The provider module handles an OpenAI compatible service, Google Gemini over REST, another OpenAI compatible relay, a Gemini CLI invoked as a local subprocess with free OAuth authentication, and a Codex CLI invoked as a local subprocess. Image generation goes to a Gemini image preview model through generateContent.

## Sources

- [death34018-hue/AionsHome on GitHub](https://github.com/death34018-hue/AionsHome)
- [Issues](https://github.com/death34018-hue/AionsHome/issues)
- [License: MIT](https://github.com/death34018-hue/AionsHome/blob/main/LICENSE)
- [README](https://github.com/death34018-hue/AionsHome/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/death34018-hue-aionshome