docs: update documentation for RA-H Light
- Rewrite 0_overview.md for 2-panel UI + MCP focus - Delete 1_architecture.md (agent hierarchy no longer applies) - Delete 3_context-and-memory.md (agent context no longer applies) - Rewrite 4_tools-and-workflows.md for MCP tools only - Rewrite 6_ui.md for 2-panel layout - Delete 7_voice.md (voice removed) - Update 8_mcp.md with correct tool list (11 tools) - Rewrite 9_open-source.md for RA-H Light - Update README.md with new doc structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
“BeeRad”
co-authored by
Claude Opus 4.5
Claude Opus 4.5
parent
ea61ef1023
commit
f383d770ca
+52
-36
@@ -1,66 +1,82 @@
|
||||
# RA-H Overview
|
||||
# RA-H Light Overview
|
||||
|
||||
## What is RA-H?
|
||||
## What is RA-H Light?
|
||||
|
||||
RA-H is an AI-powered knowledge management system designed for researchers, thinkers, and anyone who works with ideas. It learns how you think and helps connect ideas across your knowledge base.
|
||||
RA-H Light is a minimal knowledge graph UI with MCP server integration. It provides a local-first knowledge management system designed to be extended by external AI agents via the Model Context Protocol.
|
||||
|
||||
**Website:** [ra-h.app](https://ra-h.app)
|
||||
**Open Source:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os)
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
**Non-prescriptive & emergent** — The system doesn't force you into folders or predefined categories. Organization emerges naturally from your actual content. The structure adapts to how you think, not the other way around.
|
||||
**Local-first** — Your knowledge network belongs to you. Everything runs locally in a SQLite database you control.
|
||||
|
||||
**Everything is connected** — Every piece of knowledge can potentially connect to any other. Connections aren't just links — they carry context, explanation, and meaning.
|
||||
**Agent-agnostic** — No built-in AI chat. Instead, RA-H Light exposes an MCP server that any AI agent (Claude Code, custom agents) can connect to.
|
||||
|
||||
**Local-first** — Your knowledge network belongs to you, not a platform. Your thinking, research, and connections all belong to you in a portable format you control.
|
||||
|
||||
**Human + AI** — You guide, AI assists. Create custom workflows. Always in control of your knowledge.
|
||||
**Simple & focused** — 2-panel UI for browsing and editing your knowledge graph. No bloat.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Frontend:** Next.js 15, TypeScript, Tailwind CSS
|
||||
- **Database:** SQLite + sqlite-vec (vector search)
|
||||
- **AI Models:** Anthropic Claude + OpenAI GPT via Vercel AI SDK
|
||||
- **Desktop:** Tauri (Mac app)
|
||||
- **Embeddings:** OpenAI (BYO API key)
|
||||
- **MCP Server:** Local connector for Claude Code and external agents
|
||||
|
||||
## Current Status
|
||||
## What's Included
|
||||
|
||||
- **Version:** v0.1.21 (January 2026)
|
||||
- **Platforms:**
|
||||
- Mac app (download at [ra-h.app/download](https://ra-h.app/download))
|
||||
- Open source self-hosted (BYO API keys)
|
||||
- **License:** MIT (open source version)
|
||||
- 2-panel UI (nodes list + focus panel)
|
||||
- Node/Edge/Dimension CRUD
|
||||
- Full-text and semantic search
|
||||
- MCP server with 11 tools
|
||||
- Workflows system
|
||||
- PDF extraction
|
||||
- Graph visualization (Map view)
|
||||
- BYO API keys
|
||||
|
||||
## Two Ways to Use RA-H
|
||||
## What's NOT Included
|
||||
|
||||
| Version | Best For | Get It |
|
||||
|---------|----------|--------|
|
||||
| **Mac App** | Most users. One-click install, auto-updates, optional subscription features | [ra-h.app/download](https://ra-h.app/download) |
|
||||
| **Open Source** | Developers, self-hosters, contributors. BYO API keys, full control | [GitHub](https://github.com/bradwmorris/ra-h_os) |
|
||||
- Chat interface (use external agents via MCP)
|
||||
- Voice features
|
||||
- Built-in AI agents
|
||||
- Auth/subscription system
|
||||
- Desktop packaging
|
||||
|
||||
Both versions use the same core codebase. The Mac app adds packaging, auth, and subscription features. The open source version is fully functional with your own API keys.
|
||||
## Two-Panel Layout
|
||||
|
||||
## Key Features
|
||||
```
|
||||
┌─────────────┬─────────────────────────┐
|
||||
│ NODES │ FOCUS │
|
||||
│ Panel │ Panel │
|
||||
│ │ │
|
||||
│ • Search │ • Node content │
|
||||
│ • Filters │ • Connections │
|
||||
│ • List │ • Dimensions │
|
||||
│ │ │
|
||||
└─────────────┴─────────────────────────┘
|
||||
```
|
||||
|
||||
- **3-panel interface:** Nodes list, Focus view, Helpers panel
|
||||
- **AI agents:** Orchestrator for chat, workflows for deep analysis
|
||||
- **Graph database:** Nodes and edges with semantic search
|
||||
- **MCP server:** Connect Claude Code and other external agents
|
||||
- **Workflows:** Code-first automation (Integrate, custom workflows)
|
||||
- **Extraction tools:** YouTube, websites, PDFs
|
||||
## MCP Integration
|
||||
|
||||
RA-H Light is designed to be the knowledge backend for your AI workflows:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "node",
|
||||
"args": ["/path/to/ra-h_os/apps/mcp-server/stdio-server.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Available tools: `rah_add_node`, `rah_search_nodes`, `rah_update_node`, `rah_get_nodes`, `rah_create_edge`, `rah_query_edges`, `rah_update_edge`, `rah_create_dimension`, `rah_update_dimension`, `rah_delete_dimension`, `rah_search_embeddings`
|
||||
|
||||
## Documentation
|
||||
|
||||
| Doc | Description |
|
||||
|-----|-------------|
|
||||
| [Architecture](./1_architecture.md) | Agent hierarchy, system design |
|
||||
| [Schema](./2_schema.md) | Database schema, node/edge structure |
|
||||
| [Context & Memory](./3_context-and-memory.md) | How context flows through the system |
|
||||
| [Tools & Workflows](./4_tools-and-workflows.md) | Available tools, workflow system |
|
||||
| [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation framework |
|
||||
| [Tools & Workflows](./4_tools-and-workflows.md) | Available MCP tools, workflow system |
|
||||
| [UI](./6_ui.md) | Component structure, panels, views |
|
||||
| [Voice](./7_voice.md) | Voice interface (STT/TTS) |
|
||||
| [MCP](./8_mcp.md) | External agent connector setup |
|
||||
| [Open Source](./9_open-source.md) | Sync strategy between repos |
|
||||
| [Troubleshooting](./TROUBLESHOOTING.md) | Common issues and fixes |
|
||||
|
||||
@@ -1,112 +0,0 @@
|
||||
# System Architecture
|
||||
|
||||
> How RA-H's AI agents work together to manage your knowledge.
|
||||
|
||||
**How it works:** RA-H has three AI agents: orchestrators (ra-h/ra-h-easy) handle your conversations and delegate work, wise-rah executes multi-step workflows, and mini-rah handles background tasks. All agents can read your knowledge graph; only some can write.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
RA-H uses a multi-agent architecture with three specialized AI agents that collaborate to manage your knowledge base. The system is built around **nodes** (knowledge items), **edges** (relationships), and **dimensions** (categories).
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Nodes
|
||||
Knowledge items stored in the database (papers, ideas, people, projects, videos, tweets, etc). Each node has:
|
||||
- **Title** and **content**
|
||||
- **Dimensions** (multi-tag categorization)
|
||||
- **Metadata** (structured JSON)
|
||||
- **Embeddings** (for semantic search)
|
||||
- **Links** (for external sources)
|
||||
|
||||
### Edges
|
||||
Directed relationships between nodes. Edges capture how nodes connect ("relates to", "inspired by", etc).
|
||||
|
||||
### Dimensions
|
||||
Multi-select categorization tags. Nodes can have multiple dimensions. Some dimensions can be marked as "priority" for focused context.
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
### Orchestrator Agents (Easy/Hard Mode)
|
||||
|
||||
**ra-h-easy (Easy Mode - Default)**
|
||||
- **Model:** GPT-5 Mini (`openai/gpt-5-mini`)
|
||||
- **Purpose:** Fast, low-latency orchestration for everyday tasks
|
||||
- **Caching:** OpenAI implicit caching
|
||||
- **Reasoning:** `reasoning_effort: light` for speed
|
||||
|
||||
**ra-h (Hard Mode)**
|
||||
- **Model:** Claude Sonnet 4.5 (`anthropic/claude-sonnet-4.5`)
|
||||
- **Purpose:** Deep reasoning for complex tasks
|
||||
- **Caching:** Anthropic explicit prompt caching
|
||||
- **Reasoning:** Stronger analytical capabilities
|
||||
|
||||
**Tools Available:**
|
||||
- `queryNodes`, `queryEdge`, `searchContentEmbeddings`
|
||||
- `webSearch`, `think`
|
||||
- `executeWorkflow` (delegates to wise-rah)
|
||||
- `createNode`, `updateNode`, `createEdge`, `updateEdge`
|
||||
- `youtubeExtract`, `websiteExtract`, `paperExtract`
|
||||
|
||||
**Mode Switching:**
|
||||
Users toggle via UI (⚡ Easy / 🔥 Hard). Choice persists in localStorage. **Seamless mid-conversation switching** - context maintained across mode changes.
|
||||
|
||||
### Wise RA-H (Workflow Executor)
|
||||
|
||||
**wise-rah**
|
||||
- **Model:** GPT-5 (`openai/gpt-5`)
|
||||
- **Purpose:** Executes predefined workflows (integrate, deep analysis)
|
||||
- **Direct write access:** Calls `updateNode` directly (no delegation)
|
||||
- **Context isolation:** Returns summaries only to orchestrator
|
||||
|
||||
**Tools Available:**
|
||||
- `queryNodes`, `getNodesById`, `queryEdge`, `searchContentEmbeddings`
|
||||
- `webSearch`, `think`
|
||||
- `updateNode` (append-only, enforced at tool level)
|
||||
|
||||
**Key Workflows:**
|
||||
- **Integrate:** Database-wide connection discovery (5-step: plan → ground → search → contextualize → append)
|
||||
|
||||
### Mini RA-H (Delegate Workers)
|
||||
|
||||
**mini-rah**
|
||||
- **Model:** GPT-4o Mini (`openai/gpt-4o-mini`)
|
||||
- **Purpose:** Spawned for write operations, extraction, batch tasks
|
||||
- **Execution:** Isolated context, returns summaries only
|
||||
|
||||
**Tools Available:**
|
||||
- All read tools + `createNode`, `updateNode`, `createEdge`, `updateEdge`
|
||||
- Extraction tools (`youtubeExtract`, `websiteExtract`, `paperExtract`)
|
||||
|
||||
## Prompt Caching
|
||||
|
||||
**Anthropic (Claude):**
|
||||
- Explicit cache control blocks in system prompts
|
||||
- Caches tool definitions, workflows, base context
|
||||
|
||||
**OpenAI (GPT-5/4o):**
|
||||
- Implicit caching based on prefix matching
|
||||
- Optimized prompts for cache reuse
|
||||
- `reasoning_effort` parameter for speed/quality tradeoff
|
||||
|
||||
## Context Hygiene
|
||||
|
||||
**Orchestrator:**
|
||||
- Maintains full conversation history
|
||||
- Sees auto-context (top 10 connected nodes) + focused node
|
||||
- Delegates isolation ensures clean context
|
||||
|
||||
**Workers (wise-rah/mini-rah):**
|
||||
- Execute in isolated sessions
|
||||
- Return structured summaries only
|
||||
- Do NOT pollute orchestrator context with tool execution details
|
||||
|
||||
## UI Integration
|
||||
|
||||
Users interact with a single interface that automatically routes requests to the appropriate agent based on:
|
||||
- **Mode selection** (Easy/Hard)
|
||||
- **Workflow triggers** (executeWorkflow → wise-rah)
|
||||
- **Delegation needs** (mini-rah spawned in background)
|
||||
|
||||
Orchestrators see **auto-context** (your 10 most-connected nodes) plus the **focused node** for consistent knowledge access. See [Context & Memory](./3_context-and-memory.md) for details.
|
||||
@@ -1,161 +0,0 @@
|
||||
# Context & Memory
|
||||
|
||||
> How RA-H decides what information to show the AI during conversations.
|
||||
|
||||
**How it works:** RA-H automatically identifies your 10 most-connected knowledge nodes (by edge count) and shares their titles with the AI as background context. When you focus on a specific node, the AI also sees a preview of that content. This means the AI always knows about your most important ideas without you having to manually select them.
|
||||
|
||||
---
|
||||
|
||||
## Context System Overview
|
||||
|
||||
Every conversation includes context assembled by the **context builder**. This context tells the AI about your knowledge base, available tools, and what you're currently working on.
|
||||
|
||||
### What Gets Included
|
||||
|
||||
| Block | Contents | Cached? |
|
||||
|-------|----------|---------|
|
||||
| **Base Context** | How nodes, edges, dimensions work; formatting rules | ✅ Yes |
|
||||
| **Agent Instructions** | Role-specific prompts (ra-h, ra-h-easy, wise-rah, mini-rah) | ✅ Yes |
|
||||
| **Tool Definitions** | Available tools and their parameters | ✅ Yes |
|
||||
| **Workflow Definitions** | Available workflows (orchestrators only) | ✅ Yes |
|
||||
| **Background Context** | Top 10 most-connected nodes (if enabled) | ✅ Yes |
|
||||
| **Focused Nodes** | Currently open node(s) with content previews | ❌ No |
|
||||
|
||||
---
|
||||
|
||||
## Auto-Context System
|
||||
|
||||
Auto-context automatically includes your most important knowledge in every conversation. It replaces the old manual "pinning" system.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Toggle:** Enable in Settings → Context tab
|
||||
2. **Query:** Finds top 10 nodes by edge count (most connections = most important)
|
||||
3. **Format:** Shows `[NODE:id:"title"] (edges: X)` for each hub node
|
||||
4. **Agent behavior:** Agents see titles only; they call `queryNodes` or `getNodesById` when they need full content
|
||||
|
||||
### The Query
|
||||
|
||||
```sql
|
||||
SELECT n.id, n.title, COUNT(DISTINCT e.id) AS edge_count
|
||||
FROM nodes n
|
||||
LEFT JOIN edges e ON (e.from_node_id = n.id OR e.to_node_id = n.id)
|
||||
WHERE n.type IS NULL OR n.type != 'memory'
|
||||
GROUP BY n.id
|
||||
ORDER BY edge_count DESC, n.updated_at DESC
|
||||
LIMIT 10
|
||||
```
|
||||
|
||||
**Tie-breaking:** When nodes have equal edge counts, most recently updated wins.
|
||||
|
||||
### Settings Storage
|
||||
|
||||
**Location:** `~/Library/Application Support/RA-H/config/settings.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"autoContextEnabled": true,
|
||||
"lastPinnedMigration": "2025-12-09T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Legacy migration:** If you had pinned nodes before the auto-context update, the system automatically enabled auto-context on first run.
|
||||
|
||||
### Context Block Format
|
||||
|
||||
When enabled, agents see this in their system prompt:
|
||||
|
||||
```
|
||||
=== BACKGROUND CONTEXT ===
|
||||
Top 10 most-connected nodes (important knowledge hubs). Use queryNodes/getNodesById if relevant.
|
||||
|
||||
[NODE:1573:"building ra-h - knowledge management system"] (edges: 47)
|
||||
[NODE:4436:"Continual learning explains some interesting phenomena"] (edges: 32)
|
||||
[NODE:3014:"Multi-Agent Research Systems: Insights from Simon Willison"] (edges: 28)
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Focused Nodes
|
||||
|
||||
Focused nodes are the node(s) you currently have open in the Focus panel.
|
||||
|
||||
### What Agents See
|
||||
|
||||
- **Primary focused node:** The active tab
|
||||
- **Additional focused nodes:** Other open tabs
|
||||
- **Content preview:** First ~25 words
|
||||
- **Metadata:** Title, ID, link, dimensions, chunk status
|
||||
|
||||
### Example Format
|
||||
|
||||
```
|
||||
=== FOCUSED NODES ===
|
||||
|
||||
### Primary: [NODE:4523:"How RAG systems work"]
|
||||
Preview: Retrieval-augmented generation (RAG) combines information retrieval with language model generation to produce more accurate and grounded responses...
|
||||
Link: https://example.com/rag-systems
|
||||
Dimensions: research, ai, papers
|
||||
Chunk status: chunked (embeddings available)
|
||||
|
||||
### Also Open:
|
||||
- [NODE:4520:"Vector databases explained"] (25 words preview...)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context Caching
|
||||
|
||||
RA-H uses provider-specific caching to reduce costs and latency.
|
||||
|
||||
### Anthropic (Claude)
|
||||
|
||||
- **Explicit cache control:** Blocks marked with `cache_control: { type: 'ephemeral' }`
|
||||
- **What's cached:** Base context, instructions, tools, workflows, background context
|
||||
- **What's NOT cached:** Focused nodes (change too frequently)
|
||||
|
||||
### OpenAI (GPT)
|
||||
|
||||
- **Implicit caching:** Based on prefix matching
|
||||
- **Same structure:** Identical blocks, just no explicit markers
|
||||
- **Optimization:** Prompts structured for maximum cache reuse
|
||||
|
||||
---
|
||||
|
||||
## Agent-Specific Context
|
||||
|
||||
Different agents receive different context based on their role:
|
||||
|
||||
| Agent | Background Context | Workflows | Tools |
|
||||
|-------|-------------------|-----------|-------|
|
||||
| **ra-h / ra-h-easy** (orchestrators) | ✅ Yes | ✅ Yes | All |
|
||||
| **wise-rah** (workflow executor) | ❌ No | ❌ No | Planner tools only |
|
||||
| **mini-rah** (worker) | ❌ No | ❌ No | Executor tools only |
|
||||
|
||||
**Why orchestrators only:** Background context helps with general conversation. Workers execute specific tasks and don't need the full picture.
|
||||
|
||||
---
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `src/services/helpers/contextBuilder.ts` | Assembles system prompts with caching |
|
||||
| `src/services/context/autoContext.ts` | Auto-context query and formatting |
|
||||
| `src/services/settings/autoContextSettings.ts` | Settings read/write helpers |
|
||||
| `src/components/settings/ContextViewer.tsx` | Settings UI for auto-context toggle |
|
||||
|
||||
---
|
||||
|
||||
## Legacy: Memory System (Removed)
|
||||
|
||||
The automatic memory extraction pipeline has been **removed**. Previously, RA-H would analyze conversations and create "memory" nodes automatically. This system was removed because:
|
||||
|
||||
1. Memory nodes cluttered the database
|
||||
2. Quality was inconsistent
|
||||
3. Users preferred explicit knowledge capture
|
||||
|
||||
**Existing memory nodes:** Still in the database but excluded from auto-context (filtered by `type != 'memory'`).
|
||||
|
||||
**Future approach:** Store long-term knowledge as regular nodes with explicit dimensions rather than automatic extraction.
|
||||
+118
-244
@@ -1,217 +1,132 @@
|
||||
# Tools & Workflows
|
||||
|
||||
> What actions the AI can take and how workflows automate multi-step processes.
|
||||
> MCP tools available for external agents and the workflow execution system.
|
||||
|
||||
**How it works:** AI agents have access to tools — functions they can call to read data, create nodes, search content, and more. Workflows are pre-written instruction sets that guide the AI through complex multi-step processes like finding connections across your knowledge base.
|
||||
**How it works:** RA-H Light exposes tools via MCP that external AI agents can call to read, create, and update your knowledge graph. Workflows are pre-written instruction sets that can be executed via the `/api/workflows/execute` endpoint.
|
||||
|
||||
---
|
||||
|
||||
## Tools Overview
|
||||
## MCP Tools
|
||||
|
||||
Tools are organized into three categories:
|
||||
RA-H Light provides 11 MCP tools for external agents:
|
||||
|
||||
| Category | Purpose | Examples |
|
||||
|----------|---------|----------|
|
||||
| **Core** | Read-only graph operations | queryNodes, searchContentEmbeddings |
|
||||
| **Orchestration** | Delegation and reasoning | executeWorkflow, think, webSearch |
|
||||
| **Execution** | Write operations and extraction | createNode, updateNode, youtubeExtract |
|
||||
### Node Operations
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `rah_add_node` | Create a new knowledge node |
|
||||
| `rah_search_nodes` | Search nodes by title, content, or dimensions |
|
||||
| `rah_update_node` | Update an existing node |
|
||||
| `rah_get_nodes` | Get nodes by ID array |
|
||||
|
||||
### Edge Operations
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `rah_create_edge` | Create relationship between nodes |
|
||||
| `rah_query_edges` | Query existing edges |
|
||||
| `rah_update_edge` | Update edge metadata |
|
||||
|
||||
### Dimension Operations
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `rah_create_dimension` | Create a new dimension tag |
|
||||
| `rah_update_dimension` | Update dimension description |
|
||||
| `rah_delete_dimension` | Delete a dimension |
|
||||
|
||||
### Search
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `rah_search_embeddings` | Semantic search across chunk embeddings |
|
||||
|
||||
---
|
||||
|
||||
## Core Tools (All Agents)
|
||||
## Tool Schemas
|
||||
|
||||
Read-only operations available to all agents:
|
||||
|
||||
### queryNodes
|
||||
Search nodes by title, content, or dimensions.
|
||||
### rah_add_node
|
||||
|
||||
```typescript
|
||||
queryNodes({
|
||||
search?: string, // Full-text search
|
||||
dimensions?: string[],// Filter by dimensions
|
||||
limit?: number // Max results (default: 20)
|
||||
})
|
||||
```
|
||||
|
||||
### getNodesById
|
||||
Retrieve full node data by ID array.
|
||||
|
||||
```typescript
|
||||
getNodesById({
|
||||
ids: number[] // Array of node IDs
|
||||
})
|
||||
```
|
||||
|
||||
### queryEdge
|
||||
Inspect existing edges between nodes.
|
||||
|
||||
```typescript
|
||||
queryEdge({
|
||||
from_node_id?: number,
|
||||
to_node_id?: number,
|
||||
limit?: number
|
||||
})
|
||||
```
|
||||
|
||||
### searchContentEmbeddings
|
||||
Semantic search across chunk embeddings.
|
||||
|
||||
```typescript
|
||||
searchContentEmbeddings({
|
||||
query: string, // Search query
|
||||
node_id?: number, // Scope to specific node
|
||||
limit?: number, // Max results
|
||||
threshold?: number // Similarity threshold (0-1)
|
||||
})
|
||||
```
|
||||
|
||||
### queryDimensions
|
||||
Query and filter dimensions.
|
||||
|
||||
```typescript
|
||||
queryDimensions({
|
||||
search?: string, // Filter by name
|
||||
isPriority?: boolean, // Filter locked dimensions only
|
||||
limit?: number
|
||||
})
|
||||
```
|
||||
|
||||
### getDimension
|
||||
Get a single dimension by exact name.
|
||||
|
||||
```typescript
|
||||
getDimension({
|
||||
name: string // Exact dimension name
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Orchestration Tools (Orchestrators Only)
|
||||
|
||||
Tools for reasoning and delegation:
|
||||
|
||||
### webSearch
|
||||
External web search via Tavily.
|
||||
|
||||
```typescript
|
||||
webSearch({
|
||||
query: string,
|
||||
max_results?: number
|
||||
})
|
||||
```
|
||||
|
||||
### think
|
||||
Internal reasoning/planning (logged to metadata, not shown to user).
|
||||
|
||||
```typescript
|
||||
think({
|
||||
thought: string // Reasoning to log
|
||||
})
|
||||
```
|
||||
|
||||
### executeWorkflow
|
||||
Delegate to wise-rah for predefined workflows.
|
||||
|
||||
```typescript
|
||||
executeWorkflow({
|
||||
workflow_key: string // e.g., "integrate"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution Tools (Writers)
|
||||
|
||||
Write operations and content extraction:
|
||||
|
||||
### createNode
|
||||
Create a new knowledge node.
|
||||
|
||||
```typescript
|
||||
createNode({
|
||||
title: string,
|
||||
{
|
||||
title: string, // Required
|
||||
content?: string,
|
||||
description?: string,
|
||||
dimensions?: string[],
|
||||
link?: string,
|
||||
metadata?: object
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### updateNode
|
||||
Append content to existing nodes. **Append-only** — cannot overwrite.
|
||||
### rah_search_nodes
|
||||
|
||||
```typescript
|
||||
updateNode({
|
||||
id: number,
|
||||
content: string // Appended to existing content
|
||||
})
|
||||
{
|
||||
search?: string, // Full-text search
|
||||
dimensions?: string[],// Filter by dimensions
|
||||
limit?: number // Max results (default: 20)
|
||||
}
|
||||
```
|
||||
|
||||
### createEdge
|
||||
Create relationship between nodes.
|
||||
### rah_update_node
|
||||
|
||||
```typescript
|
||||
createEdge({
|
||||
{
|
||||
id: number, // Node ID
|
||||
title?: string,
|
||||
content?: string, // Replaces existing content
|
||||
description?: string,
|
||||
dimensions?: string[],
|
||||
link?: string,
|
||||
metadata?: object
|
||||
}
|
||||
```
|
||||
|
||||
### rah_create_edge
|
||||
|
||||
```typescript
|
||||
{
|
||||
from_node_id: number,
|
||||
to_node_id: number,
|
||||
context?: string // Relationship description
|
||||
})
|
||||
context?: string // Relationship description
|
||||
}
|
||||
```
|
||||
|
||||
### updateEdge
|
||||
Modify edge metadata.
|
||||
### rah_search_embeddings
|
||||
|
||||
```typescript
|
||||
updateEdge({
|
||||
id: number,
|
||||
context?: string,
|
||||
user_feedback?: number
|
||||
})
|
||||
```
|
||||
|
||||
### Dimension Tools
|
||||
|
||||
```typescript
|
||||
createDimension({ name: string, description?: string })
|
||||
updateDimension({ name: string, description?: string })
|
||||
lockDimension({ name: string }) // Make priority dimension
|
||||
unlockDimension({ name: string }) // Remove priority status
|
||||
deleteDimension({ name: string })
|
||||
```
|
||||
|
||||
### Extraction Tools
|
||||
|
||||
```typescript
|
||||
youtubeExtract({ url: string }) // Extract transcript
|
||||
websiteExtract({ url: string }) // Extract page content
|
||||
paperExtract({ url: string }) // Extract PDF text
|
||||
{
|
||||
query: string, // Search query
|
||||
node_id?: number, // Scope to specific node
|
||||
limit?: number, // Max results
|
||||
threshold?: number // Similarity threshold (0-1)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Access by Agent
|
||||
## API Routes
|
||||
|
||||
| Agent | Core | Orchestration | Execution |
|
||||
|-------|------|---------------|-----------|
|
||||
| **ra-h / ra-h-easy** | ✅ All | webSearch, think, executeWorkflow | ✅ All |
|
||||
| **wise-rah** | ✅ All | webSearch, think, delegateToMiniRAH | updateNode, createEdge |
|
||||
| **mini-rah** | ✅ All | webSearch, think | ✅ All |
|
||||
RA-H Light exposes REST APIs that MCP tools call internally:
|
||||
|
||||
| Route | Method | Purpose |
|
||||
|-------|--------|---------|
|
||||
| `/api/nodes` | GET/POST | List/create nodes |
|
||||
| `/api/nodes/[id]` | GET/PUT/DELETE | Node CRUD |
|
||||
| `/api/nodes/search` | POST | Search nodes |
|
||||
| `/api/edges` | GET/POST | List/create edges |
|
||||
| `/api/edges/[id]` | GET/PUT/DELETE | Edge CRUD |
|
||||
| `/api/dimensions` | GET/POST | List/create dimensions |
|
||||
| `/api/dimensions/search` | GET | Search dimensions |
|
||||
| `/api/workflows/execute` | POST | Execute workflow |
|
||||
|
||||
---
|
||||
|
||||
## Workflows
|
||||
|
||||
Workflows are multi-step instruction sets executed by wise-rah.
|
||||
Workflows are pre-written instruction sets stored in `~/Library/Application Support/RA-H/workflows/`.
|
||||
|
||||
### User-Editable Workflows
|
||||
|
||||
**Users can create, edit, and delete workflows** from Settings → Workflows tab.
|
||||
|
||||
**Storage:** `~/Library/Application Support/RA-H/workflows/`
|
||||
|
||||
**Format:** JSON files with this structure:
|
||||
### Workflow Format
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -224,93 +139,52 @@ Workflows are multi-step instruction sets executed by wise-rah.
|
||||
}
|
||||
```
|
||||
|
||||
### How Workflows Work
|
||||
### Executing Workflows
|
||||
|
||||
1. User says "run integrate workflow" (or similar)
|
||||
2. Orchestrator calls `executeWorkflow({ workflow_key: 'integrate' })`
|
||||
3. System spawns wise-rah session with workflow instructions
|
||||
4. wise-rah executes steps autonomously (30-60+ seconds)
|
||||
5. wise-rah returns summary to orchestrator
|
||||
6. Orchestrator shows result to user
|
||||
Via API:
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/workflows/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"workflow_key": "integrate", "focused_node_id": 123}'
|
||||
```
|
||||
|
||||
### Built-in Workflows
|
||||
|
||||
#### Integrate
|
||||
|
||||
**Key:** `integrate`
|
||||
**Purpose:** Database-wide connection discovery
|
||||
**Cost:** ~$0.18/execution
|
||||
|
||||
**5-Step Process:**
|
||||
|
||||
1. **Plan** — Call `think` to outline approach
|
||||
2. **Ground** — Extract entities (names, projects, concepts) from focused node
|
||||
3. **Search** — Database-wide search using extracted entities
|
||||
4. **Contextualize** — Brief relevance explanation
|
||||
5. **Append** — Call `updateNode` ONCE with Integration Analysis section
|
||||
|
||||
**Output Format:**
|
||||
|
||||
```markdown
|
||||
## Integration Analysis
|
||||
|
||||
[2-3 sentences: what this node is, why it matters]
|
||||
|
||||
**Database Connections:**
|
||||
- [NODE:123:"Title"] — [why relevant]
|
||||
- [NODE:456:"Title"] — [why relevant]
|
||||
...
|
||||
|
||||
**Relevance:** [1-2 sentences connecting to your context]
|
||||
```
|
||||
**Integrate** — Database-wide connection discovery. Finds related nodes and suggests connections.
|
||||
|
||||
### Creating Custom Workflows
|
||||
|
||||
1. Go to Settings → Workflows
|
||||
2. Click "New Workflow"
|
||||
3. Fill in:
|
||||
- **Key** — unique identifier (lowercase, no spaces)
|
||||
- **Display Name** — shown in UI
|
||||
- **Description** — what it does
|
||||
- **Instructions** — the prompt for wise-rah
|
||||
- **Requires Focused Node** — whether a node must be selected
|
||||
4. Save
|
||||
|
||||
### Workflow Instructions Tips
|
||||
|
||||
- Be explicit about steps and expected output
|
||||
- Reference tools by name (wise-rah has: queryNodes, searchContentEmbeddings, updateNode, createEdge, webSearch, think)
|
||||
- Specify output format precisely
|
||||
- Include guardrails ("call updateNode exactly once")
|
||||
1. Create a JSON file in `~/Library/Application Support/RA-H/workflows/`
|
||||
2. Define key, displayName, description, instructions
|
||||
3. Set `enabled: true`
|
||||
4. Execute via API
|
||||
|
||||
---
|
||||
|
||||
## Tool Registry
|
||||
## Database Tools (Internal)
|
||||
|
||||
**Location:** `src/tools/infrastructure/registry.ts`
|
||||
These tools are used by the workflow executor and API routes:
|
||||
|
||||
**Structure:**
|
||||
|
||||
```typescript
|
||||
TOOL_SETS = {
|
||||
core: { queryNodes, getNodesById, queryEdge, queryDimensions, getDimension, searchContentEmbeddings },
|
||||
orchestration: { webSearch, think, delegateToMiniRAH, executeWorkflow, ... },
|
||||
execution: { createNode, updateNode, createEdge, updateEdge, youtubeExtract, websiteExtract, paperExtract, ... }
|
||||
}
|
||||
```
|
||||
| Tool | File | Purpose |
|
||||
|------|------|---------|
|
||||
| `queryNodes` | `src/tools/database/queryNodes.ts` | Search nodes |
|
||||
| `createNode` | `src/tools/database/createNode.ts` | Create node |
|
||||
| `updateNode` | `src/tools/database/updateNode.ts` | Update node |
|
||||
| `deleteNode` | `src/tools/database/deleteNode.ts` | Delete node |
|
||||
| `getNodesById` | `src/tools/database/getNodesById.ts` | Get by ID |
|
||||
| `createEdge` | `src/tools/database/createEdge.ts` | Create edge |
|
||||
| `updateEdge` | `src/tools/database/updateEdge.ts` | Update edge |
|
||||
| `queryEdge` | `src/tools/database/queryEdge.ts` | Query edges |
|
||||
| `queryDimensions` | `src/tools/database/queryDimensions.ts` | Query dimensions |
|
||||
| `searchContentEmbeddings` | `src/tools/other/searchContentEmbeddings.ts` | Semantic search |
|
||||
|
||||
---
|
||||
|
||||
## Key Design Decisions
|
||||
## Key Files
|
||||
|
||||
### Append-Only Updates
|
||||
|
||||
`updateNode` is **append-only** — it cannot overwrite existing content. This prevents AI from accidentally destroying knowledge. The tool-level enforcement means workflows can't bypass this restriction.
|
||||
|
||||
### No Workflow Delegation Loops
|
||||
|
||||
wise-rah cannot call `executeWorkflow` or delegate to other wise-rah instances. This prevents infinite loops and keeps execution bounded.
|
||||
|
||||
### Isolated Execution
|
||||
|
||||
Workers (wise-rah, mini-rah) execute in isolated sessions. They return structured summaries only — they don't pollute orchestrator context with execution details.
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `apps/mcp-server/server.js` | HTTP MCP server |
|
||||
| `apps/mcp-server/stdio-server.js` | STDIO MCP server |
|
||||
| `src/tools/infrastructure/registry.ts` | Tool registry |
|
||||
| `src/services/agents/workflowExecutor.ts` | Workflow execution |
|
||||
|
||||
+20
-83
@@ -1,23 +1,23 @@
|
||||
# User Interface
|
||||
|
||||
> How to navigate and use RA-H's interface.
|
||||
> How to navigate and use RA-H Light's interface.
|
||||
|
||||
**How it works:** RA-H uses a 3-panel layout: browse nodes on the left, work with focused content in the middle, and chat with AI on the right. The chat panel is collapsible (Cmd+\\). Settings give you access to workflows, database views, a knowledge map, and more.
|
||||
**How it works:** RA-H Light uses a 2-panel layout: browse nodes on the left, work with focused content on the right. Settings give you access to workflows, database views, a knowledge map, and more.
|
||||
|
||||
---
|
||||
|
||||
## 3-Panel Layout
|
||||
## 2-Panel Layout
|
||||
|
||||
```
|
||||
┌─────────────┬─────────────────────────┬─────────────────┐
|
||||
│ NODES │ FOCUS │ HELPERS │
|
||||
│ Panel │ Panel │ Panel │
|
||||
│ │ │ │
|
||||
│ • Search │ • Tabbed workspace │ • AI chat │
|
||||
│ • Filters │ • Node content │ • Easy/Hard │
|
||||
│ • Folders │ • Connections │ • Delegations │
|
||||
│ │ │ │
|
||||
└─────────────┴─────────────────────────┴─────────────────┘
|
||||
┌─────────────┬─────────────────────────┐
|
||||
│ NODES │ FOCUS │
|
||||
│ Panel │ Panel │
|
||||
│ │ │
|
||||
│ • Search │ • Tabbed workspace │
|
||||
│ • Filters │ • Node content │
|
||||
│ • Folders │ • Connections │
|
||||
│ │ │
|
||||
└─────────────┴─────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
@@ -95,14 +95,14 @@ Save filter + view combinations:
|
||||
|
||||
---
|
||||
|
||||
## Middle Panel: Focus
|
||||
## Right Panel: Focus
|
||||
|
||||
Active workspace for the node(s) you're working with.
|
||||
|
||||
### Tabbed Interface
|
||||
|
||||
- **Primary tab** — Main focused node
|
||||
- **Additional tabs** — Related nodes opened from chat
|
||||
- **Additional tabs** — Related nodes opened from links
|
||||
- **Tab controls** — Close (×), reorder, switch
|
||||
|
||||
### Node Detail View
|
||||
@@ -124,54 +124,6 @@ Active workspace for the node(s) you're working with.
|
||||
|
||||
---
|
||||
|
||||
## Right Panel: Helpers
|
||||
|
||||
AI conversation interface.
|
||||
|
||||
### Chat Interface
|
||||
|
||||
- **Message history** — User + assistant messages
|
||||
- **Tool call visibility** — Collapsed by default, expandable
|
||||
- **Token/cost tracking** — Per-message usage
|
||||
- **Node references** — Auto-linked `[NODE:id:"title"]`
|
||||
|
||||
### Mode Toggle
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ ⚡ Easy │ 🔥 Hard │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
| Mode | Model | Use Case |
|
||||
|------|-------|----------|
|
||||
| **Easy** | GPT-5 Mini | Fast, everyday tasks |
|
||||
| **Hard** | Claude Sonnet 4.5 | Deep reasoning, complex analysis |
|
||||
|
||||
Mode persists in localStorage. Switch mid-conversation seamlessly.
|
||||
|
||||
### Collapsible Panel
|
||||
|
||||
- **Toggle:** Cmd+\\ (Mac) / Ctrl+\\ (Windows)
|
||||
- **Collapsed state:** 48px rail with expand button
|
||||
- **State persists:** Remembers your preference
|
||||
|
||||
---
|
||||
|
||||
## Quick Add
|
||||
|
||||
Bottom of the Helpers panel. Three modes:
|
||||
|
||||
| Mode | Icon | Purpose |
|
||||
|------|------|---------|
|
||||
| **Link** | 🔗 | Paste URLs for auto-extraction |
|
||||
| **Note** | 📄 | Quick note, no AI processing |
|
||||
| **Chat** | 💬 | Paste conversations |
|
||||
|
||||
Auto-detects mode based on input (URLs trigger Link mode).
|
||||
|
||||
---
|
||||
|
||||
## Search (Cmd+K)
|
||||
|
||||
Global search modal with 4-tier relevance:
|
||||
@@ -190,19 +142,15 @@ Global search modal with 4-tier relevance:
|
||||
|
||||
## Settings Panel
|
||||
|
||||
**Access:** Settings cog icon (top-right, green ring)
|
||||
**Access:** Settings cog icon (top-right)
|
||||
|
||||
**Size:** 88vw × 90vh with glass effect
|
||||
|
||||
### Tabs (in order)
|
||||
### Tabs
|
||||
|
||||
| Tab | Purpose |
|
||||
|-----|---------|
|
||||
| **Subscription** | Account status, usage, upgrade options |
|
||||
| **API Keys** | Configure Anthropic/OpenAI/Tavily keys |
|
||||
| **Workflows** | View, edit, create, delete workflows |
|
||||
| **Tools** | View available agent tools |
|
||||
| **Context** | Auto-context toggle, view hub nodes |
|
||||
| **API Keys** | Configure OpenAI/Tavily keys |
|
||||
| **Workflows** | View, edit, create workflows |
|
||||
| **Tools** | View available tools |
|
||||
| **Map** | Knowledge graph visualization |
|
||||
| **Database** | Full node table with filters/sorting |
|
||||
| **Logs** | Activity feed (last 100 entries) |
|
||||
@@ -221,11 +169,6 @@ Visual graph of your knowledge network.
|
||||
- Click node to highlight connections
|
||||
- Selection shows connected nodes in green
|
||||
|
||||
**Styling:**
|
||||
- Cluster layout with golden angle spiral
|
||||
- Transparent flat circles
|
||||
- Green rings for selected/connected nodes
|
||||
|
||||
---
|
||||
|
||||
## Database View
|
||||
@@ -236,7 +179,6 @@ Full table view of all nodes.
|
||||
- Node (title + ID)
|
||||
- Dimensions (folder badges)
|
||||
- Edges (count)
|
||||
- Status (context hub indicator)
|
||||
- Updated (timestamp)
|
||||
|
||||
**Features:**
|
||||
@@ -254,7 +196,7 @@ Each dimension can have a custom Lucide icon.
|
||||
**To set:**
|
||||
1. Open Folder View → hover over dimension
|
||||
2. Click edit (pencil) icon
|
||||
3. Choose icon from 115 curated options
|
||||
3. Choose icon from curated options
|
||||
4. Icons persist in localStorage
|
||||
|
||||
---
|
||||
@@ -264,13 +206,10 @@ Each dimension can have a custom Lucide icon.
|
||||
**Format:** `[NODE:id:"title"]`
|
||||
|
||||
**Rendering:**
|
||||
- Clickable labels in chat messages
|
||||
- Clickable labels in node content
|
||||
- Hover shows preview tooltip
|
||||
- Click opens in Focus panel
|
||||
|
||||
AI agents automatically use this format for all node mentions.
|
||||
|
||||
---
|
||||
|
||||
## Keyboard Shortcuts
|
||||
@@ -278,7 +217,6 @@ AI agents automatically use this format for all node mentions.
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Cmd+K` | Open search |
|
||||
| `Cmd+\\` | Toggle chat panel |
|
||||
| `Escape` | Close modals/overlays |
|
||||
|
||||
---
|
||||
@@ -288,7 +226,6 @@ AI agents automatically use this format for all node mentions.
|
||||
### Colors
|
||||
|
||||
- **Background:** `#0a0a0a` (near black)
|
||||
- **Panels:** Subtle gradients distinguishing left/middle/right
|
||||
- **Accent:** Green (`#22c55e`) for actions, selections
|
||||
- **Text:** White (primary), neutral-400 (secondary)
|
||||
|
||||
|
||||
-125
@@ -1,125 +0,0 @@
|
||||
# Voice Interface
|
||||
|
||||
> Talk to RA-H instead of typing.
|
||||
|
||||
**How it works:** Press the microphone button to speak your message. RA-H converts your speech to text using OpenAI's Realtime API, sends it to the AI, and speaks the response back using text-to-speech. All processing requires an internet connection.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The voice interface lets you have spoken conversations with RA-H. It uses:
|
||||
|
||||
- **Speech-to-Text (STT):** OpenAI Realtime API for low-latency transcription
|
||||
- **Text-to-Speech (TTS):** OpenAI TTS for natural voice responses
|
||||
- **Same AI agents:** Your voice messages go to the same orchestrator (Easy/Hard mode)
|
||||
|
||||
---
|
||||
|
||||
## Using Voice
|
||||
|
||||
### Starting a Voice Session
|
||||
|
||||
1. Click the **microphone icon** in the chat panel
|
||||
2. Grant microphone permission if prompted
|
||||
3. Speak naturally — RA-H transcribes in real-time
|
||||
4. The AI responds with both text and audio
|
||||
|
||||
### Visual Feedback
|
||||
|
||||
- **"RA-H is listening"** strip appears when active
|
||||
- **Amplitude bars** show microphone input level
|
||||
- **Transcript preview** shows what's being recognized
|
||||
|
||||
### Stopping Voice Input
|
||||
|
||||
- Click the microphone button again
|
||||
- Or wait for silence detection (~800ms pause)
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
| Requirement | Details |
|
||||
|-------------|---------|
|
||||
| **API Key** | OpenAI API key (same key used for Easy mode) |
|
||||
| **Internet** | Required for STT and TTS |
|
||||
| **Microphone** | Mac app requests permission on first use |
|
||||
| **macOS** | 12+ (Monterey or later) |
|
||||
|
||||
---
|
||||
|
||||
## Cost
|
||||
|
||||
Voice features use OpenAI's APIs which have usage costs:
|
||||
|
||||
| Feature | Pricing |
|
||||
|---------|---------|
|
||||
| **Realtime STT** | Included in Realtime API usage |
|
||||
| **TTS** | ~$0.015 per 1,000 characters |
|
||||
|
||||
Costs are tracked in:
|
||||
- Per-message metadata (`voice_tts_*` fields)
|
||||
- `voice_usage` SQLite table
|
||||
- Settings → Analytics panel
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Internet required** — No offline voice support
|
||||
- **English optimized** — Other languages may have lower accuracy
|
||||
- **No voice selection** — Uses default OpenAI voice
|
||||
- **Mac only** — Voice features not available in web/open-source version
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
### API Endpoints
|
||||
|
||||
| Endpoint | Purpose |
|
||||
|----------|---------|
|
||||
| `/api/realtime/ephemeral-token` | Get temporary token for Realtime API |
|
||||
| `/api/voice/tts` | Convert text to speech |
|
||||
|
||||
### Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `src/components/agents/hooks/useRealtimeVoiceClient.ts` | STT WebSocket client |
|
||||
| `src/components/agents/hooks/useAssistantTTS.ts` | TTS playback |
|
||||
| `app/api/realtime/ephemeral-token/route.ts` | Token endpoint |
|
||||
| `app/api/voice/tts/route.ts` | TTS endpoint |
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Required for voice
|
||||
OPENAI_API_KEY=sk-...
|
||||
|
||||
# Optional: cost tracking
|
||||
RAH_TTS_COST_PER_1K_CHAR_USD=0.015
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Microphone not working"
|
||||
|
||||
1. Check System Preferences → Privacy → Microphone → RA-H is allowed
|
||||
2. Restart the app after granting permission
|
||||
3. Test microphone in other apps
|
||||
|
||||
### "Voice isn't responding"
|
||||
|
||||
1. Check internet connection
|
||||
2. Verify OpenAI API key is valid
|
||||
3. Check Settings → API Keys
|
||||
|
||||
### "Transcription is inaccurate"
|
||||
|
||||
- Speak clearly and at normal pace
|
||||
- Reduce background noise
|
||||
- Voice works best in quiet environments
|
||||
+79
-45
@@ -1,44 +1,63 @@
|
||||
# RA-H MCP Server
|
||||
# MCP Server
|
||||
|
||||
> How to connect Claude Code and other AI assistants to your knowledge base.
|
||||
|
||||
**How it works:** The RA-H desktop app runs a local MCP (Model Context Protocol) server. This lets any MCP-compatible assistant — like Claude Code — search your notes, add new knowledge, and extract content from URLs. Everything stays on your Mac; nothing goes to the cloud.
|
||||
**How it works:** RA-H Light runs a local MCP (Model Context Protocol) server. This lets any MCP-compatible assistant — like Claude Code — search your notes, add new knowledge, and manage your knowledge graph. Everything stays local; nothing goes to the cloud.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Launch the RA-H desktop app (it boots the MCP server automatically)
|
||||
2. Open **Settings → External Agents** inside RA-H and copy the connector URL
|
||||
3. Configure your assistant (see below)
|
||||
4. Talk naturally: "Summarize this and add it to RA-H"
|
||||
1. Start RA-H Light: `npm run dev`
|
||||
2. Configure your AI assistant (see below)
|
||||
3. Use naturally: "Search RA-H for my notes on X" or "Add this to RA-H"
|
||||
|
||||
---
|
||||
|
||||
## Available Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `rah_add_node` | Create a new node (title/content/dimensions) |
|
||||
| `rah_search_nodes` | Search existing nodes before creating duplicates |
|
||||
| `rah_youtube_extract` | Extract transcript from YouTube video |
|
||||
| `rah_website_extract` | Extract content from web page |
|
||||
| `rah_paper_extract` | Extract text from PDF |
|
||||
| `rah_search_nodes` | Search existing nodes |
|
||||
| `rah_update_node` | Update an existing node |
|
||||
| `rah_get_nodes` | Get nodes by ID |
|
||||
| `rah_create_edge` | Create relationship between nodes |
|
||||
| `rah_query_edges` | Query existing edges |
|
||||
| `rah_update_edge` | Update edge metadata |
|
||||
| `rah_create_dimension` | Create a new dimension |
|
||||
| `rah_update_dimension` | Update dimension description |
|
||||
| `rah_delete_dimension` | Delete a dimension |
|
||||
| `rah_search_embeddings` | Semantic search across embeddings |
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Configuration
|
||||
|
||||
Add to your `~/.claude/claude_desktop_config.json`:
|
||||
Add to your `~/.claude.json` or Claude Code settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "node",
|
||||
"args": ["/Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-server.js"]
|
||||
"args": ["/path/to/ra-h_os/apps/mcp-server/stdio-server.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or use the HTTP transport if you prefer:
|
||||
Replace `/path/to/ra-h_os` with the actual path to your RA-H Light installation.
|
||||
|
||||
**Note:** RA-H Light must be running (`npm run dev`) for the MCP server to work.
|
||||
|
||||
---
|
||||
|
||||
## HTTP Transport
|
||||
|
||||
For assistants that support HTTP transport:
|
||||
|
||||
**URL:** `http://127.0.0.1:44145/mcp`
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -50,52 +69,67 @@ Or use the HTTP transport if you prefer:
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** The RA-H desktop app must be running for the MCP server to work.
|
||||
|
||||
## Claude Desktop (STDIO)
|
||||
|
||||
Claude Desktop expects STDIO-based servers. Point it at:
|
||||
|
||||
```
|
||||
node /Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-server.js
|
||||
To start the HTTP server standalone:
|
||||
```bash
|
||||
node apps/mcp-server/server.js
|
||||
```
|
||||
|
||||
This script speaks MCP over stdin/stdout. Keep the main RA-H app running so the STDIO bridge can call `http://127.0.0.1:3000/api/nodes`.
|
||||
|
||||
## HTTP Transport
|
||||
|
||||
For assistants that support HTTP transport:
|
||||
|
||||
1. Copy the URL from **Settings → External Agents** (e.g., `http://127.0.0.1:44145/mcp`)
|
||||
2. Add as HTTP connector in your assistant
|
||||
---
|
||||
|
||||
## Example Usage
|
||||
|
||||
Once connected, you can:
|
||||
Once connected, you can ask your AI assistant:
|
||||
|
||||
```
|
||||
"Search RA-H for what I wrote about product strategy"
|
||||
"Add this conversation summary to RA-H as a new node"
|
||||
"Extract the transcript from this YouTube video and save to RA-H"
|
||||
"Find connections between my notes on AI agents"
|
||||
"Find all nodes with the 'research' dimension"
|
||||
"Create an edge between node 123 and node 456"
|
||||
"What are my most connected nodes?"
|
||||
```
|
||||
|
||||
## Guardrails
|
||||
---
|
||||
|
||||
- The MCP server only binds to `127.0.0.1` — for your agents only
|
||||
- Everything is persisted to `~/Library/Application Support/RA-H/db/rah.sqlite`
|
||||
- Disable with `RAH_ENABLE_MCP=false` before launching (UI toggle coming)
|
||||
- Health check: `curl http://127.0.0.1:44145/status`
|
||||
## Security
|
||||
|
||||
## Development
|
||||
- The MCP server only binds to `127.0.0.1` — localhost only
|
||||
- No authentication required (local access only)
|
||||
- All data persisted to `~/Library/Application Support/RA-H/db/rah.sqlite`
|
||||
|
||||
- **HTTP server:** `apps/mcp-server/server.js`
|
||||
- **STDIO bridge:** `apps/mcp-server/stdio-server.js`
|
||||
- **Sidecar launcher:** `apps/mac/scripts/sidecar-launcher.js`
|
||||
- **Status file:** `~/Library/Application Support/RA-H/config/mcp-status.json`
|
||||
---
|
||||
|
||||
## Health Check
|
||||
|
||||
To run standalone (for MCP Inspector):
|
||||
```bash
|
||||
node apps/mcp-server/server.js
|
||||
curl http://127.0.0.1:44145/status
|
||||
```
|
||||
Requires the Next.js sidecar to be running.
|
||||
|
||||
---
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `apps/mcp-server/server.js` | HTTP MCP server |
|
||||
| `apps/mcp-server/stdio-server.js` | STDIO MCP server (for Claude Code) |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Connection refused"
|
||||
|
||||
1. Make sure RA-H Light is running: `npm run dev`
|
||||
2. Check the port isn't blocked: `lsof -i :44145`
|
||||
3. Verify the server started: check terminal output
|
||||
|
||||
### "Tools not showing"
|
||||
|
||||
1. Restart your AI assistant after configuring
|
||||
2. Verify the path in your config is correct
|
||||
3. Check `node apps/mcp-server/stdio-server.js` runs without errors
|
||||
|
||||
### "Permission denied"
|
||||
|
||||
1. Make sure the stdio-server.js file is readable
|
||||
2. Check Node.js is in your PATH
|
||||
|
||||
+28
-21
@@ -1,33 +1,40 @@
|
||||
# RA-H Open Source
|
||||
# RA-H Light
|
||||
|
||||
**Full docs:** [ra-h.app/docs](https://ra-h.app/docs)
|
||||
This is **RA-H Light** — a minimal, local-first knowledge graph UI with MCP server integration.
|
||||
|
||||
This is the open source, BYO-key version of RA-H.
|
||||
## What is RA-H Light?
|
||||
|
||||
## What's Included
|
||||
RA-H Light is a stripped-down version of [RA-H](https://ra-h.app) focused on:
|
||||
|
||||
- Full three-panel UI (Nodes | Focus | Helpers)
|
||||
- Local SQLite storage with vector search
|
||||
- Complete agent system (ra-h, mini-rah, wise-rah)
|
||||
- All tools and workflows
|
||||
- MCP server for external AI assistants
|
||||
- Settings panel with API key management
|
||||
- **2-panel UI** for browsing and editing your knowledge graph
|
||||
- **MCP server** so external AI agents (like Claude Code) can access your notes
|
||||
- **Local SQLite** database with vector search
|
||||
- **BYO API keys** — no cloud dependencies
|
||||
|
||||
## What's Not Included
|
||||
## What's NOT Included
|
||||
|
||||
- Mac app packaging (Tauri)
|
||||
- Supabase authentication
|
||||
- Subscription/payment system
|
||||
- Auto-updates
|
||||
RA-H Light intentionally excludes:
|
||||
|
||||
## Relationship to Main Repo
|
||||
- Chat interface (use external agents via MCP)
|
||||
- Voice features
|
||||
- Built-in AI agents
|
||||
- Auth/subscription system
|
||||
- Desktop packaging (Tauri)
|
||||
|
||||
This repo is a mirror of the private `ra-h` repository. Features are developed privately and synced here.
|
||||
## Relationship to RA-H
|
||||
|
||||
- **Contributions welcome** - See [CONTRIBUTING.md](../CONTRIBUTING.md)
|
||||
- **Bug reports** - Open an issue
|
||||
- **Feature requests** - Open an issue; major features typically built privately first
|
||||
This repo (`ra-h_os`) is derived from the private `ra-h` repository. Shared features (database, UI components, MCP server) are synced from private to public.
|
||||
|
||||
## Setup
|
||||
## Getting Started
|
||||
|
||||
See [README.md](../README.md) for installation.
|
||||
|
||||
## Contributing
|
||||
|
||||
- **Bug reports** — Open an issue
|
||||
- **Feature requests** — Open an issue
|
||||
- **Pull requests** — Welcome for bug fixes and improvements
|
||||
|
||||
## License
|
||||
|
||||
MIT — See [LICENSE](../LICENSE)
|
||||
|
||||
+41
-23
@@ -1,33 +1,51 @@
|
||||
# RA-H Documentation
|
||||
|
||||
**Primary documentation:** [ra-h.app/docs](https://ra-h.app/docs)
|
||||
|
||||
The website docs are the source of truth. These local docs are a reference mirror.
|
||||
# RA-H Light Documentation
|
||||
|
||||
## Quick Links
|
||||
|
||||
- **Full Docs:** [ra-h.app/docs](https://ra-h.app/docs)
|
||||
- **Website:** [ra-h.app](https://ra-h.app)
|
||||
- **GitHub:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os)
|
||||
| Doc | Description |
|
||||
|-----|-------------|
|
||||
| [Overview](./0_overview.md) | What is RA-H Light, design philosophy |
|
||||
| [Schema](./2_schema.md) | Database schema, node/edge structure |
|
||||
| [Tools & Workflows](./4_tools-and-workflows.md) | MCP tools, workflow system |
|
||||
| [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation framework |
|
||||
| [UI](./6_ui.md) | 2-panel layout, components, views |
|
||||
| [MCP](./8_mcp.md) | Connect Claude Code and external agents |
|
||||
| [About](./9_open-source.md) | What's included, contributing |
|
||||
| [Troubleshooting](./TROUBLESHOOTING.md) | Common issues and fixes |
|
||||
|
||||
## Local Reference
|
||||
## Getting Started
|
||||
|
||||
| # | Document | Description |
|
||||
|---|----------|-------------|
|
||||
| 0 | [Overview](./0_overview.md) | What is RA-H, design philosophy |
|
||||
| 1 | [Architecture](./1_architecture.md) | Agent hierarchy, system design |
|
||||
| 2 | [Schema](./2_schema.md) | Database schema, nodes, edges, embeddings |
|
||||
| 3 | [Context & Memory](./3_context-and-memory.md) | Auto-context system |
|
||||
| 4 | [Tools & Workflows](./4_tools-and-workflows.md) | Available tools, workflows |
|
||||
| 5 | [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation |
|
||||
| 6 | [UI](./6_ui.md) | 3-panel layout, views |
|
||||
| 7 | [Voice](./7_voice.md) | Voice interface |
|
||||
| 8 | [MCP Server](./8_mcp.md) | External agent connector |
|
||||
```bash
|
||||
# Clone
|
||||
git clone https://github.com/bradwmorris/ra-h_os.git
|
||||
cd ra-h_os
|
||||
|
||||
## Troubleshooting
|
||||
# Install
|
||||
npm install
|
||||
|
||||
See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues.
|
||||
# Run
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open http://localhost:3000
|
||||
|
||||
## MCP Integration
|
||||
|
||||
Add to your Claude Code config:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ra-h": {
|
||||
"command": "node",
|
||||
"args": ["/path/to/ra-h_os/apps/mcp-server/stdio-server.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See [MCP docs](./8_mcp.md) for full setup.
|
||||
|
||||
## Questions?
|
||||
|
||||
Check [ra-h.app/docs](https://ra-h.app/docs) or open an issue on GitHub.
|
||||
Open an issue on [GitHub](https://github.com/bradwmorris/ra-h_os).
|
||||
|
||||
Reference in New Issue
Block a user