enderofwings/NexusOS
1
0
Fork 1
Code Issues Pull Requests 1 Actions 10 Packages Projects Releases Wiki Activity

docs(readme): bring README up to date with shipped features

Browse Source 
Ported from the private repo (bin/publish.sh's README-only path): adds a
Flagship features section, reorders Quick start (Linux first), splits out
a Promethean section, corrects the ncp cross-platform parity note, and
replaces the stale in-README Roadmap with a pointer to NexusOS-requests.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Jon Wingender
2026-07-29 22:36:54 -05:00
co-authored by Claude Sonnet 5
parent cc20ceac64
commit 0f335115d3
1 changed files with 116 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+116 -71
View File
@@ -20,21 +20,86 @@ 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 on Linux,
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.
Chat with vision and voice, persistent memory, tool-using playbooks, document
RAG scoped to Projects, gated action tools, and full model management — see
**Flagship features** below for what each of those actually does. Rounding it
out: full conversation history (persist, search, edit, export) and a browser
tail of the service logs.
## Quick start
## Flagship features
### Chat, vision & voice
Streaming responses over SSE, with stop/regenerate/edit-and-resend so a bad
reply doesn't mean retyping the whole message. Attach images and route them to
a multimodal Ollama model for vision. Dictate with local Whisper STT instead
of typing, and have replies read back aloud. A per-message extended-thinking
toggle lets a reasoning model show its work without a round-trip to Settings.
### Persistent memory
A dedicated microservice reads every exchange and decides, via its own Ollama
prompt, whether it contains a durable fact worth keeping — a preference, a
name, a standing instruction. Saved facts get layered back into the system
prompt on every future chat, so Nexus remembers you across conversations
without you re-explaining yourself.
### Playbooks
Ordered YAML system-prompt records instead of one static prompt. The first
playbook is the active persona; the rest are automatically routed in as
reference context when relevant. Each playbook can pin its own chat model and
its own tool allowlist, so "coding assistant" and "creative writing partner"
can be genuinely different setups, not just different wording.
### Documents & RAG
Upload PDF, DOCX, TXT, or Markdown; NexusOS chunks and embeds it into a
sqlite-vec index and cites the matching passages back into chat answers.
**Projects** scope this per workspace — switch projects and the model only
draws on that project's documents (or none, in the unscoped "All" view).
### Action tools with an approval gate
Beyond read-only tools (search memory/history/documents, list models, get the
time), Nexus can search the web, fetch a URL, or save a fact on its own
initiative — but each of those three is gated behind an explicit approval
prompt in the chat UI before it runs. Nothing reaches out to the network or
writes to memory without you seeing the request first.
### Model management
List, pull, and delete Ollama models from the UI or `ncp`, with hardware-aware
recommendations (GPU detection via Vulkan) so a small-VRAM box isn't offered a
model it can't run.
## Quick start
NexusOS runs **single-process**: the backend on `:8000` serves the built web UI
itself, so there's no separate frontend server at runtime. Ollama is started
manually from the app (**Start AI** in the sidebar), not at boot.
### Windows (recommended)
### Linux
Nexus was built using an Apple T2 computer running Linux Mint XFCE. The desktop
branding (theme, icons, boot splash) could hypothetically be adapted to any
Linux distro, but I only support the Ubuntu/Linux Mint package base.
```bash
# 1. Build everything: venv (auto-selects AMD/NVIDIA/CPU), web UI, memory DB,
# system packages, Ollama binary and the XFCE desktop wiring.
./install.sh
# 2. Launch (memory :8001, backend :8000 — backend also serves the built UI)
# The install symlinks ncp into /usr/local/bin (sudo); open a new shell first.
ncp web
```
Python deps are layered: `requirements-base.txt` (GPU-agnostic core) plus one
GPU overlay — `requirements-amd.txt` (ROCm) or `requirements-nvidia.txt` (CUDA).
`requirements-windows.txt` is the standalone CPU-only runtime (no base overlay).
`bin/sync.py` picks the right one for the host.
`./install.sh` is also the update path — re-run it any time to pull the latest
and rebuild. `--check` dry-runs it; `--no-desktop` skips the XFCE panel/theme
wiring (that stage is auto-skipped off XFCE anyway). It's a thin wrapper over
`bin/sync.py restore`, the same code the Windows box runs.
### Windows
```powershell
# 0. Allow scripts to run (PowerShell blocks unsigned scripts by default, which
@@ -65,28 +130,6 @@ The app opens at `:8000`; click **Start AI** to launch Ollama. The installer
uses `requirements-windows.txt` (CPU-only, pure-Python — no ML stack, since Ollama
does all inference over HTTP).
### Linux
```bash
# 1. Build everything: venv (auto-selects AMD/NVIDIA/CPU), web UI, memory DB,
# system packages, Ollama binary and the XFCE desktop wiring.
./install.sh
# 2. Launch (memory :8001, backend :8000 — backend also serves the built UI)
# The install symlinks ncp into /usr/local/bin (sudo); open a new shell first.
ncp web
```
Python deps are layered: `requirements-base.txt` (GPU-agnostic core) plus one
GPU overlay — `requirements-amd.txt` (ROCm) or `requirements-nvidia.txt` (CUDA).
`requirements-windows.txt` is the standalone CPU-only runtime (no base overlay).
`bin/sync.py` picks the right one for the host.
`./install.sh` is also the update path — re-run it any time to pull the latest
and rebuild. `--check` dry-runs it; `--no-desktop` skips the XFCE panel/theme
wiring (that stage is auto-skipped off XFCE anyway). It's a thin wrapper over
`bin/sync.py restore`, the same code the Windows box runs.
### Individual services
```bash
@@ -100,8 +143,35 @@ uvicorn synapse.memory.service:app --host 0.0.0.0 --port 8001 --reload # me
cd interface/web && npm run dev
```
### Promethean
The name for the Python virtual environment all backend code runs in — keeps
Nexus's dependencies out of the system Python. To add a package, activate it
and `pip install` as usual:
```bash
# Linux
source Promethean/bin/activate
pip install <package>
```
```powershell
# Windows — needs the RemoteSigned policy from step 0 above, since
# Activate.ps1 is a script PowerShell would otherwise refuse to run
Promethean\Scripts\Activate.ps1
pip install <package>
```
On Linux, the installer also registers a `promethean` alias in `~/.bashrc`
(and an optional "Promethean Terminal" desktop launcher) that drops you
straight into an activated shell. There's no equivalent on Windows yet — use
`Activate.ps1` above, or call `Promethean\Scripts\python.exe -m pip install
<package>` directly without activating at all.
## CLI (`ncp`)
`ncp` stands for Nexus Control Panel. This was the original method of accessing the frontend and backend power switches before the UI was implemented. The CLI itself is the same Python script on both platforms and behaves identically either way — the exception is `ncp panel` (the tkinter GUI), which was tuned for Linux/XFCE and looks noticeably more dated on Windows.
Start/stop services and drive the same features as the web UI over the REST API:
```bash
@@ -112,7 +182,8 @@ 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
ncp doctor # diagnostics: venv, Node, imports, Ollama, status
ncp doctor [--fix] # diagnostics: venv, Node, imports, Ollama, status
ncp help # see complete help tree
```
## Architecture
@@ -120,17 +191,20 @@ ncp doctor # diagnostics: venv, Node, imports, Ollam
| Component | Location | Role |
|---|---|---|
| **Promethean** (venv) | `Promethean/` | The Python venv all backend code runs in — `source Promethean/bin/activate` (Linux) / `Promethean\Scripts\python.exe` (Windows). Keeps deps out of the system Python. |
| **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. |
| **Synapse** (backend) | `synapse/` | FastAPI app: `/chat/stream` (+ `/chat/approve` for gated tool calls), `/playbooks`, `/memory`, `/models`, `/documents`, `/projects`, `/conversations`, `/stt`, `/logs`, `/settings`, `/ollama`, `/frontend`, `/icons`. Assembles the system prompt: active playbook → reference playbooks → memory facts → relevant past snippets → matching documents → web search results. |
| **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`. |
| **Documents / RAG** | `synapse/memory/store.py` | PDF/DOCX/TXT/MD ingest, chunked and embedded, retrieved via a sqlite-vec index; scoped per **Project** workspace. |
| **Action tools** | `synapse/tools.py`, `synapse/search.py` | Read-only tools (search memory/history/documents, list models, get time) run automatically; `web_search`, `fetch_url`, and `remember` require per-call approval from the chat UI. |
| **Playbooks** | `synapse/playbooks/` + `data/playbooks/` | Ordered `{id}.yaml` records managed by `PlaybookManager`; each can pin a chat model and a tool list. |
| **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. Built to `dist/` and served by the backend at `:8000` (single-process). Pages: Chat, Playbooks, History, Models, Memory, Settings. |
| **Frontend** | `interface/web/` | React 19 + Vite. Built to `dist/` and served by the backend at `:8000` (single-process). Pages: Chat, Playbooks, Models, Memory, Documents, Logs, 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`.
conversations, messages, settings, and the document/vector index. Playbooks
are the exception (YAML files in `data/playbooks/`). All paths are defined in
`synapse/nexus_config.py`.
## Layout
@@ -153,42 +227,13 @@ Promethean/ Python venv (gitignored, built by the installer)
| Frontend API base URL | `interface/web/src/config.js` |
| Python deps | `requirements-base.txt` + amd/nvidia GPU overlay; `requirements-windows.txt` = standalone CPU runtime |
## Roadmap
## Issues and feature requests
Rough plan, not promises. Ordered by how soon and how much it touches.
Planned work and feature requests now live in
[NexusOS-requests](https://git.enderofwings.com/enderofwings/NexusOS-requests)
instead of here. Click the link or hit the tab at the top of the repo.
### Soon
- **Inference knobs in Settings** — expose temperature, context length, and
`num_gpu` in the UI. The backend already passes options to Ollama; there's no
UI for them yet, and small-VRAM boxes need `num_gpu=0` today via env only.
- **Chat controls** — stop generation, regenerate last reply, edit-and-resend.
History editing exists; live regeneration doesn't.
- **Per-playbook model** — playbooks set the persona but not the model; let a
playbook pin its own chat model (Settings already splits chat vs. memory model).
### Eventually
- **Document ingest / RAG** — the embedding stack (nomic-embed-text,
`message_vectors`, cosine recall) already retrieves past conversations. Extend
it to uploaded files and notes so chats can cite your own documents.
- **Vision chat** — attach images to a message and route to a multimodal Ollama
model. The stream path is text-only today.
- **Real vector index** — recall does a brute-force cosine scan over JSON blobs
in SQLite. Fine at current scale; swap in a proper index (e.g. sqlite-vec)
before the DB grows.
### Far future
- **macOS support** — POSIX process control already works; needs a `sync.py`
platform fork, ROCm-free requirements, and an installer. Waiting on a Mac.
- **Voice I/O** — local speech-to-text in, text-to-speech out.
- **Fine-tuning loop** — conversations already export as ShareGPT; close the
loop into a local fine-tune. The ML stack was stripped from the runtime venv
but the requirements files restore it.
- **Tool-using playbooks** — function calling so a playbook can take actions,
not just shape the prompt.
- **Machine learning & gameplay** — the original goal: an agent that learns to
play games alongside me (it started as "teach it to play Lego Star Wars").
Screen capture in, controller/input out, trained by playing. The whole reason
this project exists.
Issues can be submitted in the [Issues](https://git.enderofwings.com/enderofwings/NexusOS) section as normal.
---