234 lines
8.6 KiB
Markdown
234 lines
8.6 KiB
Markdown
# RA-H OS
|
|
|
|
```
|
|
██████╗ █████╗ ██╗ ██╗
|
|
██╔══██╗██╔══██╗ ██║ ██║
|
|
██████╔╝███████║█████╗███████║
|
|
██╔══██╗██╔══██║╚════╝██╔══██║
|
|
██║ ██║██║ ██║ ██║ ██║
|
|
╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚═╝
|
|
```
|
|
|
|
**TL;DR:** Clone this repository and you'll have a local SQLite database on your computer. External AI agents can read and write nodes in it. The app owns chunking and embedding from node source.
|
|
|
|
[](https://youtu.be/IA02YB8mInM?si=WoWpNE9QZEKEukvZ)
|
|
|
|
> **Cross-platform local runtime:** macOS works out of the box. Windows and Linux are now being hardened for the core local/web app flow, but semantic/vector search still depends on either sqlite-vec for your platform or a later Qdrant setup.
|
|
|
|
**Full documentation:** [ra-h.app/docs/open-source](https://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](https://nodejs.org/)
|
|
- **macOS** — Works out of the box
|
|
- **Windows/Linux** — Core app flow is being validated; vector search still requires sqlite-vec for your platform (see below)
|
|
|
|
---
|
|
|
|
## Install
|
|
|
|
```bash
|
|
git clone https://github.com/bradwmorris/ra-h_os.git
|
|
cd ra-h_os
|
|
npm install
|
|
npm rebuild better-sqlite3
|
|
npm run bootstrap:local
|
|
npm run dev
|
|
```
|
|
|
|
Open [localhost:3000](http://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 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](https://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`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ra-h": {
|
|
"command": "npx",
|
|
"args": ["--yes", "ra-h-mcp-server@2.1.2"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Restart Claude Code fully (**Cmd+Q on Mac**, not just closing the window).
|
|
|
|
If you publish a newer MCP release and want clients to use it immediately, bump the pinned version here and restart the client. Do not rely on plain `npx ra-h-mcp-server` always refreshing instantly.
|
|
|
|
**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:
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ra-h": {
|
|
"command": "node",
|
|
"args": ["/absolute/path/to/ra-h_os/apps/mcp-server-standalone/index.js"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**What happens:** Once connected, Claude should use `queryNodes` for specific existing-node lookup, `retrieveQueryContext` when broader graph context would help, and `getContext` only for orientation. It proactively captures knowledge. When a new insight, decision, person, or reference surfaces, it should propose a specific node with a strong title, description, source, and metadata. Context is optional and should only be set when the primary scope is obvious. The MCP server stores source on the node. The app later turns that source into chunks and embeddings.
|
|
|
|
Available tools:
|
|
|
|
| Tool | What it does |
|
|
|------|--------------|
|
|
| `getContext` | Get graph overview — stats, contexts, hub nodes, recent activity |
|
|
| `retrieveQueryContext` | Pull relevant graph context for a broader current-turn task |
|
|
| `queryContexts` | List contexts, inspect a context, or search contexts |
|
|
| `queryNodes` | Find nodes by keyword |
|
|
| `createNode` | Create a new node |
|
|
| `writeContext` | Save one confirmed durable context node after explicit user approval |
|
|
| `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 my research context"
|
|
|
|
---
|
|
|
|
## Direct Database Access
|
|
|
|
Query your database directly:
|
|
|
|
```bash
|
|
# 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](https://ra-h.app/docs/open-source) for full schema documentation.
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
| Command | What it does |
|
|
|---------|--------------|
|
|
| `npm run bootstrap:local` | Create `.env.local`, create the SQLite DB, and seed the base schema |
|
|
| `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:
|
|
1. Go to [sqlite-vec releases](https://github.com/asg017/sqlite-vec/releases)
|
|
2. Download the Windows x64 release (for example `sqlite-vec-0.1.6-loadable-windows-x86_64.zip`)
|
|
3. Extract `vec0.dll`
|
|
4. Copy it to `vendor/sqlite-extensions/vec0.dll` in this repo
|
|
5. 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:
|
|
1. Go to [sqlite-vec releases](https://github.com/asg017/sqlite-vec/releases)
|
|
2. Download the Linux release matching your architecture (for example `sqlite-vec-0.1.6-loadable-linux-x86_64.tar.gz`)
|
|
3. Extract `vec0.so`
|
|
4. Copy it to `vendor/sqlite-extensions/vec0.so` in this repo
|
|
5. 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](https://discord.gg/3cpQj6Jtc9) — ask questions, share your setup, get help
|
|
- **Full docs:** [ra-h.app/docs/open-source](https://ra-h.app/docs/open-source)
|
|
- **Issues:** [github.com/bradwmorris/ra-h_os/issues](https://github.com/bradwmorris/ra-h_os/issues)
|
|
- **License:** MIT
|