diff --git a/docs/0_overview.md b/docs/0_overview.md index c28cc20..3844027 100644 --- a/docs/0_overview.md +++ b/docs/0_overview.md @@ -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 | diff --git a/docs/1_architecture.md b/docs/1_architecture.md deleted file mode 100644 index ac16240..0000000 --- a/docs/1_architecture.md +++ /dev/null @@ -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. diff --git a/docs/3_context-and-memory.md b/docs/3_context-and-memory.md deleted file mode 100644 index 9fc797e..0000000 --- a/docs/3_context-and-memory.md +++ /dev/null @@ -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. diff --git a/docs/4_tools-and-workflows.md b/docs/4_tools-and-workflows.md index 8cba0ce..69b0680 100644 --- a/docs/4_tools-and-workflows.md +++ b/docs/4_tools-and-workflows.md @@ -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 | diff --git a/docs/6_ui.md b/docs/6_ui.md index 56dd006..4e0efe0 100644 --- a/docs/6_ui.md +++ b/docs/6_ui.md @@ -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) diff --git a/docs/7_voice.md b/docs/7_voice.md deleted file mode 100644 index 69ce534..0000000 --- a/docs/7_voice.md +++ /dev/null @@ -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 diff --git a/docs/8_mcp.md b/docs/8_mcp.md index 2a680fe..cc25676 100644 --- a/docs/8_mcp.md +++ b/docs/8_mcp.md @@ -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//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//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 diff --git a/docs/9_open-source.md b/docs/9_open-source.md index 0456f0e..53426e6 100644 --- a/docs/9_open-source.md +++ b/docs/9_open-source.md @@ -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) diff --git a/docs/README.md b/docs/README.md index 30981e0..8316958 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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).