SyslogSolution/ra-h-os
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation for RA-H Light

Browse Source 
- 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”
2026-01-29 16:06:54 +11:00
co-authored by Claude Opus 4.5
parent ea61ef1023
commit f383d770ca
9 changed files with 338 additions and 850 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/0_overview.md
+52 -36
View File
@@ -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) **Open Source:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os)
## Design Philosophy ## 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. **Simple & focused** — 2-panel UI for browsing and editing your knowledge graph. No bloat.
**Human + AI** — You guide, AI assists. Create custom workflows. Always in control of your knowledge.
## Tech Stack ## Tech Stack
- **Frontend:** Next.js 15, TypeScript, Tailwind CSS - **Frontend:** Next.js 15, TypeScript, Tailwind CSS
- **Database:** SQLite + sqlite-vec (vector search) - **Database:** SQLite + sqlite-vec (vector search)
- **AI Models:** Anthropic Claude + OpenAI GPT via Vercel AI SDK - **Embeddings:** OpenAI (BYO API key)
- **Desktop:** Tauri (Mac app)
- **MCP Server:** Local connector for Claude Code and external agents - **MCP Server:** Local connector for Claude Code and external agents
## Current Status ## What's Included
- **Version:** v0.1.21 (January 2026) - 2-panel UI (nodes list + focus panel)
- **Platforms:** - Node/Edge/Dimension CRUD
- Mac app (download at [ra-h.app/download](https://ra-h.app/download)) - Full-text and semantic search
- Open source self-hosted (BYO API keys) - MCP server with 11 tools
- **License:** MIT (open source version) - 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 | - Chat interface (use external agents via MCP)
|---------|----------|--------| - Voice features
| **Mac App** | Most users. One-click install, auto-updates, optional subscription features | [ra-h.app/download](https://ra-h.app/download) | - Built-in AI agents
| **Open Source** | Developers, self-hosters, contributors. BYO API keys, full control | [GitHub](https://github.com/bradwmorris/ra-h_os) | - 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 ## MCP Integration
- **AI agents:** Orchestrator for chat, workflows for deep analysis
- **Graph database:** Nodes and edges with semantic search RA-H Light is designed to be the knowledge backend for your AI workflows:
- **MCP server:** Connect Claude Code and other external agents
- **Workflows:** Code-first automation (Integrate, custom workflows) ```json
- **Extraction tools:** YouTube, websites, PDFs {
"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 ## Documentation
| Doc | Description | | Doc | Description |
|-----|-------------| |-----|-------------|
| [Architecture](./1_architecture.md) | Agent hierarchy, system design |
| [Schema](./2_schema.md) | Database schema, node/edge structure | | [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 MCP tools, workflow system |
| [Tools & Workflows](./4_tools-and-workflows.md) | Available tools, workflow system |
| [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation framework |
| [UI](./6_ui.md) | Component structure, panels, views | | [UI](./6_ui.md) | Component structure, panels, views |
| [Voice](./7_voice.md) | Voice interface (STT/TTS) |
| [MCP](./8_mcp.md) | External agent connector setup | | [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 |
docs/1_architecture.md
-112
View File
@@ -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.
docs/3_context-and-memory.md
-161
View File
@@ -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.
docs/4_tools-and-workflows.md
+118 -244
View File
@@ -1,217 +1,132 @@
# Tools & Workflows # 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 | ### Node Operations
|----------|---------|----------|
| **Core** | Read-only graph operations | queryNodes, searchContentEmbeddings | | Tool | Description |
| **Orchestration** | Delegation and reasoning | executeWorkflow, think, webSearch | |------|-------------|
| **Execution** | Write operations and extraction | createNode, updateNode, youtubeExtract | | `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: ### rah_add_node
### queryNodes
Search nodes by title, content, or dimensions.
```typescript ```typescript
queryNodes({ {
search?: string, // Full-text search title: string, // Required
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,
content?: string, content?: string,
description?: string, description?: string,
dimensions?: string[], dimensions?: string[],
link?: string, link?: string,
metadata?: object metadata?: object
}) }
``` ```
### updateNode ### rah_search_nodes
Append content to existing nodes. **Append-only** — cannot overwrite.
```typescript ```typescript
updateNode({ {
id: number, search?: string, // Full-text search
content: string // Appended to existing content dimensions?: string[],// Filter by dimensions
}) limit?: number // Max results (default: 20)
}
``` ```
### createEdge ### rah_update_node
Create relationship between nodes.
```typescript ```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, from_node_id: number,
to_node_id: number, to_node_id: number,
context?: string // Relationship description context?: string // Relationship description
}) }
``` ```
### updateEdge ### rah_search_embeddings
Modify edge metadata.
```typescript ```typescript
updateEdge({ {
id: number, query: string, // Search query
context?: string, node_id?: number, // Scope to specific node
user_feedback?: number limit?: number, // Max results
}) threshold?: number // Similarity threshold (0-1)
``` }
### 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
``` ```
--- ---
## Tool Access by Agent ## API Routes
| Agent | Core | Orchestration | Execution | RA-H Light exposes REST APIs that MCP tools call internally:
|-------|------|---------------|-----------|
| **ra-h / ra-h-easy** | ✅ All | webSearch, think, executeWorkflow | ✅ All | | Route | Method | Purpose |
| **wise-rah** | ✅ All | webSearch, think, delegateToMiniRAH | updateNode, createEdge | |-------|--------|---------|
| **mini-rah** | ✅ All | webSearch, think | ✅ All | | `/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
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 ### Workflow Format
**Users can create, edit, and delete workflows** from Settings → Workflows tab.
**Storage:** `~/Library/Application Support/RA-H/workflows/`
**Format:** JSON files with this structure:
```json ```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) Via API:
2. Orchestrator calls `executeWorkflow({ workflow_key: 'integrate' })` ```bash
3. System spawns wise-rah session with workflow instructions curl -X POST http://localhost:3000/api/workflows/execute \
4. wise-rah executes steps autonomously (30-60+ seconds) -H "Content-Type: application/json" \
5. wise-rah returns summary to orchestrator -d '{"workflow_key": "integrate", "focused_node_id": 123}'
6. Orchestrator shows result to user ```
### Built-in Workflows ### Built-in Workflows
#### Integrate **Integrate** — Database-wide connection discovery. Finds related nodes and suggests connections.
**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]
```
### Creating Custom Workflows ### Creating Custom Workflows
1. Go to Settings → Workflows 1. Create a JSON file in `~/Library/Application Support/RA-H/workflows/`
2. Click "New Workflow" 2. Define key, displayName, description, instructions
3. Fill in: 3. Set `enabled: true`
- **Key** — unique identifier (lowercase, no spaces) 4. Execute via API
- **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")
--- ---
## Tool Registry ## Database Tools (Internal)
**Location:** `src/tools/infrastructure/registry.ts` These tools are used by the workflow executor and API routes:
**Structure:** | Tool | File | Purpose |
|------|------|---------|
```typescript | `queryNodes` | `src/tools/database/queryNodes.ts` | Search nodes |
TOOL_SETS = { | `createNode` | `src/tools/database/createNode.ts` | Create node |
core: { queryNodes, getNodesById, queryEdge, queryDimensions, getDimension, searchContentEmbeddings }, | `updateNode` | `src/tools/database/updateNode.ts` | Update node |
orchestration: { webSearch, think, delegateToMiniRAH, executeWorkflow, ... }, | `deleteNode` | `src/tools/database/deleteNode.ts` | Delete node |
execution: { createNode, updateNode, createEdge, updateEdge, youtubeExtract, websiteExtract, paperExtract, ... } | `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 | File | Purpose |
|------|---------|
`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. | `apps/mcp-server/server.js` | HTTP MCP server |
| `apps/mcp-server/stdio-server.js` | STDIO MCP server |
### No Workflow Delegation Loops | `src/tools/infrastructure/registry.ts` | Tool registry |
| `src/services/agents/workflowExecutor.ts` | Workflow execution |
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.
docs/6_ui.md
+20 -83
View File
@@ -1,23 +1,23 @@
# User Interface # 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 │ │ NODES │ FOCUS │
│ Panel │ Panel │ Panel │ │ Panel │ Panel │
│ │ │ │ │ │ │
│ • Search │ • Tabbed workspace │ • AI chat │ │ • Search │ • Tabbed workspace │
│ • Filters │ • Node content │ • Easy/Hard │ │ • Filters │ • Node content │
│ • Folders │ • Connections │ • Delegations │ │ • 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. Active workspace for the node(s) you're working with.
### Tabbed Interface ### Tabbed Interface
- **Primary tab** — Main focused node - **Primary tab** — Main focused node
- **Additional tabs** — Related nodes opened from chat - **Additional tabs** — Related nodes opened from links
- **Tab controls** — Close (×), reorder, switch - **Tab controls** — Close (×), reorder, switch
### Node Detail View ### 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) ## Search (Cmd+K)
Global search modal with 4-tier relevance: Global search modal with 4-tier relevance:
@@ -190,19 +142,15 @@ Global search modal with 4-tier relevance:
## Settings Panel ## Settings Panel
**Access:** Settings cog icon (top-right, green ring) **Access:** Settings cog icon (top-right)
**Size:** 88vw × 90vh with glass effect ### Tabs
### Tabs (in order)
| Tab | Purpose | | Tab | Purpose |
|-----|---------| |-----|---------|
| **Subscription** | Account status, usage, upgrade options | | **API Keys** | Configure OpenAI/Tavily keys |
| **API Keys** | Configure Anthropic/OpenAI/Tavily keys | | **Workflows** | View, edit, create workflows |
| **Workflows** | View, edit, create, delete workflows | | **Tools** | View available tools |
| **Tools** | View available agent tools |
| **Context** | Auto-context toggle, view hub nodes |
| **Map** | Knowledge graph visualization | | **Map** | Knowledge graph visualization |
| **Database** | Full node table with filters/sorting | | **Database** | Full node table with filters/sorting |
| **Logs** | Activity feed (last 100 entries) | | **Logs** | Activity feed (last 100 entries) |
@@ -221,11 +169,6 @@ Visual graph of your knowledge network.
- Click node to highlight connections - Click node to highlight connections
- Selection shows connected nodes in green - Selection shows connected nodes in green
**Styling:**
- Cluster layout with golden angle spiral
- Transparent flat circles
- Green rings for selected/connected nodes
--- ---
## Database View ## Database View
@@ -236,7 +179,6 @@ Full table view of all nodes.
- Node (title + ID) - Node (title + ID)
- Dimensions (folder badges) - Dimensions (folder badges)
- Edges (count) - Edges (count)
- Status (context hub indicator)
- Updated (timestamp) - Updated (timestamp)
**Features:** **Features:**
@@ -254,7 +196,7 @@ Each dimension can have a custom Lucide icon.
**To set:** **To set:**
1. Open Folder View → hover over dimension 1. Open Folder View → hover over dimension
2. Click edit (pencil) icon 2. Click edit (pencil) icon
3. Choose icon from 115 curated options 3. Choose icon from curated options
4. Icons persist in localStorage 4. Icons persist in localStorage
--- ---
@@ -264,13 +206,10 @@ Each dimension can have a custom Lucide icon.
**Format:** `[NODE:id:"title"]` **Format:** `[NODE:id:"title"]`
**Rendering:** **Rendering:**
- Clickable labels in chat messages
- Clickable labels in node content - Clickable labels in node content
- Hover shows preview tooltip - Hover shows preview tooltip
- Click opens in Focus panel - Click opens in Focus panel
AI agents automatically use this format for all node mentions.
--- ---
## Keyboard Shortcuts ## Keyboard Shortcuts
@@ -278,7 +217,6 @@ AI agents automatically use this format for all node mentions.
| Shortcut | Action | | Shortcut | Action |
|----------|--------| |----------|--------|
| `Cmd+K` | Open search | | `Cmd+K` | Open search |
| `Cmd+\\` | Toggle chat panel |
| `Escape` | Close modals/overlays | | `Escape` | Close modals/overlays |
--- ---
@@ -288,7 +226,6 @@ AI agents automatically use this format for all node mentions.
### Colors ### Colors
- **Background:** `#0a0a0a` (near black) - **Background:** `#0a0a0a` (near black)
- **Panels:** Subtle gradients distinguishing left/middle/right
- **Accent:** Green (`#22c55e`) for actions, selections - **Accent:** Green (`#22c55e`) for actions, selections
- **Text:** White (primary), neutral-400 (secondary) - **Text:** White (primary), neutral-400 (secondary)
docs/7_voice.md
-125
View File
@@ -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
docs/8_mcp.md
+79 -45
View File
@@ -1,44 +1,63 @@
# RA-H MCP Server # MCP Server
> How to connect Claude Code and other AI assistants to your knowledge base. > 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 ## Quick Start
1. Launch the RA-H desktop app (it boots the MCP server automatically) 1. Start RA-H Light: `npm run dev`
2. Open **Settings → External Agents** inside RA-H and copy the connector URL 2. Configure your AI assistant (see below)
3. Configure your assistant (see below) 3. Use naturally: "Search RA-H for my notes on X" or "Add this to RA-H"
4. Talk naturally: "Summarize this and add it to RA-H"
---
## Available Tools ## Available Tools
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `rah_add_node` | Create a new node (title/content/dimensions) | | `rah_add_node` | Create a new node (title/content/dimensions) |
| `rah_search_nodes` | Search existing nodes before creating duplicates | | `rah_search_nodes` | Search existing nodes |
| `rah_youtube_extract` | Extract transcript from YouTube video | | `rah_update_node` | Update an existing node |
| `rah_website_extract` | Extract content from web page | | `rah_get_nodes` | Get nodes by ID |
| `rah_paper_extract` | Extract text from PDF | | `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 ## Claude Code Configuration
Add to your `~/.claude/claude_desktop_config.json`: Add to your `~/.claude.json` or Claude Code settings:
```json ```json
{ {
"mcpServers": { "mcpServers": {
"ra-h": { "ra-h": {
"command": "node", "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 ```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. To start the HTTP server standalone:
```bash
## Claude Desktop (STDIO) node apps/mcp-server/server.js
Claude Desktop expects STDIO-based servers. Point it at:
```
node /Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-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 ## Example Usage
Once connected, you can: Once connected, you can ask your AI assistant:
``` ```
"Search RA-H for what I wrote about product strategy" "Search RA-H for what I wrote about product strategy"
"Add this conversation summary to RA-H as a new node" "Add this conversation summary to RA-H as a new node"
"Extract the transcript from this YouTube video and save to RA-H" "Find all nodes with the 'research' dimension"
"Find connections between my notes on AI agents" "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 ## Security
- 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`
## 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` ## Health Check
- **Status file:** `~/Library/Application Support/RA-H/config/mcp-status.json`
To run standalone (for MCP Inspector):
```bash ```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
docs/9_open-source.md
+28 -21
View File
@@ -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) - **2-panel UI** for browsing and editing your knowledge graph
- Local SQLite storage with vector search - **MCP server** so external AI agents (like Claude Code) can access your notes
- Complete agent system (ra-h, mini-rah, wise-rah) - **Local SQLite** database with vector search
- All tools and workflows - **BYO API keys** — no cloud dependencies
- MCP server for external AI assistants
- Settings panel with API key management
## What's Not Included ## What's NOT Included
- Mac app packaging (Tauri) RA-H Light intentionally excludes:
- Supabase authentication
- Subscription/payment system
- Auto-updates
## 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) 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.
- **Bug reports** - Open an issue
- **Feature requests** - Open an issue; major features typically built privately first
## Setup ## Getting Started
See [README.md](../README.md) for installation. 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)
docs/README.md
+41 -23
View File
@@ -1,33 +1,51 @@
# RA-H Documentation # RA-H Light 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.
## Quick Links ## Quick Links
- **Full Docs:** [ra-h.app/docs](https://ra-h.app/docs) | Doc | Description |
- **Website:** [ra-h.app](https://ra-h.app) |-----|-------------|
- **GitHub:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os) | [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 | ```bash
|---|----------|-------------| # Clone
| 0 | [Overview](./0_overview.md) | What is RA-H, design philosophy | git clone https://github.com/bradwmorris/ra-h_os.git
| 1 | [Architecture](./1_architecture.md) | Agent hierarchy, system design | cd ra-h_os
| 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 |
## 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? ## 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).