NexusOS/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What is NexusOS

NexusOS is a local AI assistant platform. It runs a Python/FastAPI backend (Synapse) that interfaces with a locally bundled Ollama instance, a dedicated memory microservice, and a React/Vite frontend. Everything runs on localhost with no external AI API calls — the LLM is served via Ollama.

Running the Project

Full stack (recommended):

./launch_nexus.sh

This activates the Promethean venv, starts the memory service on port 8001, the Synapse backend on port 8000, and the Vite frontend (default port 5173).

Individual services via CLI:

# From nexus-core/ with Promethean venv active:
source Promethean/bin/activate

# Backend
uvicorn synapse.main:sio_app --host 0.0.0.0 --port 8000 --reload

# Memory service
uvicorn synapse.memory.service:app --host 0.0.0.0 --port 8001 --reload

# Frontend
cd interface/web && npm run dev

Management CLI (start/stop individual services with PID tracking):

./management/nexus-cli.sh start   # starts backend + frontend
./management/nexus-cli.sh stop
./management/nexus-cli.sh start_backend / start_frontend

Frontend lint:

cd interface/web && npm run lint

Frontend build:

cd interface/web && npm run build

Architecture

Python venv

All Python code runs inside Promethean/ (a local venv). Always activate it before running backend commands: source Promethean/bin/activate. The AMD ROCm PyTorch stack is installed here (requirements.txt).

Synapse Backend (synapse/)

FastAPI app at synapse/main.py. Key responsibilities:

• /chat and /chat/stream — chat with Ollama; streaming uses SSE. After each exchange the stream endpoint calls the Memory Service to auto-extract persistent facts.
• /playbooks — CRUD for playbooks stored in SQLite via synapse/playbooks/store.py.
• /memory — CRUD for persistent facts (proxies the same SQLite store as the memory service).
• /models — lists, pulls, and deletes Ollama models by proxying ollama/bin/ollama's HTTP API.
• /conversations — persists and retrieves full chat history from SQLite.

System prompt assembly (in main.py chat_stream_endpoint): the final system prompt is built by layering the active playbook instructions → reference playbook context → persistent memory facts → relevant past conversation snippets retrieved by store.search_conversations.

Memory Service (synapse/memory/)

A separate FastAPI app on port 8001. service.py exposes /memories/extract which calls extractor.py — an Ollama prompt that decides whether to persist a new fact from a conversation exchange. The main Synapse backend calls this asynchronously after each streaming response. Both services share the same SQLite database (synapse/memory/memory.db).

Playbook System (synapse/playbooks/ + synapse/playbook_manager.py)

Playbooks are ordered records (title, goal, instructions, tags) stored in SQLite. The first playbook by order is the active system prompt; all subsequent playbooks are injected as reference context. PlaybookManager is the thin class the backend uses to retrieve and render them.

Ollama (ollama/bin/ollama)

A bundled Ollama binary lives at ollama/bin/ollama. OllamaManager in synapse/ollama_manager.py manages its lifecycle (start/stop/health-check) and selects the best available model. GPU detection uses Vulkan (vulkaninfo) to prefer discrete AMD/NVIDIA GPUs. The Ollama HTTP API is at http://127.0.0.1:11434 (overridable via OLLAMA_HOST env var).

Frontend (interface/web/)

React 19 + Vite. No routing library — App.jsx manages page state in a single currentPage useState. All API calls hit http://localhost:8000 (configured in src/config.js). Pages: Chatbot, Playbook editor, Conversation History, Models, Memory, Settings.

Persistent Storage

All data lands in synapse/memory/memory.db (SQLite, WAL mode). Tables: memory facts, conversations, messages, playbooks, app settings. synapse/memory/store.py (PersistentMemoryStore) owns the schema and all queries. nexus_config.py defines all paths; it also ensures all required directories exist on import.

Logs & Runtime State

• runtime/backend.log, runtime/frontend.log — service stdout
• runtime/logs/ollama.log, runtime/logs/chat.log
• runtime/pids/backend.pid, runtime/pids/frontend.pid — used by the management CLI

Key Config

Concern	Location
Ollama host	OLLAMA_HOST env var (default http://127.0.0.1:11434)
All filesystem paths	synapse/nexus_config.py Settings class
Frontend API base URL	interface/web/src/config.js
Python dependencies (AMD)	requirements.txt / amd_requirements.txt
Python dependencies (base)	requirements-base.txt