NexusOS/README.md

NexusOS

A local-first AI assistant platform. Runs entirely on your machine — a Python/FastAPI backend, a bundled Ollama instance for inference, a persistent memory service, and a React frontend. No external AI provider is called.

---

What it is

NexusOS ("Nexus") is a self-hosted assistant you actually own. All inference runs through a locally bundled Ollama on localhost; conversations, facts, and settings live in local SQLite. It ships with desktop branding (XFCE theme, icons, boot splash) so it can be run as a full assistant environment, not just a web app.

• Chat — streaming responses from local Ollama models (SSE).
• Persistent memory — a dedicated service auto-extracts durable facts from each exchange and layers them into future prompts.
• Playbooks — ordered YAML system-prompt records; the first is the active persona, the rest are injected as reference context.
• Model management — list, pull, and delete Ollama models from the UI/CLI.
• History — full conversation persistence, search, edit, export.

Quick start

Requires Python 3, Node, and a GPU is optional (CPU works).

# 1. Install deps into the Promethean venv (auto-selects AMD/NVIDIA/CPU)
./bin/install.sh

# 2. Launch the full stack (memory :8001, backend :8000, frontend :5173)
./launch_nexus.sh

Python deps are layered: requirements-base.txt (GPU-agnostic core) plus one overlay — requirements-amd.txt (ROCm), requirements-nvidia.txt (CUDA), or requirements-wsl.txt (CPU-only). bin/install.sh picks the right one for the host.

Individual services

source Promethean/bin/activate

uvicorn synapse.main:sio_app          --host 0.0.0.0 --port 8000 --reload   # backend
uvicorn synapse.memory.service:app    --host 0.0.0.0 --port 8001 --reload   # memory
cd interface/web && npm run dev                                             # frontend

CLI (ncp)

Start/stop services and drive the same features as the web UI over the REST API:

./management/nexus-cli.sh start        # backend + frontend (--backend|--frontend|--memory)
./management/nexus-cli.sh stop

ncp chat "<message>"                   # stream a reply
ncp memory list | add <text> | rm <id>
ncp playbook list | show <id>          # first playbook (*) = active system prompt
ncp history [query]                    # recent conversations

Architecture

Component	Location	Role
Synapse (backend)	synapse/	FastAPI app. /chat/stream, /playbooks, /memory, /models, /conversations, /settings, /ollama, /icons. Assembles the system prompt: active playbook → reference playbooks → memory facts → relevant past snippets.
Memory service	synapse/memory/	Separate FastAPI app (:8001). /memories/extract uses an Ollama prompt to decide what to persist. Shares the SQLite DB with the backend.
Playbooks	synapse/playbooks/ + data/playbooks/	Ordered {id}.yaml records managed by PlaybookManager.
Ollama	ollama/bin/ollama	Bundled binary; OllamaManager handles lifecycle + model selection (Vulkan GPU detection). HTTP API at 127.0.0.1:11434.
Frontend	interface/web/	React 19 + Vite. Pages: Chat, Playbooks, History, Models, Memory, Settings.

Storage

Most data lives in synapse/memory/memory.db (SQLite, WAL) — facts, conversations, messages, settings. Playbooks are the exception (YAML files in data/playbooks/). All paths are defined in synapse/nexus_config.py.

Layout

synapse/          FastAPI backend + memory service + playbook/ollama managers
interface/web/    React + Vite frontend
management/       nexus-cli.sh, ncp API client, control panel, desktop theme
bin/              install, backup/restore, panel + provisioning scripts
assets/           branding: icons, boot splash, XFCE/GTK theme
data/playbooks/   active playbook YAML

Configuration

Concern	Location
Ollama host	OLLAMA_HOST env (default http://127.0.0.1:11434)
Filesystem paths	synapse/nexus_config.py
Frontend API base URL	interface/web/src/config.js
Python deps	requirements-base.txt + amd/nvidia/wsl overlay

---

_{NexusOS · local AI, self-hosted on GitNexus}