 ██████╗  █████╗       ██╗  ██╗
 ██╔══██╗██╔══██╗      ██║  ██║
 ██████╔╝███████║█████╗███████║
 ██╔══██╗██╔══██║╚════╝██╔══██║
 ██║  ██║██║  ██║      ██║  ██║
 ╚═╝  ╚═╝╚═╝  ╚═╝      ╚═╝  ╚═╝

Quick Links

Doc	Description
Overview	What RA-H OS is and what contract it shares with the main app
Schema + Search	Current SQLite contract, indexing, and retrieval surfaces
Tools & Skills	MCP tools and skill system
Logging & Evals	Logs, evals, and debugging surfaces
UI	Current pane and focus model
MCP	Full standalone MCP install, behavior guide, and memory-file guidance
Open Source	Scope, support boundary, contributor reality
Full Local	Supported local path vs community patterns
Local Models	OpenAI-compatible local endpoint profile
Qdrant	Optional vector sidecar for sqlite-vec-hostile environments
Troubleshooting	Common issues and fixes

Start Here

If you just want RA-H OS working:

Use the MCP quick install below if you mainly want agent access.
Use the OpenAI local app quick start if you want the browser UI with OpenAI models.
Use the local Qwen/Ollama quick start if you want the browser UI with local Ollama models.
Use the local Qwen/llama.cpp quick start if you want to manage GGUF files and llama.cpp servers yourself.

MCP Quick Install

npx -y ra-h-mcp-server@latest setup --client claude-code --yes

Run doctor after setup or whenever MCP feels stale:

npx -y ra-h-mcp-server@latest doctor

Local App Quick Start: OpenAI

git clone https://github.com/bradwmorris/ra-h_os.git
cd ra-h_os
npm install
npm run setup:local -- --profile openai
npm run dev

Open http://localhost:3000 and add your OpenAI API key when prompted, or later in Settings -> API Keys.

Local App Quick Start: Local Qwen/Ollama

Requires Ollama to be installed and running.

git clone https://github.com/bradwmorris/ra-h_os.git
cd ra-h_os
npm install
ollama pull qwen3:4b
ollama pull qwen3-embedding:0.6b
npm run setup:local -- --profile qwen-local
npm run dev

Open http://localhost:3000. Settings -> API Keys shows the active local model profile and disables OpenAI key entry.

Local App Quick Start: Local Qwen/llama.cpp

Requires llama.cpp to be installed, compatible Qwen GGUF files to exist on disk, and separate OpenAI-compatible servers to be running.

Example servers:

llama-server -m /models/qwen3-4b.gguf --port 8080
llama-server -m /models/qwen3-embedding-0.6b.gguf --embedding --port 8081

Then set up RA-H:

git clone https://github.com/bradwmorris/ra-h_os.git
cd ra-h_os
npm install
npm run setup:local -- --profile llama-cpp
npm run dev

Open http://localhost:3000. Settings -> API Keys shows the active local model profile and disables OpenAI key entry.

Fresh app setup must choose --profile openai, --profile qwen-local, or --profile llama-cpp before vector tables are created. OpenAI embeddings use width 1536; the supported Qwen embedding profiles use width 1024.

MCP Integration

The recommended MCP setup is the CLI command above. Manual config is only for troubleshooting or unsupported clients:

{
  "mcpServers": {
    "ra-h": {
      "command": "npx",
      "args": ["-y", "ra-h-mcp-server@latest"]
    }
  }
}

If you need a frozen version for release/debug work, pin it intentionally and restart the client.

The selected setup profile creates the default database if it does not exist. By default, that database is in the operating system's app-data folder, not inside the cloned repo:

~/Library/Application Support/RA-H/db/rah.sqlite   # macOS
~/.local/share/RA-H/db/rah.sqlite                  # Linux
%APPDATA%/RA-H/db/rah.sqlite                       # Windows

Set SQLITE_DB_PATH before setup if you want a repo-local DB, demo DB, or any other separate location. If MCP should use that same non-default database, pass the same path to the MCP installer with --db.

The standalone MCP server can write nodes without the app running, but the app owns chunking and embedding from node source: readable chunks, full-text indexes, vec_nodes, and vec_chunks. See MCP docs for the full install, verify, memory-file, and troubleshooting path.

Questions?

Open an issue on GitHub.