From a7234be5f45174fa55bf82e808e3d485d3a052ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CBeeRad=E2=80=9D?= Date: Thu, 29 Jan 2026 15:44:06 +1100 Subject: [PATCH] feat(rah-light): update README for lite version - Rename to RA-H Light - Describe as knowledge management backend for AI agents - Add MCP integration section with Claude Code setup - List all 11 available MCP tools - Remove references to chat agents, voice, 3-panel interface - Keep essential sections: quick start, project layout, commands, docs Co-Authored-By: Claude Opus 4.5 --- README.md | 107 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 70 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 7551e6d..b4b2276 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,26 @@ -# RA-H Open Source +# RA-H Light -A local-first AI research workspace. Full 3-panel interface, vector search, content ingestion, workflows, and conversation agents. BYO API keys, no cloud dependencies. +A lightweight local knowledge graph UI with MCP server. Connect your AI coding agents to a personal knowledge base. BYO API keys, no cloud dependencies. -**Full Documentation:** [ra-h.app/docs](https://ra-h.app/docs) +## What is RA-H Light? + +RA-H Light is a stripped-down version of RA-H focused on being a **knowledge management backend for AI agents**. It provides: + +- **2-panel UI** – Nodes list + focus panel for viewing/editing knowledge +- **SQLite + sqlite-vec** – Local vector database with semantic search +- **MCP Server** – Connect Claude Code, Cursor, or any MCP-compatible AI assistant +- **Workflows** – Editable JSON workflows for multi-step operations + +**What's removed:** Built-in chat agents, voice features, delegation system. RA-H Light is designed for technical users who want to bring their own AI agents via MCP. ## Platform Support | Platform | Status | |----------|--------| -| macOS (Apple Silicon) | ✅ Supported | -| macOS (Intel) | ✅ Supported | -| Linux | 🚧 Coming (requires manual sqlite-vec build) | -| Windows | 🚧 Coming (requires manual sqlite-vec build) | +| macOS (Apple Silicon) | Supported | +| macOS (Intel) | Supported | +| Linux | Requires manual sqlite-vec build | +| Windows | Requires manual sqlite-vec build | ## Quick Start @@ -24,30 +33,65 @@ scripts/dev/bootstrap-local.sh npm run dev ``` -Open http://localhost:3000 → **Settings → API Keys** → add your OpenAI/Anthropic keys. +Open http://localhost:3000 → **Settings → API Keys** → add your OpenAI key (for embeddings). -## Features +## Connecting AI Agents via MCP -- **3-Panel interface** – Nodes, focus, and chat in one view -- **BYO keys** – Your Anthropic/OpenAI keys only; nothing sent to RA-H -- **Local SQLite + sqlite-vec** – Semantic search and embeddings on your machine -- **Content extraction** – YouTube, PDF, web pipelines included -- **Workflows** – Editable JSON workflows for common tasks -- **MCP Server** – Connect Claude Code, ChatGPT, or any MCP-compatible assistant +RA-H Light exposes an MCP server that external AI assistants can use to read/write your knowledge graph. + +### Claude Code Integration + +Add to your Claude Code settings: + +```json +{ + "mcpServers": { + "rah": { + "command": "node", + "args": ["/path/to/ra-h_os/apps/mcp-server/stdio-server.js"] + } + } +} +``` + +### Available MCP Tools + +| Tool | Description | +|------|-------------| +| `rah_add_node` | Create a new knowledge node | +| `rah_search_nodes` | Search nodes by text | +| `rah_update_node` | Update an existing node | +| `rah_get_nodes` | Get nodes by ID | +| `rah_create_edge` | Connect two nodes | +| `rah_query_edges` | Find connections | +| `rah_update_edge` | Update a connection | +| `rah_create_dimension` | Create a tag/category | +| `rah_update_dimension` | Update a dimension | +| `rah_delete_dimension` | Delete a dimension | +| `rah_search_embeddings` | Semantic vector search | + +### HTTP MCP Server + +For non-stdio clients, start the HTTP server: + +```bash +node apps/mcp-server/server.js +``` + +Listens on `http://127.0.0.1:44145/mcp` by default. ## Project Layout ``` app/ Next.js App Router src/ - components/ UI - services/ Agents, embeddings, ingestion, storage - tools/ Agent tools - config/ Prompts, workflows -apps/mcp-server/ MCP server for external AI assistants -docs/ Local docs (mirrors ra-h.app/docs) + components/ UI components + services/ Database, embeddings, workflows + tools/ Available tools for workflows +apps/mcp-server/ MCP server (stdio + HTTP) +docs/ Local documentation scripts/ Dev helpers -vendor/ Pre-built binaries (sqlite-vec, yt-dlp) +vendor/ Pre-built binaries (sqlite-vec) ``` ## Commands @@ -62,31 +106,20 @@ vendor/ Pre-built binaries (sqlite-vec, yt-dlp) ## Documentation -**Primary:** [ra-h.app/docs](https://ra-h.app/docs) - -Local reference: -- [docs/0_overview.md](docs/0_overview.md) – Overview -- [docs/1_architecture.md](docs/1_architecture.md) – Architecture +- [docs/0_overview.md](docs/0_overview.md) – System overview - [docs/2_schema.md](docs/2_schema.md) – Database schema -- [docs/8_mcp.md](docs/8_mcp.md) – MCP server setup -- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) – Common issues +- [docs/8_mcp.md](docs/8_mcp.md) – MCP server details ## Linux/Windows Setup -The bundled `sqlite-vec` and `yt-dlp` binaries are macOS-only. For other platforms: +The bundled `sqlite-vec` binary is macOS-only. For other platforms: -**sqlite-vec** (required for vector search): 1. Clone https://github.com/asg017/sqlite-vec 2. Build for your platform 3. Place at `vendor/sqlite-extensions/vec0.so` (Linux) or `vec0.dll` (Windows) 4. Set `SQLITE_VEC_EXTENSION_PATH` in `.env.local` -**yt-dlp** (required for YouTube extraction): -1. Download from https://github.com/yt-dlp/yt-dlp/releases -2. Place at `vendor/bin/yt-dlp` -3. `chmod +x vendor/bin/yt-dlp` (Linux) - -Without sqlite-vec: UI, node CRUD, basic search, chat, and content extraction still work. Vector/semantic search requires it. +Without sqlite-vec: UI, node CRUD, and basic search still work. Vector/semantic search requires it. ## Contributing