RA-H OS

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

TL;DR: Clone this repository and you'll have a local SQLite database on your computer. The database schema is structured so external AI agents can continuously read and write to it, building your knowledge graph externally.

Currently macOS only. Linux and Windows support is coming. If you want to run it on Linux/Windows now, see instructions at the bottom.

Full documentation: ra-h.app/docs/open-source

---

What This Does

1. Stores knowledge locally — Notes, bookmarks, ideas, research in a SQLite database on your machine
2. Provides a UI — Browse, search, and organize your nodes at localhost:3000
3. Exposes an MCP server — Claude Code, Cursor, or any MCP client can query and add to your knowledge base

Your data stays on your machine. Nothing is sent anywhere unless you configure an API key.

---

Requirements

• Node.js 20.18.1+ — nodejs.org
• macOS — Works out of the box
• Linux/Windows — Requires building sqlite-vec manually (see below)

---

Install

git clone https://github.com/bradwmorris/ra-h_os.git
cd ra-h_os
npm install
npm rebuild better-sqlite3
./scripts/dev/bootstrap-local.sh
npm run dev

Open localhost:3000. Done.

---

OpenAI API Key

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

With a key, you get:

• Auto-generated descriptions when you add nodes
• Automatic dimension/tag assignment
• 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

---

Where Your Data Lives

~/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 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

---

Connect Claude Code (or other MCP clients)

Add to your ~/.claude.json:

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

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

Verify it worked: Ask Claude "Do you have RA-H tools available?" — you should see tools like createNode, queryNodes, 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, Claude calls getContext first to orient itself (stats, hub nodes, dimensions, available skills). It proactively captures knowledge — when a new insight, decision, person, or reference surfaces, it proposes a specific node (title, dimensions, description) so you can approve with minimal friction. For complex tasks it reads skills to follow your graph conventions and workflows.

Available tools:

Tool	What it does
getContext	Get graph overview — stats, hub nodes, dimensions, recent activity
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
updateEdge	Update an edge explanation
queryEdge	Find connections
queryDimensions	List all tags/categories
createDimension	Create a new dimension
updateDimension	Update/rename a dimension
deleteDimension	Delete a dimension
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"
• "What nodes are connected to my 'research' dimension?"

---

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 ra-h.app/docs/open-source for full schema documentation.

---

Commands

Command	What it does
npm run dev	Start the app at localhost:3000
npm run build	Production build
npm run type-check	Check TypeScript

---

Linux/Windows

The repo ships with a macOS binary for sqlite-vec (vendor/sqlite-extensions/vec0.dylib). On Linux or Windows you need to swap it for your platform's version.

Linux:

1. Go to sqlite-vec releases
2. Download the release matching your architecture (e.g. sqlite-vec-0.1.6-loadable-linux-x86_64.tar.gz)
3. Extract vec0.so from the archive
4. Copy it to vendor/sqlite-extensions/vec0.so in this repo
5. Run the normal install steps above

Windows:

1. Go to sqlite-vec releases
2. Download the Windows release (e.g. sqlite-vec-0.1.6-loadable-windows-x86_64.zip)
3. Extract vec0.dll from the archive
4. Copy it to vendor/sqlite-extensions/vec0.dll in this repo
5. Run the normal install steps above

Without sqlite-vec, everything works except semantic/vector search.

---

Community

• Discord: discord.gg/3cpQj6Jtc9 — ask questions, share your setup, get help
• Full docs: ra-h.app/docs/open-source
• Issues: github.com/bradwmorris/ra-h_os/issues
• License: MIT