RA-H OS

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

TL;DR: Clone this repository, choose where the models run, then start the local app. Your SQLite database stays on your device in every setup. Choose OpenAI if you want the easiest model setup. Choose local Qwen through Ollama or llama.cpp if you want the utility model and embedding model running on your own machine.

Cross-platform local runtime: macOS works out of the box. OpenAI is the default AI path. A supported local model profile is available through OpenAI-compatible local endpoints, and Qdrant is available as a vector sidecar when sqlite-vec is unreliable on your platform.

Docs start here: docs/README.md

What This Does

Stores knowledge locally — Notes, bookmarks, ideas, research in a SQLite database on your machine
Provides a UI — Browse, search, and organize your nodes at localhost:3000
Exposes an MCP server — Claude Code and other MCP clients can query and add to your knowledge base

Your database stays on your machine. With the openai profile, model requests go to OpenAI after you add an API key. With qwen-local or llama-cpp, model requests go to your local OpenAI-compatible endpoints.

Current contract:

no runtime dimensions
no separate runtime contexts layer or context capsule
node quality comes from title, description, source, metadata, and explicit edges
direct node lookup first for specific-node intent
getContext for orientation and retrieveQueryContext for broader current-turn grounding
standalone MCP writes node data, but the app owns chunking and embeddings: nodes.source becomes readable chunks, node-level vectors in vec_nodes, and passage vectors in vec_chunks
local model support uses external OpenAI-compatible model servers; RA-H does not bundle model weights

Requirements

Node.js 20.18.1+ — nodejs.org
macOS — Works out of the box
Windows/Linux — Core app flow is being validated; vector search requires sqlite-vec for your platform or Qdrant as the sidecar backend

Install

Choose One Model Path

Every path uses a local SQLite database. The choice is only about where the two AI models run:

You want...	Use this path
The simplest setup and strongest default model quality	Local DB + OpenAI models
No model calls leaving your computer	Local DB + local Qwen models

What "OpenAI models" means:

Your database is local.
Your notes, graph, chunks, and vectors are stored in SQLite on your device.
RA-H sends utility-model requests and embedding requests to the OpenAI API after you add an API key.
The utility model helps with descriptions and summaries. The embedding model powers semantic search.
Choose this if you want the easiest setup and do not want to manage local model runtimes.

What "local Qwen models" means:

Your database is local.
The utility model runs locally.
The embedding model runs locally.
Those model requests go to Ollama or llama.cpp on your device, not to OpenAI or another hosted model API.
The utility model helps with descriptions and summaries. The embedding model powers semantic search.
Choose this if you care most about local control, privacy, offline operation, or avoiding API usage. It requires more setup and enough local hardware.

Option 1: Local DB + OpenAI Models

Use this if you want RA-H running quickly and are comfortable using OpenAI for descriptions, embeddings, and semantic search.

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 localhost:3000. Add your OpenAI API key when the app prompts you, or later in Settings -> API Keys.

Option 2A: Local DB + Local Qwen/Ollama

Use this if you want the easiest local-model setup. Ollama runs the local utility and embedding models.

Prerequisites:

Ollama is installed and running.
These models are pulled before setup.

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 localhost:3000. Settings -> API Keys will show the active local model profile and disable OpenAI key entry.

Option 2B: Local DB + Local Qwen/llama.cpp

Use this if you want local model calls and prefer managing GGUF files and llama.cpp server processes yourself.

Prerequisites:

llama.cpp is installed.
You have compatible Qwen chat and embedding GGUF files.
You start separate OpenAI-compatible servers before running RA-H setup.

Example llama.cpp 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 localhost:3000. Settings -> API Keys will show the active local model profile and disable OpenAI key entry.

Connect MCP After App Setup

MCP lets Claude Code, Codex, Cursor, and other coding agents read and write your RA-H graph. Configure it after the app database exists.

If you used the default database path:

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

If you used a custom SQLITE_DB_PATH, pass that exact same path with --db:

