From 0f408bc9078b4eff6d5da1fe6d42638d46cfb5d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CBeeRad=E2=80=9D?= Date: Mon, 5 Jan 2026 12:42:51 +1100 Subject: [PATCH] docs: sync documentation from private repo - Rewrite 3_context-and-memory.md (auto-context system, remove legacy memory) - Create 7_voice.md (voice interface documentation) - Update 0_overview.md, 1_architecture.md, 4_tools-and-workflows.md, 6_ui.md, 8_mcp.md - Add simple human-readable intros to all docs - Update README.md with voice doc reference Synced from ra-h commit 4a3d7e0 --- docs/0_overview.md | 58 ++++- docs/1_architecture.md | 10 +- docs/3_context-and-memory.md | 263 +++++++++++---------- docs/4_tools-and-workflows.md | 426 ++++++++++++++++++++++------------ docs/6_ui.md | 377 ++++++++++++++++++++---------- docs/7_voice.md | 125 ++++++++++ docs/8_mcp.md | 135 ++++++----- docs/README.md | 59 +++-- 8 files changed, 973 insertions(+), 480 deletions(-) create mode 100644 docs/7_voice.md diff --git a/docs/0_overview.md b/docs/0_overview.md index fb374a4..c28cc20 100644 --- a/docs/0_overview.md +++ b/docs/0_overview.md @@ -2,27 +2,65 @@ ## What is RA-H? -RA-H is a flexible knowledge management system designed for researchers. It learns how you think and helps connect ideas across your knowledge base. +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. -For more information, visit [ra-h.app](https://ra-h.app) +**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. +**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. -**Everything is connected** - Every piece of knowledge can potentially connect to any other. Connections aren't just links - they carry context, explanation, and meaning. +**Everything is connected** — Every piece of knowledge can potentially connect to any other. Connections aren't just links — they carry context, explanation, and meaning. -**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. +**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. ## Tech Stack - **Frontend:** Next.js 15, TypeScript, Tailwind CSS - **Database:** SQLite + sqlite-vec (vector search) -- **AI:** Anthropic Claude + OpenAI GPT via Vercel AI SDK -- **Deployment:** Currently beta web bundle, Mac app coming soon +- **AI Models:** Anthropic Claude + OpenAI GPT via Vercel AI SDK +- **Desktop:** Tauri (Mac app) +- **MCP Server:** Local connector for Claude Code and external agents ## Current Status -- **Version:** 0.1.0 (Open Source) -- **Platform:** Web-based (Next.js server, local-only) -- **License:** MIT +- **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) + +## Two Ways to Use RA-H + +| 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) | + +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. + +## Key Features + +- **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 + +## 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 | +| [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 | diff --git a/docs/1_architecture.md b/docs/1_architecture.md index a0d871c..ac16240 100644 --- a/docs/1_architecture.md +++ b/docs/1_architecture.md @@ -1,5 +1,11 @@ # 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). @@ -88,7 +94,7 @@ Users toggle via UI (⚡ Easy / 🔥 Hard). Choice persists in localStorage. **S **Orchestrator:** - Maintains full conversation history -- Sees pinned nodes + focused node +- Sees auto-context (top 10 connected nodes) + focused node - Delegates isolation ensures clean context **Workers (wise-rah/mini-rah):** @@ -103,4 +109,4 @@ Users interact with a single interface that automatically routes requests to the - **Workflow triggers** (executeWorkflow → wise-rah) - **Delegation needs** (mini-rah spawned in background) -All agents share the same **pinned context** (up to 10 nodes) plus the **focused node** for consistent knowledge access. +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 index d54fe49..9fc797e 100644 --- a/docs/3_context-and-memory.md +++ b/docs/3_context-and-memory.md @@ -1,148 +1,161 @@ # Context & Memory -## Context Builder +> How RA-H decides what information to show the AI during conversations. -The context builder assembles the information each agent sees during conversations. It creates **cacheable blocks** (for Anthropic) and structured context for all agents. +**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 Structure +--- -Every agent receives: +## Context System Overview -**1. Base Context** -- How nodes, edges, and dimensions work -- Node reference format: `[NODE:id:"title"]` -- If auto-context is enabled, BACKGROUND CONTEXT explains that the 10 most-connected nodes will be listed later -- Pronouns like "this conversation/paper/video" refer to focused node +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. -**2. Agent Instructions** -- Agent-specific system prompt (ra-h, ra-h-easy, wise-rah, mini-rah) -- Role-specific behavior guidelines -- Execution approach and response style +### What Gets Included -**3. Tool Definitions** -- Role-specific tools (orchestrator/executor/planner) -- Each tool's description and parameters -- Usage guidelines +| 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 | -**4. Workflow Definitions** (orchestrators only) -- Available workflows (integrate, etc.) -- Workflow descriptions and triggers -- Only shown to ra-h and ra-h-easy +--- -**5. Background Context (auto-context hubs)** (orchestrators only) -- Optional block controlled by `~/Library/Application Support/RA-H/config/settings.json` -- Lists the 10 nodes with the highest edge counts (ID + title + edge count) -- Reminds agents to call `queryNodes`/`getNodesById` for full content -- Ordered by edge count, then most recently updated to break ties +## Auto-Context System -**6. Focused Nodes** -- Primary focused node (active tab) -- Additional focused nodes (other open tabs) -- 25-word content previews -- Chunk status and embedding availability -- Link information +Auto-context automatically includes your most important knowledge in every conversation. It replaces the old manual "pinning" system. -### Context Caching +### How It Works -**Anthropic (Claude):** -- Explicit cache control blocks (`cache_control: {type: 'ephemeral'}`) -- Caches base context, instructions, tools, workflows, background context -- Focused nodes NOT cached (changes frequently) +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 -**OpenAI (GPT):** -- Implicit caching based on prefix matching -- Same block structure for consistency -- No explicit cache control markers needed - -### Truncation Strategy - -- **Background context:** IDs + titles only to keep the block lightweight -- **Focused nodes:** 25-word previews -- **Full content access:** Agents use `queryNodes`, `getNodesById`, `searchContentEmbeddings` for complete content -- **Chunk status indicator:** Shows if embeddings are available (avoid re-extraction) - -## Memory System (Legacy) - -The automatic memory pipeline has been removed. Existing memory nodes remain in the database for archival purposes, but no new ones are created and they are excluded from auto-context. The old files (`src/services/memory/**`) have been deleted along with the `ENABLE_CHAT_MEMORY_PIPELINE` toggle. Future improvements should store long-term knowledge as normal nodes with explicit dimensions rather than a background pipeline. -6. Update checkpoint in `chat_memory_state` - -**Location:** -- Pipeline: `/src/services/memory/synthesis/chatMemoryPipeline.ts` -- Trigger: `/src/services/chat/middleware.ts:168-178` -- Extraction: `/src/services/memory/synthesis/llmSynthesis.ts` - -### Memory Node Structure - -```typescript -{ - type: 'memory', - title: 'Insight on [subject]', - description: 'Multi-line list of facts', - content: 'Second-person statements combined', - metadata: { - category: 'identity' | 'interests' | 'models' | 'preferences' | 'relationships', - subject_type: 'person' | 'project' | 'concept' | 'resource' | 'organization' | 'workflow', - source_thread: string, - source_helper: string, - importance: 'low' | 'medium' | 'high', - focused_node_titles: string[], - canonical_key: string | null, - subject: string - } -} -``` - -### Memory Categories - -- **identity** - Who you are, your roles, background -- **interests** - What you're curious about, learning, exploring -- **models** - How you think, mental frameworks, approaches -- **preferences** - What you like/dislike, priorities, values -- **relationships** - Connections to people, projects, concepts - -### Subject Types - -Memory extraction classifies subjects into these types: - -- **person** - Individual people (yourself or collaborators) -- **project** - Projects, products, or initiatives -- **concept** - Ideas, theories, mental models, beliefs -- **resource** - Tools, articles, books, references -- **organization** - Companies, institutions, communities -- **workflow** - Processes, systems, methodologies - -### Importance Levels - -Each memory fact is classified by importance: - -- **high** - Explicitly marked as priority, main project, strong belief ("is crucial", "must") -- **medium** - Normal statements and observations (default) -- **low** - Tentative, uncertain, or exploratory statements - -## Auto-Context Toggle - -Auto-context replaces manual pinning. When enabled, BACKGROUND CONTEXT includes the 10 nodes with the highest edge counts. - -**How it works:** -1. Settings UI exposes a toggle inside the Context tab. -2. The toggle writes to `~/Library/Application Support/RA-H/config/settings.json`. -3. Context builder and workflows read that file on each request (missing file defaults to `false`). -4. When enabled, the following query runs once per request: +### The Query ```sql -SELECT n.id, - n.title, - COUNT(DISTINCT e.id) AS edge_count, - n.updated_at +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; +LIMIT 10 ``` -**Notes:** -- Only orchestrators (ra-h / ra-h-easy) see the block. -- Titles + edge counts are shown; agents must call `queryNodes`/`getNodesById` for content. -- Users who previously pinned nodes are auto-migrated to `autoContextEnabled: true` the first time the toggle helper runs and sees legacy pins. +**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 998d1d8..8cba0ce 100644 --- a/docs/4_tools-and-workflows.md +++ b/docs/4_tools-and-workflows.md @@ -1,174 +1,316 @@ # Tools & Workflows -## Tool Architecture +> What actions the AI can take and how workflows automate multi-step processes. -Tools are organized into three categories with role-based access control. +**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. -### Core Tools (All Agents) +--- -Read-only graph operations available to orchestrators, executors, and planners: +## Tools Overview -- **queryNodes** - Search nodes by title/content/dimensions -- **getNodesById** - Retrieve full node data by ID array -- **queryEdge** - Inspect existing edges between nodes -- **searchContentEmbeddings** - Semantic search across chunk embeddings +Tools are organized into three categories: -### Orchestration Tools (Orchestrators Only) +| 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 | -Workflow and delegation tools for ra-h and ra-h-easy: +--- -- **webSearch** - External web search via Tavily -- **think** - Internal reasoning/planning (logged to metadata) -- **executeWorkflow** - Delegate to wise-rah for predefined workflows -- **delegateToMiniRAH** - Spawn mini-rah worker for tasks (deprecated in favor of direct execution) -- **delegateToWiseRAH** - Delegate to wise-rah (now replaced by executeWorkflow) +## Core Tools (All Agents) -### Execution Tools (Workers + Orchestrators) +Read-only operations available to all agents: -Write operations and extraction - available to mini-rah, wise-rah, and orchestrators: +### queryNodes +Search nodes by title, content, or dimensions. -- **createNode** - Create new knowledge nodes -- **updateNode** - Append content to existing nodes (append-only enforced at tool level) -- **createEdge** - Create relationships between nodes -- **updateEdge** - Modify edge metadata -- **youtubeExtract** - Extract transcripts from YouTube videos -- **websiteExtract** - Extract content from web pages -- **paperExtract** - Extract text from PDF papers +```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, + content?: string, + description?: string, + dimensions?: string[], + link?: string, + metadata?: object +}) +``` + +### updateNode +Append content to existing nodes. **Append-only** — cannot overwrite. + +```typescript +updateNode({ + id: number, + content: string // Appended to existing content +}) +``` + +### createEdge +Create relationship between nodes. + +```typescript +createEdge({ + from_node_id: number, + to_node_id: number, + context?: string // Relationship description +}) +``` + +### updateEdge +Modify edge metadata. + +```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 +``` + +--- ## Tool Access by Agent -### ra-h / ra-h-easy (Orchestrators) -**Tools:** Core + Orchestration + Execution (minus delegation helpers) -- Direct write access (createNode, updateNode, createEdge, updateEdge) -- Extraction tools (youtube, website, paper) -- Workflow execution (executeWorkflow) -- External search (webSearch) +| 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 | -### wise-rah (Planner) -**Tools:** Core + webSearch + think + updateNode -- **Direct write access** via updateNode (append-only) -- **NO delegation** - executes workflows autonomously -- Database-wide search capabilities -- Minimal tool set for focused workflow execution - -### mini-rah (Executor) -**Tools:** Core + Execution + webSearch + think -- All read tools -- All write tools (createNode, updateNode, createEdge, updateEdge) -- All extraction tools -- **NO delegation** - leaf workers only - -## Tool Registry - -**Location:** `/src/tools/infrastructure/registry.ts` - -**Structure:** -```typescript -TOOL_SETS = { - core: { queryNodes, getNodesById, queryEdge, searchContentEmbeddings }, - orchestration: { webSearch, think, delegateToMiniRAH, executeWorkflow, ... }, - execution: { createNode, updateNode, createEdge, updateEdge, youtubeExtract, websiteExtract, paperExtract } -} -``` - -**Role mappings:** -- `ORCHESTRATOR_TOOL_NAMES` - Core + webSearch + think + executeWorkflow + Execution -- `EXECUTOR_TOOL_NAMES` - Core + Execution + webSearch + think (no delegation) -- `PLANNER_TOOL_NAMES` - Core + webSearch + think + updateNode +--- ## Workflows -**Location:** `/src/services/workflows/registry.ts` +Workflows are multi-step instruction sets executed by wise-rah. -Workflows are **code-first** - defined in registry, not database. Users cannot create custom workflows. +### User-Editable Workflows -### Integrate Workflow +**Users can create, edit, and delete workflows** from Settings → Workflows tab. -**Key:** `integrate` -**Executor:** wise-rah (planner role) -**Purpose:** Database-wide connection discovery for focused node -**Cost:** ~$0.18/execution (GPT-5, 18 tool calls max) +**Storage:** `~/Library/Application Support/RA-H/workflows/` -**Process (5 steps):** +**Format:** JSON files with this structure: -1. **Plan** - Call `think` to outline approach -2. **Ground** - Identify node type, extract entities (names, projects, concepts), summarize core insight -3. **Search** - Database-wide search using extracted entities - - Obvious connections: queryNodes for specific names/projects/techniques - - Thematic connections: searchContentEmbeddings for shared concepts - - Finds 3-8 strong connections (not 20 weak ones) -4. **Contextualize** - Brief 1-2 sentence relevance to pinned context -5. **Append** - Call updateNode ONCE with Integration Analysis section - -**Output format:** -```markdown -## Integration Analysis - -[2-3 sentences: what this node is, why it matters, core insight] - -**Database Connections:** -- [NODE:123:"Title"] — [why: authorship/shared concept/dependency/contradiction] -- [NODE:456:"Title"] — [why: ...] -- [continue for 3-8 connections] - -**Relevance:** [1-2 sentences connecting to user's pinned context] -``` - -**Key features:** -- **Database-first search** - Ignores pinned context during search (step 3), uses it only for relevance explanation (step 4) -- **Entity extraction** - Grounding step identifies searchable entities before searching -- **Append-only** - updateNode enforced at tool level (cannot overwrite) -- **Single update** - Calls updateNode EXACTLY once per workflow -- **Works for any node type** - Adapts to person/project/paper/idea/video/tweet/technique - -**Invocation:** -```typescript -// User: "run integrate workflow" -// Orchestrator calls: executeWorkflow({ workflow_key: 'integrate' }) -// System delegates to wise-rah with workflow instructions -``` - -## Workflow Registry - -**Definition:** -```typescript +```json { - id: 1, - key: 'integrate', - displayName: 'Integrate', - description: 'Deep analysis and connection-building for focused node', - instructions: INTEGRATE_WORKFLOW_INSTRUCTIONS, - enabled: true, - requiresFocusedNode: true, - primaryActor: 'oracle', - expectedOutcome: 'Focused node updated with insights; 3-5 high-value edges created' + "key": "integrate", + "displayName": "Integrate", + "description": "Deep analysis and connection-building for focused node", + "instructions": "You are executing the INTEGRATE workflow...", + "enabled": true, + "requiresFocusedNode": true } ``` -**Adding new workflows:** -1. Create instructions file in `/src/config/workflows/[name].ts` -2. Add workflow definition to `WorkflowRegistry.WORKFLOWS` -3. Immediately available to orchestrators (no database changes needed) +### How Workflows Work -## Tool Execution Flow - -**Orchestrator conversation:** -1. User sends message → ra-h/ra-h-easy -2. Agent calls tools directly (createNode, queryNodes, etc.) -3. Agent synthesizes response from tool results -4. Response includes [NODE:id:"title"] references for UI rendering - -**Workflow execution:** -1. User: "run integrate workflow" -2. ra-h/ra-h-easy calls `executeWorkflow({ workflow_key: 'integrate' })` +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 5-step process autonomously +4. wise-rah executes steps autonomously (30-60+ seconds) 5. wise-rah returns summary to orchestrator -6. Orchestrator shows summary to user +6. Orchestrator shows result to user -**Delegation (legacy, rarely used):** -1. Orchestrator calls `delegateToMiniRAH({ task, context, expected_outcome })` -2. System creates agent_delegations row (status: 'queued') -3. Mini-rah spawned in isolated session -4. Mini-rah executes task, returns structured summary -5. Summary shown in delegation tab (persists until manually closed) +### 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] +``` + +### 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") + +--- + +## Tool Registry + +**Location:** `src/tools/infrastructure/registry.ts` + +**Structure:** + +```typescript +TOOL_SETS = { + core: { queryNodes, getNodesById, queryEdge, queryDimensions, getDimension, searchContentEmbeddings }, + orchestration: { webSearch, think, delegateToMiniRAH, executeWorkflow, ... }, + execution: { createNode, updateNode, createEdge, updateEdge, youtubeExtract, websiteExtract, paperExtract, ... } +} +``` + +--- + +## Key Design Decisions + +### 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. diff --git a/docs/6_ui.md b/docs/6_ui.md index 0ce63e1..56dd006 100644 --- a/docs/6_ui.md +++ b/docs/6_ui.md @@ -1,136 +1,263 @@ # User Interface +> How to navigate and use RA-H'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. + +--- + ## 3-Panel Layout -RA-H uses a fixed 3-panel desktop layout optimized for knowledge work. +``` +┌─────────────┬─────────────────────────┬─────────────────┐ +│ NODES │ FOCUS │ HELPERS │ +│ Panel │ Panel │ Panel │ +│ │ │ │ +│ • Search │ • Tabbed workspace │ • AI chat │ +│ • Filters │ • Node content │ • Easy/Hard │ +│ • Folders │ • Connections │ • Delegations │ +│ │ │ │ +└─────────────┴─────────────────────────┴─────────────────┘ +``` -### Left Panel: Nodes -**Purpose:** Browse and manage your knowledge base +--- -**Features:** -- **Search bar** - Cmd+K global search modal -- **Dimension filters** - Multi-select dimension tags -- **Node list** - Scrollable list of filtered nodes -- **Quick actions** - Pin/unpin, delete, open in focus +## Left Panel: Nodes -**Node display:** +Browse and manage your knowledge base. + +### Features + +- **Search bar** — Cmd+K opens global search modal +- **Dimension filters** — Multi-select dimension tags +- **Node list** — Scrollable list of filtered nodes +- **Folder view toggle** — Switch between list and folder views + +### Node Display + +Each node shows: - Title + description preview -- Dimension tags +- Dimension tags (with custom icons) - Last updated timestamp -- Pin indicator +- Node ID badge -### Middle Panel: Focus -**Purpose:** Active workspace for current node(s) +### Folder View -**Tabbed interface:** -- **Primary tab** - Main focused node -- **Additional tabs** - Related nodes opened from conversations -- **Tab controls** - Close, reorder, switch +Click the folder icon to open the **Folder View Overlay**: -**Node detail view:** -- Full title and content -- Metadata (created, updated, type, link) -- Dimension tags (editable) -- Edge list (incoming/outgoing connections) -- Quick Add bar (bottom) - Create related nodes +**Two Modes:** + +1. **Folders Mode** — Browse by dimension folders + - Each dimension shows as a folder card + - Drag nodes to folders to add dimensions + - Click to view nodes in that dimension + +2. **Filtered View Mode** — Multi-dimension filtering with views + - Add multiple dimension filters + - Choose view layout (List, Grid, Kanban) + - Save views for quick access + +--- + +## Filtered View System + +### View Modes + +| Mode | Description | +|------|-------------| +| **List** | Nodes grouped by dimension with section headers | +| **Grid** | Cards in responsive grid, grouped by dimension | +| **Kanban** | Columns per dimension, drag to move between | + +### Compound Filters (AND Logic) + +Add secondary filters to columns: + +1. Add a filter (e.g., "inbox") +2. Click the `[+ AND]` button next to the dimension name +3. Select secondary dimension (e.g., "research") +4. Column now shows only nodes with BOTH dimensions + +### Saved Views + +Save filter + view combinations: + +1. Configure your filters and view mode +2. Click the save icon +3. Name your view +4. Access from the "Saved Views" dropdown + +### Drag-and-Drop + +- **Reorder nodes** within views +- **Move between Kanban columns** (updates dimensions) +- **Drag from nodes list** to dimension folders + +--- + +## Middle 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 +- **Tab controls** — Close (×), reorder, switch + +### Node Detail View + +| Section | Content | +|---------|---------| +| **Header** | Title, node ID, trash icon | +| **Content** | Full markdown content with syntax highlighting | +| **Metadata** | Created, updated, type, link | +| **Dimensions** | Editable dimension tags | +| **Connections** | Incoming/outgoing edges | + +### Content Rendering -**Content rendering:** - Markdown support -- `[NODE:id:"title"]` auto-links to clickable node references +- `[NODE:id:"title"]` renders as clickable links - Syntax highlighting for code blocks -- YouTube embeds (if link present) +- YouTube embeds (if link is YouTube URL) -### Right Panel: Helpers -**Purpose:** AI conversation interface +--- -**Tabbed interface:** -- **ra-h tab** - Main orchestrator conversation -- **Delegation tabs** - Background worker tasks (mini-rah) -- **Tab lifecycle** - Manual close only (persist until user closes) +## Right Panel: Helpers -**Conversation view:** -- Message history (user + assistant) -- Tool call visibility (collapsed by default) -- Token/cost tracking per message -- Node references auto-linked +AI conversation interface. -**Input controls:** -- Text input with Shift+Enter for multiline -- Submit button -- Mode toggle (⚡ Easy / 🔥 Hard) -- Thread reset button +### Chat Interface -**Mode switching:** -- Easy mode: GPT-5 Mini (fast, cheap) -- Hard mode: Claude Sonnet 4.5 (deep reasoning) -- Seamless mid-conversation switching -- localStorage persists user choice +- **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"]` -## Settings Panel +### Mode Toggle -**Access:** Settings icon (top-right) +``` +┌──────────────────┐ +│ ⚡ Easy │ 🔥 Hard │ +└──────────────────┘ +``` -**Tabs:** -1. **General** - App info, version, data location -2. **Agents** - View agent configurations (ra-h, ra-h-easy, mini-rah, wise-rah) -3. **Workflows** - Available workflows (integrate) -4. **Logs** - Activity feed (last 100 entries) -5. **Analytics** - Token usage and cost breakdown -6. **API Keys** - Configure your Anthropic/OpenAI/Tavily keys (required for operation) +| Mode | Model | Use Case | +|------|-------|----------| +| **Easy** | GPT-5 Mini | Fast, everyday tasks | +| **Hard** | Claude Sonnet 4.5 | Deep reasoning, complex analysis | -**Logs view:** -- Table/action filtering -- Timestamp, table, action, summary -- Detailed JSON snapshot on click -- Real-time updates +Mode persists in localStorage. Switch mid-conversation seamlessly. -**Analytics view:** -- Total tokens used -- Total cost (USD) -- Breakdown by agent -- Breakdown by thread -- Average cost per chat +### Collapsible Panel -## Search (Cmd+K) +- **Toggle:** Cmd+\\ (Mac) / Ctrl+\\ (Windows) +- **Collapsed state:** 48px rail with expand button +- **State persists:** Remembers your preference -**Trigger:** Cmd+K keyboard shortcut - -**4-tier relevance ranking:** -1. **Exact title match** - Highest priority -2. **Title substring** - High priority -3. **FTS content match** - Medium priority -4. **Semantic embedding** - Fallback for conceptual matches - -**Features:** -- Type-ahead search -- Instant results (no search button) -- Click to open node in Focus panel -- Recent searches preserved (session only) - -**UI:** -- Modal overlay -- Search input -- Results list (grouped by relevance tier) -- Keyboard navigation (arrow keys, Enter to select) +--- ## Quick Add -**Location:** Bottom of Focus panel +Bottom of the Helpers panel. Three modes: -**Purpose:** Rapidly create nodes related to current focus +| Mode | Icon | Purpose | +|------|------|---------| +| **Link** | 🔗 | Paste URLs for auto-extraction | +| **Note** | 📄 | Quick note, no AI processing | +| **Chat** | 💬 | Paste conversations | -**Flow:** -1. User types title in Quick Add input -2. Presses Enter -3. System creates node via `createNode` tool -4. Auto-creates edge from focused node to new node -5. New node opens in adjacent tab +Auto-detects mode based on input (URLs trigger Link mode). + +--- + +## Search (Cmd+K) + +Global search modal with 4-tier relevance: + +1. **Exact title match** — Highest priority +2. **Title substring** — High priority +3. **FTS content match** — Medium priority +4. **Semantic embedding** — Conceptual matches **Features:** -- Single-field input (title only) -- Inherit dimensions from focused node -- Automatic edge creation with source='quick_add' -- Real-time feedback (loading state, success confirmation) +- Type-ahead instant results +- Keyboard navigation (↑↓, Enter) +- Click or Enter to open in Focus panel + +--- + +## Settings Panel + +**Access:** Settings cog icon (top-right, green ring) + +**Size:** 88vw × 90vh with glass effect + +### Tabs (in order) + +| 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 | +| **Map** | Knowledge graph visualization | +| **Database** | Full node table with filters/sorting | +| **Logs** | Activity feed (last 100 entries) | +| **Agents** | External agent (MCP) configuration | + +--- + +## Map View + +Visual graph of your knowledge network. + +**Features:** +- Force-directed layout with pan/zoom +- Node size proportional to edge count +- Top 15 nodes labeled (title + dimensions) +- 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 + +Full table view of all nodes. + +**Columns:** +- Node (title + ID) +- Dimensions (folder badges) +- Edges (count) +- Status (context hub indicator) +- Updated (timestamp) + +**Features:** +- Search by title/content +- Filter by dimensions +- Sort by updated/edges/created +- Pagination + +--- + +## Dimension Icons + +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 +4. Icons persist in localStorage + +--- ## Node References @@ -139,31 +266,39 @@ RA-H uses a fixed 3-panel desktop layout optimized for knowledge work. **Rendering:** - Clickable labels in chat messages - Clickable labels in node content -- Hover tooltip with node preview -- Click → open node in Focus panel +- Hover shows preview tooltip +- Click opens in Focus panel -**Usage:** -- Agents automatically use this format -- Middleware converts to clickable UI elements -- Enables knowledge graph navigation from conversations +AI agents automatically use this format for all node mentions. -## Delegation Tabs +--- -**Purpose:** Show background worker task progress +## Keyboard Shortcuts -**Lifecycle:** -- Created when mini-rah delegated -- Persist until manually closed (no auto-cleanup) -- Show task, status, summary, result -- Tool calls visible (collapsed) +| Shortcut | Action | +|----------|--------| +| `Cmd+K` | Open search | +| `Cmd+\\` | Toggle chat panel | +| `Escape` | Close modals/overlays | -**Status indicators:** -- queued - Task waiting -- in_progress - Worker executing -- completed - Success -- failed - Error with details +--- -**Close behavior:** -- Manual close only (X button) -- DELETE request to `/api/rah/delegations/[sessionId]` -- Permanent deletion from database +## Design System + +### Colors + +- **Background:** `#0a0a0a` (near black) +- **Panels:** Subtle gradients distinguishing left/middle/right +- **Accent:** Green (`#22c55e`) for actions, selections +- **Text:** White (primary), neutral-400 (secondary) + +### Typography + +- **Font:** Geist (monospace feel) +- **Sizes:** 11-14px for UI, larger for content + +### Buttons + +- **Primary:** White bg, black text +- **Secondary:** Transparent, border, white text +- **Toggle:** 28×28px, subtle border, icon only diff --git a/docs/7_voice.md b/docs/7_voice.md new file mode 100644 index 0000000..69ce534 --- /dev/null +++ b/docs/7_voice.md @@ -0,0 +1,125 @@ +# 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 70c3767..2a680fe 100644 --- a/docs/8_mcp.md +++ b/docs/8_mcp.md @@ -1,92 +1,101 @@ -# RA-H MCP Server Setup +# RA-H MCP Server -RA-H includes a local Model Context Protocol (MCP) server that lets any MCP-compatible assistant (Claude, ChatGPT, Gemini, etc.) read/write your knowledge graph. Everything runs on `127.0.0.1` and never leaves your machine. +> How to connect Claude Code and other AI assistants to your knowledge base. -## Overview +**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. -The MCP server is a standalone Node.js process that bridges external AI assistants to your local RA-H database. In the open source version, you run this server manually alongside the Next.js dev server. +--- ## Quick Start -### 1. Start the Next.js Server - -```bash -npm run dev -``` - -This starts the web app at `http://localhost:3000`. - -### 2. Start the MCP Server - -In a separate terminal: - -```bash -node apps/mcp-server/server.js -``` - -The MCP server will start on port `44145` by default. - -### 3. Connect Your Assistant - -1. Open **Settings → External Agents** in RA-H and copy the connector URL: `http://127.0.0.1:44145/mcp` -2. In Claude, ChatGPT, or your assistant: - - Open the MCP/connectors panel - - Choose **Add connector → HTTP** - - Paste the URL and name it "RA-H" - -### 4. Use It - -Talk naturally: -- "Summarize this chat and add it to RA-H under Strategy + Q1 Execution." -- "Search RA-H for what I already wrote about Apollo launch delays." +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" ## Available Tools | Tool | Description | |------|-------------| -| `rah_add_node` | Adds a new entry (title/content/dimensions) to the local SQLite graph and triggers auto-embedding. | -| `rah_search_nodes` | Searches existing nodes (title/content/dimensions) before deciding whether to create something new. | +| `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 | -## Claude Desktop (STDIO Connector) +## Claude Code Configuration + +Add to your `~/.claude/claude_desktop_config.json`: + +```json +{ + "mcpServers": { + "ra-h": { + "command": "node", + "args": ["/Users//Desktop/dev/ra-h/apps/mcp-server/stdio-server.js"] + } + } +} +``` + +Or use the HTTP transport if you prefer: + +```json +{ + "mcpServers": { + "ra-h": { + "url": "http://127.0.0.1:44145/mcp" + } + } +} +``` + +**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 /path/to/ra-h_os/apps/mcp-server/stdio-server.js +node /Users//Desktop/dev/ra-h/apps/mcp-server/stdio-server.js ``` -This speaks MCP over stdin/stdout. Add it to `claude_desktop_config.json` or use the "Add MCP Server" CLI flow. Keep the Next.js server running so the STDIO bridge can call `http://127.0.0.1:3000/api/nodes`. +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`. -## Configuration +## HTTP Transport -| Environment Variable | Default | Description | -|---------------------|---------|-------------| -| `MCP_PORT` | `44145` | Port for the HTTP MCP server | -| `RAH_ENABLE_MCP` | `true` | Set to `false` to disable MCP | +For assistants that support HTTP transport: -## Security Notes +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 -- The MCP server only binds to `127.0.0.1` — it's meant for **your** local agents only -- Do not expose it beyond your machine -- Anything the assistant writes is immediately persisted to your local SQLite database -- Review the RA-H activity panel if something looks unexpected +## Example Usage -## Troubleshooting +Once connected, you can: -### Server won't start -- Ensure the Next.js dev server is running first -- Check if port 44145 is already in use: `lsof -i :44145` +``` +"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" +``` -### Connection fails in assistant -- Verify both servers are running (Next.js on 3000, MCP on 44145) -- Try the health endpoint: `curl http://127.0.0.1:44145/status` +## Guardrails -### Tools not working -- The MCP server proxies through `/api/nodes/*` routes — ensure the Next.js server responds -- Check the terminal running the MCP server for error logs +- 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` ## Development -- Implementation: `apps/mcp-server/server.js` (HTTP transport + tool definitions) -- STDIO variant: `apps/mcp-server/stdio-server.js` -- The server proxies through existing `/api/nodes/*` routes, so validation and auto-embed behavior stays consistent +- **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` + +To run standalone (for MCP Inspector): +```bash +node apps/mcp-server/server.js +``` +Requires the Next.js sidecar to be running. diff --git a/docs/README.md b/docs/README.md index 41115ad..fa22d74 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,21 +1,46 @@ -# Documentation +# RA-H Documentation -## Quick Start -See the main [README.md](../README.md) for setup instructions. +Technical documentation for RA-H — AI-powered knowledge management. -## Architecture +## Quick Links -| Document | Description | -|----------|-------------| -| [0_overview.md](0_overview.md) | System overview and philosophy | -| [1_architecture.md](1_architecture.md) | Technical architecture | -| [2_schema.md](2_schema.md) | Database schema and sqlite-vec setup | -| [3_context-and-memory.md](3_context-and-memory.md) | Context system | -| [4_tools-and-workflows.md](4_tools-and-workflows.md) | Agent tools and workflows | -| [5_logging-and-evals.md](5_logging-and-evals.md) | Logging infrastructure | -| [6_ui.md](6_ui.md) | UI components and patterns | -| [8_mcp.md](8_mcp.md) | MCP server setup | -| [9_open-source.md](9_open-source.md) | Open source specific notes | +- **Website:** [ra-h.app](https://ra-h.app) +- **Download:** [ra-h.app/download](https://ra-h.app/download) +- **Open Source:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os) -## Troubleshooting -See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues. +## Documentation Index + +| # | Document | Description | +|---|----------|-------------| +| 0 | [Overview](./0_overview.md) | What is RA-H, design philosophy, tech stack | +| 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, how agents see your knowledge | +| 4 | [Tools & Workflows](./4_tools-and-workflows.md) | Available tools, editable workflows | +| 5 | [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation framework | +| 6 | [UI](./6_ui.md) | 3-panel layout, views, Settings | +| 7 | [Voice](./7_voice.md) | Voice interface (STT/TTS) | +| 8 | [MCP Server](./8_mcp.md) | External agent connector (Claude Code, etc.) | +| 9 | [Open Source](./9_open-source.md) | Sync strategy, repo differences | + +## For Users + +Start here: +1. [Overview](./0_overview.md) — What RA-H is and how it works +2. [MCP Server](./8_mcp.md) — Connect Claude Code to your knowledge base + +## For Developers + +If you're contributing or self-hosting: +1. [Architecture](./1_architecture.md) — Understand the agent hierarchy +2. [Schema](./2_schema.md) — Database structure +3. [Tools & Workflows](./4_tools-and-workflows.md) — How to extend RA-H +4. [Open Source](./9_open-source.md) — Contribution workflow + +## Development Process + +Internal development docs are in `docs/development/`: +- `process/` — Workflow, handoff, kickstart +- `backlog/` — Task backlog +- `prd-*.md` — Product requirement documents +- `completed/` — Archived PRDs