How it works

A short mental model of the system — enough to understand what the commands and the dashboard are actually doing.

Offline first, not offline capable

Everything runs on the machine. Models, maps, knowledge corpora, and your data are all local. The Internet is treated as an optional sync service — used, when present, to download a model, fetch a map region, or refresh a corpus — never as a runtime dependency. Unplug the network and the system keeps working: it just can’t fetch new material until you reconnect.

The Entity Graph

At the centre is a local graph — a kernel process that stores entities (things: a host, a CPU, a file, a function, a map feature, a knowledge document, a place) joined by relationships (edges: CONTAINS, CALLS, DEPENDS_ON, …). Indexing a project, probing the machine, or ingesting a map region all write into this one graph, so the assistant can reason across everything at once — “which projects use MQTT”, “what does this function call”, “what’s near me”.

Browse it with aios graph (or the dashboard Graph tab); the assistant can inspect it too (see Exploring the graph).

Provenance, not fabrication

Every fact in the graph is recorded as one or more observations — each stamped with its source, a locator (e.g. a file:line, an OSM id, a GPS fix), a confidence, and when it was seen. So the assistant can tell you not just an answer but how it knows (aios ask "how do you know…", or the explain behaviour). The design rule is: never fabricate — cite the local evidence.

Local models

The assistant uses local language models (via Ollama). The system probes your hardware and picks a sensible model tier automatically — a general assistant model for questions and chat, a coder model for code tasks — so you rarely choose. aios status shows the selection and why; override with the AIOS_LLM_MODEL environment variable. Answers are grounded in the graph and your knowledge corpora, not the model’s training alone.

One location, many writers

Map and field tools share a single notion of “where you are” — the geo:here entity. GPS, Set Home (the map centre), a place name, or typed coordinates are all just writers of that one value, each stamped with how it was set (gps/manual/place/map) and when. Everything that needs a location — Nearest, Route, Sightlines, Signal — reads that single seam. See Maps & geo.