npx -y ra-h-mcp-server@latest setup \
  --client claude-code,codex \
  --yes \
  --db "/absolute/path/to/rah.sqlite"

Fully restart the agent client after changing MCP config. For Claude Code on Mac, use Cmd+Q, then reopen it.

Full install details:

First-Time Setup Rules

Pick the embedding profile before the database is created.

This is not cosmetic. The readable nodes and chunks tables are normal SQLite tables, but the derived vector tables are created with a fixed embedding width:

Setup profile	Utility model	Embedding model	Vector width
`openai`	`gpt-4o-mini`	`text-embedding-3-small`	`1536`
`qwen-local`	`qwen3:4b` through Ollama	`qwen3-embedding:0.6b` through Ollama	`1024`
`llama-cpp`	`qwen3-4b` through llama.cpp	`qwen3-embedding-0.6b` through llama.cpp	`1024`

Setup requires one of these commands on a fresh install.

OpenAI:

npm install
npm run setup:local -- --profile openai
npm run dev

Local Qwen with Ollama:

npm install
ollama pull qwen3:4b
ollama pull qwen3-embedding:0.6b
npm run setup:local -- --profile qwen-local
npm run dev

Local Qwen with llama.cpp:

npm install
npm run setup:local -- --profile llama-cpp
npm run dev

If you run setup without a profile and .env.local does not already select one, setup stops before creating vector tables and prints the supported commands.

If you change embedding provider, model, dimensions, or vector backend after data exists, your source data stays intact but derived embeddings must be rebuilt:

npm run rebuild:embeddings

OpenAI API Key

Only applies to the openai setup profile.

Without a key, you can still create and organize nodes manually.

With a key, you get:

Auto-generated descriptions when you add nodes
Automatic node descriptions
Semantic search (find similar content, not just keyword matches)

Cost: Less than $0.10/day for heavy use. Most users spend $1-2/month.

Setup: The app will prompt you on first launch, or go to Settings -> API Keys.

Get a key at platform.openai.com/api-keys

If you selected qwen-local or llama-cpp, do not add an OpenAI key in the UI. Settings -> API Keys shows the active local model profile and disables OpenAI key entry so the install stays aligned with the setup profile.

Local Model Profile

Use qwen-local or llama-cpp if you want local utility LLM calls and local embeddings.

RA-H does not bundle model weights. It calls local OpenAI-compatible HTTP endpoints. The tested local paths are Ollama with Qwen and llama.cpp with compatible Qwen GGUF files.

Supported Ollama contract:

LLM_PROFILE=openai-compatible
LLM_BASE_URL=http://127.0.0.1:11434/v1
LLM_MODEL=qwen3:4b

EMBEDDING_PROFILE=openai-compatible
EMBEDDING_BASE_URL=http://127.0.0.1:11434/v1
EMBEDDING_MODEL=qwen3-embedding:0.6b
EMBEDDING_DIMENSIONS=1024

Supported llama.cpp contract:

LLM_PROFILE=openai-compatible
LLM_BASE_URL=http://127.0.0.1:8080/v1
LLM_MODEL=qwen3-4b

EMBEDDING_PROFILE=openai-compatible
EMBEDDING_BASE_URL=http://127.0.0.1:8081/v1
EMBEDDING_MODEL=qwen3-embedding-0.6b
EMBEDDING_DIMENSIONS=1024

Runtime guides:

Validate local AI and vector configuration:

npm run doctor:local-ai

If you change embedding provider, model, dimensions, or vector backend after data exists:

npm run rebuild:embeddings

Custom model/provider overrides are advanced and not a broad support guarantee. They may work, but the tested product surface is OpenAI plus the narrow local Qwen profiles.

Vector Backends

Default:

VECTOR_BACKEND=sqlite-vec

Use Qdrant when sqlite-vec is unavailable or unreliable:

docker compose up -d qdrant
VECTOR_BACKEND=qdrant
QDRANT_URL=http://localhost:6333

SQLite remains the source-of-truth database. Qdrant stores only derived vector indexes.

