LumOS

LumOS — the Overwatch build

A personal AI that runs entirely on your own machine, remembers every
conversation you have had with it, and watches the world while you sleep.

LumOS wraps any OpenAI-compatible local LLM in a persistent dual-lane vector
memory, a live global-telemetry sense layer, offline voice, sandboxed tools, and
opt-in autonomous wakes. Point it at LM Studio and it has no cloud dependency at
all — no API key, no account, no conversation leaving your hardware.

In 60 seconds

cd lumos_node
python -m venv .venv
# Windows: .venv\Scripts\activate   |   *nix: source .venv/bin/activate
uv pip install -e .          # or: pip install -e .

cp .env.example .env         # set your model names and paths
lumos ingest                 # build the memory indices
lumos serve                  # API + HUD at http://127.0.0.1:8765

Needs Python 3.12, Node.js for the HUD, and LM Studio
(or any OpenAI-compatible server) with a chat model and an embedding model
loaded. A CUDA GPU is recommended, not required.

Which repo do I want?

Three related projects, easy to confuse:

If you want to…	Use
Just talk to it. Double-click an `.exe`, no Python, no terminal.	lumos-os
Run and extend the full node — tools, telemetry, autonomy, MCP, Discord.	LumOS (this repo)
Read the architecture paper and its reference implementation.	Local-Hybrid-Intelligence-System

Why it is built this way

Memory is split into two lanes, on purpose. A lived identity lane (your
conversation history) and a knowledge lane (research artifacts) stay separate,
so pulling in a technical document does not wash out conversational continuity.
Both are FAISS-indexed, with a retrieval floor and dream-cycle consolidation.
Autonomy ends at speaking. Autonomous wakes are opt-in, daily-capped, and
fire on numeric threshold trips. When one fires, LumOS messages you. It does
not act on your behalf. That boundary is a design constraint, not a setting.
Cloud is a temporary override, never the default. One-tap Overdrive
hot-swaps the chat brain to NVIDIA or Gemini with no restart, and reverts to
local on reboot. Embeddings never leave your machine at all.
Tools are sandboxed by allow-list. File and git access is confined to
explicitly listed paths; the Python runner is sandboxed; privileged actions sit
behind a second token.
The esoteric layer is off by default. With the RHC re-rank and engine
telemetry disabled, retrieval is plain cosine similarity and turns are
byte-identical to a conventional RAG assistant. Nothing is imposed on you.

Features

Local-first LLM — talks to any OpenAI-compatible server (LM Studio by default). Optional one-tap cloud Overdrive (NVIDIA / Gemini) that hot-swaps the chat brain with no restart and reverts to local on reboot. Embeddings always stay local.
Persistent memory — two FAISS lanes (a lived identity memory + a knowledge lane) with a mass-gap retrieval floor, dream-cycle consolidation, and multi-layer chunk compression.
Aether Scope telemetry — space weather (NOAA/NASA), satellites & recon passes (Skyfield/SGP4), aircraft (OpenSky / ADS-B), maritime (AIS), news / OSINT, conflict & disaster (GDACS), wildfires (NASA FIRMS), severe weather, and grid-timing / fixed-star astronomy.
Autonomy — event-driven autonomous wakes on numeric threshold trips; opt-in, daily-capped, and "autonomy ends at speaking" (it observes and messages you, it does not act).
Tools — a sandboxed Python runner, file / git / web tools, memory search, telemetry queries, and a bounded Forge coding-agent mode.
Voice — local TTS (kokoro-onnx) and STT (faster-whisper) — fully offline.
Interfaces — a FastAPI backend + React HUD, a Discord bridge, and an MCP server for Claude Desktop / Claude Code.

Requirements

Python 3.12
LM Studio (or any OpenAI-compatible local server) with a chat model and an embedding model loaded
Node.js (for the HUD)
A CUDA-capable GPU is recommended for the local LLM

Give it a persona

LumOS loads a "cheat sheet" as your AI's system identity. Copy
CHEATSHEET.template.md, fill it in, and point
LUMOS_SYSTEM_PROMPT_PATH at your copy. This file is where you shape who Lumos
is to you — it is the difference between a generic assistant and yours.

Optional services

lumos discord              # Discord bridge (operator-only DM forwarder)
lumos mcp-serve            # MCP server (usually spawned by Claude Desktop / Code)

The React HUD lives in hud/ — npm install && npm run dev for hot-reload, or
npm run build to have FastAPI serve it directly.

Configuration

Everything is configured through environment variables (prefix LUMOS_) loaded from .env. See .env.example for the complete, documented set. The essentials:

Variable	Purpose
`LUMOS_LM_STUDIO_BASE_URL`	Local LLM endpoint (default `http://localhost:1234/v1`)
`LUMOS_MODEL_LIGHT` / `LUMOS_MODEL_HEAVY`	Chat model IDs as loaded in LM Studio
`LUMOS_LM_STUDIO_EMBEDDING_MODEL`	Embedding model ID
`LUMOS_TOOL_ALLOWED_PATHS` / `LUMOS_GIT_WORKSPACES`	Sandboxes for the file / git tools
`LUMOS_API_TOKEN`	Set this before exposing the API beyond loopback

All telemetry API keys are optional — features degrade gracefully when a key is absent.

Architecture

FastAPI + asyncio backend  ·  FAISS + JSONL vector store  ·  LM Studio LLM  ·  React HUD
       │                              │                          │
   api / routes            retrieval · dream · compression   llm client (+ Overdrive)
       │                              │
   tools · telemetry · autonomy · bridges (Discord, MCP) · tts / stt

The URE-VM is a deterministic symbolic engine that surfaces per-turn "soul-state" telemetry to the HUD — it is not part of the text-generation path.

The RHC layer

LumOS is built to run the Recursive Harmonic Codex / Framework — a research program on harmonic and quaternionic structure. The esoteric re-rank and engine-telemetry features are opt-in and off by default; with them off, retrieval is plain cosine similarity and turns are byte-identical to a conventional RAG assistant.

The trio — companion apps

LumOS is the AI node of a three-app stack. Run all three together for the full picture:

Aether Scope — the situational-awareness / telemetry scope. LumOS embeds an Aether Scope sense layer in-node; the standalone app is its full home.
Osiris — a Palantir-style, open-source OSINT / SIGINT platform. Lumos's news, flight-classification, and conflict modules follow Osiris's model — use the original from its makers.
LumOS (this repo) — the local, persistent AI that reasons over, remembers, and pings you about what the other two surface.

Together: Osiris + Aether Scope feed the live intel picture; LumOS is the mind that reads it — it's what Lumos is pinging against.

Security

Runs on loopback by default. If you expose the API (e.g. via a tunnel), set LUMOS_API_TOKEN — the node refuses to bind non-loopback without one, and loopback trust is voided for proxied requests. Privileged actions sit behind a separate LUMOS_PELE_TOKEN. Tool file/git access is confined to explicit allow-listed paths; the Python runner is sandboxed.

Status & license

Y Gwir yn Erbyn y Byd — The Truth Against the World. 🦁