Qdrant does not change your model choice. OpenAI vs local Qwen is controlled by LLM_PROFILE and EMBEDDING_PROFILE. sqlite-vec vs Qdrant is controlled by VECTOR_BACKEND.

Where Your Data Lives

By default, setup creates and seeds the SQLite database in your 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

This default applies to all app profiles:

npm run setup:local -- --profile openai
npm run setup:local -- --profile qwen-local
npm run setup:local -- --profile llama-cpp

This is a standard SQLite file. You can:

Back it up by copying the file
Query it directly with sqlite3 or any SQLite tool
Move it between machines

You can put the database somewhere else by setting SQLITE_DB_PATH before setup. Use this when you want a repo-local DB, a demo DB, or any other separate database:

SQLITE_DB_PATH="$HOME/Desktop/ra-h_os-demo-data/rah.sqlite" npm run setup:local -- --profile qwen-local

To put it directly inside your cloned repo, use a gitignored local folder:

SQLITE_DB_PATH="$PWD/.ra-h/db/rah.sqlite" npm run setup:local -- --profile qwen-local

If MCP should use that same non-default database, pass the same path to the MCP installer:

npx -y ra-h-mcp-server@latest setup --client claude-code,codex --yes --db "$HOME/Desktop/ra-h_os-demo-data/rah.sqlite"

Point MCP At The Right Database

The MCP server reads and writes whichever SQLite file is set as RAH_DB_PATH.

Use the same database path for the app and for MCP. If these paths do not match, the browser UI and your coding agent will be looking at different graphs.

Default Database

If you used the default app-data database, install MCP without --db:

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

That points MCP at the default platform path:

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

Custom Or Repo-Local Database

If you set SQLITE_DB_PATH during app setup, pass that exact same path to the MCP installer with --db.

Example repo-local app setup:

SQLITE_DB_PATH="$PWD/.ra-h/db/rah.sqlite" npm run setup:local -- --profile qwen-local

Matching MCP setup:

npx -y ra-h-mcp-server@latest setup \
  --client claude-code,codex \
  --yes \
  --db "$PWD/.ra-h/db/rah.sqlite"

Project-Scoped Claude Code MCP

If you want Claude Code to use a repo-local database only inside this repo, create a project .mcp.json:

{
  "mcpServers": {
    "ra-h": {
      "command": "npx",
      "args": ["-y", "ra-h-mcp-server@latest"],
      "env": {
        "RAH_DB_PATH": "/absolute/path/to/ra-h_os/.ra-h/db/rah.sqlite"
      }
    }
  }
}

Use the server name ra-h in project config if you want the project database to override a user-level ra-h server while Claude is opened in that repo.

Keep .mcp.json out of git if it contains a machine-specific path.

Verify The Active MCP Database

After configuring MCP, fully restart the client.

Then run:

npx -y ra-h-mcp-server@latest doctor --db "/path/to/rah.sqlite"

Inside your agent, ask it to use the RA-H MCP server and report the database path it is using before it creates or updates nodes.

Demo-safe isolated install

If you need a clean demo without touching your normal RA-H database:

git clone https://github.com/bradwmorris/ra-h_os.git ~/Desktop/ra-h_os-demo
cd ~/Desktop/ra-h_os-demo
npm install
SQLITE_DB_PATH="$HOME/Desktop/ra-h_os-demo-data/rah.sqlite" npm run setup:local -- --profile qwen-local
npm run dev

npx -y ra-h-mcp-server@latest setup \
  --client claude-code,codex \
  --yes \
  --install-rules \
  --target "$HOME/Desktop/ra-h_os-demo" \
  --db "$HOME/Desktop/ra-h_os-demo-data/rah.sqlite"

Connect Claude Code (or other MCP clients)

The recommended path is the CLI installer:

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

If your app uses a custom database path, include --db with that exact path. See Point MCP At The Right Database.

Manual config is still useful for troubleshooting or unsupported clients. Add this to your MCP client config and restart the client fully:

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

Restart Claude Code fully (Cmd+Q on Mac, not just closing the window).

If you need a frozen version for debugging, pin it explicitly and restart the client.

Verify it worked: Ask Claude Do you have RA-H tools available? You should see tools like queryNodes, retrieveQueryContext, createNode, and readSkill.

For contributors testing local changes, use the local path instead:

{
  "mcpServers": {
    "ra-h": {
      "command": "node",
      "args": ["/absolute/path/to/ra-h_os/apps/mcp-server-standalone/index.js"]
    }
  }
}

What happens: Once connected, the agent should use queryNodes for specific existing-node lookup, retrieveQueryContext when broader graph grounding would help, and getContext only for orientation. It should search before creating, propose durable writeback selectively instead of pestering, and treat the graph itself as the source of grounding rather than a separate contexts layer. The MCP server stores source on the node. The app later turns that source into chunks and embeddings.

Recommended memory file: If you use Claude Code or another coding agent, add one short repo-level memory file (AGENTS.md or CLAUDE.md) that reinforces the core graph behavior. Keep it simple and do not maintain conflicting versions across multiple files.

Suggested snippet:

## RA-H Graph Memory

You are helping build a thoughtful graph of atomic units of context.

- Use `queryNodes` for direct lookup of a specific existing node.
- Use `retrieveQueryContext` when broader graph context would help with the current turn.
- Search before creating. Prefer updating the same artifact when it is clearly the same thing.
- `description` should state plainly what the thing is first, then why it belongs and current status.
- Preserve the user's wording in `source` for user-authored ideas unless they explicitly want a rewrite.

Or install that guidance into the repo memory file:

npx -y ra-h-mcp-server@latest install-rules --client claude-code,codex --target . --yes

Available tools:

Tool	What it does
`getContext`	Get graph overview — stats, hub nodes, skills, and orientation signals
`retrieveQueryContext`	Pull relevant graph context for a broader current-turn task
`queryNodes`	Find nodes by keyword
`createNode`	Create a new node
`getNodesById`	Fetch nodes by ID
`updateNode`	Edit an existing node
`createEdge`	Link two nodes together after explicit confirmation
`updateEdge`	Update an edge explanation after explicit confirmation
`queryEdge`	Find connections
`listSkills`	List available skills
`readSkill`	Read a skill by name
`writeSkill`	Create or update a custom skill
`deleteSkill`	Delete a custom skill
`searchContentEmbeddings`	Search through source content (transcripts, books, articles)
`sqliteQuery`	Run read-only SQL queries (SELECT/WITH/PRAGMA)

Example prompts for Claude Code:

"What's in my knowledge graph?"
"Search my knowledge base for notes about React performance"
"Add a node about the article I just read on transformers"
"Show me the nodes connected to this project idea"

Direct Database Access

Query your database directly:

# Open the database
sqlite3 ~/Library/Application\ Support/RA-H/db/rah.sqlite

# List all nodes
SELECT id, title, created_at FROM nodes ORDER BY created_at DESC LIMIT 10;

# Search by title
SELECT title, description FROM nodes WHERE title LIKE '%react%';

# Find connections
SELECT n1.title, e.explanation, n2.title
FROM edges e
JOIN nodes n1 ON e.from_node_id = n1.id
JOIN nodes n2 ON e.to_node_id = n2.id
LIMIT 10;

See docs/2_schema.md and docs/8_mcp.md for the current contract.

Commands

Command	What it does
`npm run setup:local -- --profile openai`	Rebuild native modules, create `.env.local`, create the SQLite DB, and seed OpenAI-width vector tables
`npm run setup:local -- --profile qwen-local`	Rebuild native modules, create `.env.local`, create the SQLite DB, and seed Qwen-width vector tables
`npm run setup:local -- --profile llama-cpp`	Rebuild native modules, create `.env.local`, create the SQLite DB, and seed Qwen-width vector tables for llama.cpp endpoints
`npm run setup:local`	Only valid if `.env.local` already selects an embedding profile; otherwise it stops before DB/vector setup
`npm run bootstrap:local`	Lower-level helper used by `setup:local`; most users should not run this directly
`npm run rebuild:embeddings`	Recreate derived embeddings after changing embedding provider, model, dimensions, or vector backend
`npm run dev`	Start the app at localhost:3000
`npm run dev:local`	Alias for `npm run dev`
`npm run build`	Production build
`npm run type-check`	Check TypeScript

Windows

Windows support is now being validated against real user setups.

The latest runtime update is intended to make the core local/web app work on Windows even if vector search is not configured yet:

the app should still start
nodes, UI, and keyword/FTS search should still work
/api/health/vectors should report vector search as unavailable instead of crashing

For semantic/vector search on Windows:

Go to sqlite-vec releases
Download the Windows x64 release (for example sqlite-vec-0.1.6-loadable-windows-x86_64.zip)
Extract vec0.dll
Copy it to vendor/sqlite-extensions/vec0.dll in this repo
Re-run the normal local setup steps

Without vec0.dll, the core app should still work, but semantic/vector search will be unavailable.

Linux

Linux support depends on which Linux environment you are running.

For standard Linux x64 distributions that use glibc (Ubuntu, Debian, Fedora, etc.), the core app should work and sqlite-vec can be added like this:

Go to sqlite-vec releases
Download the Linux release matching your architecture (for example sqlite-vec-0.1.6-loadable-linux-x86_64.tar.gz)
Extract vec0.so
Copy it to vendor/sqlite-extensions/vec0.so in this repo
Re-run the normal local setup steps

For Alpine/musl environments, sqlite-vec is the problem case. The core app may still run, but sqlite-vec is not the reliable path there. Qdrant is the intended backend for that deployment target.

Without sqlite-vec:

the core app should still start
nodes, UI, and keyword/FTS search should still work
/api/health/vectors should report vector search as unavailable instead of crashing

Community

Discord: discord.gg/3cpQj6Jtc9 — ask questions, share your setup, get help
Repo docs: docs/README.md
Issues: github.com/bradwmorris/ra-h_os/issues
License: MIT

Name		Name	Last commit message	Last commit date
Latest commit History 189 Commits
.github		.github
app		app
apps		apps
docs		docs
ralph		ralph
scripts		scripts
src		src
tests		tests
vendor		vendor
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
LLAMA-CPP-LOCAL-PROFILE.md		LLAMA-CPP-LOCAL-PROFILE.md
LOCAL-MODELS.md		LOCAL-MODELS.md
OLLAMA-LOCAL-PROFILE.md		OLLAMA-LOCAL-PROFILE.md
QDRANT-DEPLOYMENT.md		QDRANT-DEPLOYMENT.md
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
instrumentation.ts		instrumentation.ts
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

RA-H OS

What This Does

Requirements

Install

Choose One Model Path

Option 1: Local DB + OpenAI Models

Option 2A: Local DB + Local Qwen/Ollama

Option 2B: Local DB + Local Qwen/llama.cpp

Connect MCP After App Setup

First-Time Setup Rules

OpenAI API Key

Local Model Profile

Vector Backends

Where Your Data Lives

Point MCP At The Right Database

Default Database

Custom Or Repo-Local Database

Project-Scoped Claude Code MCP

Verify The Active MCP Database

Demo-safe isolated install

Connect Claude Code (or other MCP clients)

Direct Database Access

Commands

Windows

Linux

Community

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

RA-H OS

What This Does

Requirements

Install

Choose One Model Path

Option 1: Local DB + OpenAI Models

Option 2A: Local DB + Local Qwen/Ollama

Option 2B: Local DB + Local Qwen/llama.cpp

Connect MCP After App Setup

First-Time Setup Rules

OpenAI API Key

Local Model Profile

Vector Backends

Where Your Data Lives

Point MCP At The Right Database

Default Database

Custom Or Repo-Local Database

Project-Scoped Claude Code MCP

Verify The Active MCP Database

Demo-safe isolated install

Connect Claude Code (or other MCP clients)

Direct Database Access

Commands

Windows

Linux

Community

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages