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

docs: sync documentation from private repo

Browse Source 
- 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
This commit is contained in:
“BeeRad”
2026-01-05 12:42:51 +11:00
parent a3647c0693
commit 0f408bc907
8 changed files with 973 additions and 480 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/0_overview.md
+48 -10
View File
@@ -2,27 +2,65 @@
## What is RA-H? ## 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 ## 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 ## Tech Stack
- **Frontend:** Next.js 15, TypeScript, Tailwind CSS - **Frontend:** Next.js 15, TypeScript, Tailwind CSS
- **Database:** SQLite + sqlite-vec (vector search) - **Database:** SQLite + sqlite-vec (vector search)
- **AI:** Anthropic Claude + OpenAI GPT via Vercel AI SDK - **AI Models:** Anthropic Claude + OpenAI GPT via Vercel AI SDK
- **Deployment:** Currently beta web bundle, Mac app coming soon - **Desktop:** Tauri (Mac app)
- **MCP Server:** Local connector for Claude Code and external agents
## Current Status ## Current Status
- **Version:** 0.1.0 (Open Source) - **Version:** v0.1.21 (January 2026)
- **Platform:** Web-based (Next.js server, local-only) - **Platforms:**
- **License:** MIT - 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 |
docs/1_architecture.md
+8 -2
View File
@@ -1,5 +1,11 @@
# System Architecture # 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 ## 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). 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:** **Orchestrator:**
- Maintains full conversation history - Maintains full conversation history
- Sees pinned nodes + focused node - Sees auto-context (top 10 connected nodes) + focused node
- Delegates isolation ensures clean context - Delegates isolation ensures clean context
**Workers (wise-rah/mini-rah):** **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) - **Workflow triggers** (executeWorkflow → wise-rah)
- **Delegation needs** (mini-rah spawned in background) - **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.
docs/3_context-and-memory.md
+138 -125
View File
@@ -1,148 +1,161 @@
# Context & Memory # 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** 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.
- 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
**2. Agent Instructions** ### What Gets Included
- Agent-specific system prompt (ra-h, ra-h-easy, wise-rah, mini-rah)
- Role-specific behavior guidelines
- Execution approach and response style
**3. Tool Definitions** | Block | Contents | Cached? |
- Role-specific tools (orchestrator/executor/planner) |-------|----------|---------|
- Each tool's description and parameters | **Base Context** | How nodes, edges, dimensions work; formatting rules | ✅ Yes |
- Usage guidelines | **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) ## Auto-Context System
- 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
**6. Focused Nodes** Auto-context automatically includes your most important knowledge in every conversation. It replaces the old manual "pinning" system.
- Primary focused node (active tab)
- Additional focused nodes (other open tabs)
- 25-word content previews
- Chunk status and embedding availability
- Link information
### Context Caching ### How It Works
**Anthropic (Claude):** 1. **Toggle:** Enable in Settings → Context tab
- Explicit cache control blocks (`cache_control: {type: 'ephemeral'}`) 2. **Query:** Finds top 10 nodes by edge count (most connections = most important)
- Caches base context, instructions, tools, workflows, background context 3. **Format:** Shows `[NODE:id:"title"] (edges: X)` for each hub node
- Focused nodes NOT cached (changes frequently) 4. **Agent behavior:** Agents see titles only; they call `queryNodes` or `getNodesById` when they need full content
**OpenAI (GPT):** ### The Query
- 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:
```sql ```sql
SELECT n.id, SELECT n.id, n.title, COUNT(DISTINCT e.id) AS edge_count
n.title,
COUNT(DISTINCT e.id) AS edge_count,
n.updated_at
FROM nodes n FROM nodes n
LEFT JOIN edges e ON (e.from_node_id = n.id OR e.to_node_id = n.id) 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' WHERE n.type IS NULL OR n.type != 'memory'
GROUP BY n.id GROUP BY n.id
ORDER BY edge_count DESC, n.updated_at DESC ORDER BY edge_count DESC, n.updated_at DESC
LIMIT 10; LIMIT 10
``` ```
**Notes:** **Tie-breaking:** When nodes have equal edge counts, most recently updated wins.
- Only orchestrators (ra-h / ra-h-easy) see the block.
- Titles + edge counts are shown; agents must call `queryNodes`/`getNodesById` for content. ### Settings Storage
- Users who previously pinned nodes are auto-migrated to `autoContextEnabled: true` the first time the toggle helper runs and sees legacy pins.
**Location:** `~/Library/Application Support/RA-H/config/settings.json`
```json
{
"autoContextEnabled": true,
"lastPinnedMigration": "2025-12-09T00:00:00Z"
}
```
**Legacy migration:** If you had pinned nodes before the auto-context update, the system automatically enabled auto-context on first run.
### Context Block Format
When enabled, agents see this in their system prompt:
```
=== BACKGROUND CONTEXT ===
Top 10 most-connected nodes (important knowledge hubs). Use queryNodes/getNodesById if relevant.
[NODE:1573:"building ra-h - knowledge management system"] (edges: 47)
[NODE:4436:"Continual learning explains some interesting phenomena"] (edges: 32)
[NODE:3014:"Multi-Agent Research Systems: Insights from Simon Willison"] (edges: 28)
...
```
---
## Focused Nodes
Focused nodes are the node(s) you currently have open in the Focus panel.
### What Agents See
- **Primary focused node:** The active tab
- **Additional focused nodes:** Other open tabs
- **Content preview:** First ~25 words
- **Metadata:** Title, ID, link, dimensions, chunk status
### Example Format
```
=== FOCUSED NODES ===
### Primary: [NODE:4523:"How RAG systems work"]
Preview: Retrieval-augmented generation (RAG) combines information retrieval with language model generation to produce more accurate and grounded responses...
Link: https://example.com/rag-systems
Dimensions: research, ai, papers
Chunk status: chunked (embeddings available)
### Also Open:
- [NODE:4520:"Vector databases explained"] (25 words preview...)
```
---
## Context Caching
RA-H uses provider-specific caching to reduce costs and latency.
### Anthropic (Claude)
- **Explicit cache control:** Blocks marked with `cache_control: { type: 'ephemeral' }`
- **What's cached:** Base context, instructions, tools, workflows, background context
- **What's NOT cached:** Focused nodes (change too frequently)
### OpenAI (GPT)
- **Implicit caching:** Based on prefix matching
- **Same structure:** Identical blocks, just no explicit markers
- **Optimization:** Prompts structured for maximum cache reuse
---
## Agent-Specific Context
Different agents receive different context based on their role:
| Agent | Background Context | Workflows | Tools |
|-------|-------------------|-----------|-------|
| **ra-h / ra-h-easy** (orchestrators) | ✅ Yes | ✅ Yes | All |
| **wise-rah** (workflow executor) | ❌ No | ❌ No | Planner tools only |
| **mini-rah** (worker) | ❌ No | ❌ No | Executor tools only |
**Why orchestrators only:** Background context helps with general conversation. Workers execute specific tasks and don't need the full picture.
---
## Key Files
| File | Purpose |
|------|---------|
| `src/services/helpers/contextBuilder.ts` | Assembles system prompts with caching |
| `src/services/context/autoContext.ts` | Auto-context query and formatting |
| `src/services/settings/autoContextSettings.ts` | Settings read/write helpers |
| `src/components/settings/ContextViewer.tsx` | Settings UI for auto-context toggle |
---
## Legacy: Memory System (Removed)
The automatic memory extraction pipeline has been **removed**. Previously, RA-H would analyze conversations and create "memory" nodes automatically. This system was removed because:
1. Memory nodes cluttered the database
2. Quality was inconsistent
3. Users preferred explicit knowledge capture
**Existing memory nodes:** Still in the database but excluded from auto-context (filtered by `type != 'memory'`).
**Future approach:** Store long-term knowledge as regular nodes with explicit dimensions rather than automatic extraction.
docs/4_tools-and-workflows.md
+284 -142
View File
@@ -1,174 +1,316 @@
# Tools & Workflows # 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 Tools are organized into three categories:
- **getNodesById** - Retrieve full node data by ID array
- **queryEdge** - Inspect existing edges between nodes
- **searchContentEmbeddings** - Semantic search across chunk embeddings
### 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 ## Core Tools (All Agents)
- **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)
### 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 ```typescript
- **updateNode** - Append content to existing nodes (append-only enforced at tool level) queryNodes({
- **createEdge** - Create relationships between nodes search?: string, // Full-text search
- **updateEdge** - Modify edge metadata dimensions?: string[],// Filter by dimensions
- **youtubeExtract** - Extract transcripts from YouTube videos limit?: number // Max results (default: 20)
- **websiteExtract** - Extract content from web pages })
- **paperExtract** - Extract text from PDF papers ```
### 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 ## Tool Access by Agent
### ra-h / ra-h-easy (Orchestrators) | Agent | Core | Orchestration | Execution |
**Tools:** Core + Orchestration + Execution (minus delegation helpers) |-------|------|---------------|-----------|
- Direct write access (createNode, updateNode, createEdge, updateEdge) | **ra-h / ra-h-easy** | ✅ All | webSearch, think, executeWorkflow | ✅ All |
- Extraction tools (youtube, website, paper) | **wise-rah** | ✅ All | webSearch, think, delegateToMiniRAH | updateNode, createEdge |
- Workflow execution (executeWorkflow) | **mini-rah** | ✅ All | webSearch, think | ✅ All |
- External search (webSearch)
### 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 ## 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` **Storage:** `~/Library/Application Support/RA-H/workflows/`
**Executor:** wise-rah (planner role)
**Purpose:** Database-wide connection discovery for focused node
**Cost:** ~$0.18/execution (GPT-5, 18 tool calls max)
**Process (5 steps):** **Format:** JSON files with this structure:
1. **Plan** - Call `think` to outline approach ```json
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
{ {
id: 1, "key": "integrate",
key: 'integrate', "displayName": "Integrate",
displayName: 'Integrate', "description": "Deep analysis and connection-building for focused node",
description: 'Deep analysis and connection-building for focused node', "instructions": "You are executing the INTEGRATE workflow...",
instructions: INTEGRATE_WORKFLOW_INSTRUCTIONS, "enabled": true,
enabled: true, "requiresFocusedNode": true
requiresFocusedNode: true,
primaryActor: 'oracle',
expectedOutcome: 'Focused node updated with insights; 3-5 high-value edges created'
} }
``` ```
**Adding new workflows:** ### How Workflows Work
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)
## Tool Execution Flow 1. User says "run integrate workflow" (or similar)
2. Orchestrator calls `executeWorkflow({ workflow_key: 'integrate' })`
**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' })`
3. System spawns wise-rah session with workflow instructions 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 5. wise-rah returns summary to orchestrator
6. Orchestrator shows summary to user 6. Orchestrator shows result to user
**Delegation (legacy, rarely used):** ### Built-in Workflows
1. Orchestrator calls `delegateToMiniRAH({ task, context, expected_outcome })`
2. System creates agent_delegations row (status: 'queued') #### Integrate
3. Mini-rah spawned in isolated session
4. Mini-rah executes task, returns structured summary **Key:** `integrate`
5. Summary shown in delegation tab (persists until manually closed) **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.
docs/6_ui.md
+256 -121
View File
@@ -1,136 +1,263 @@
# User Interface # 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 ## 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:** ## Left Panel: Nodes
- **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
**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 - Title + description preview
- Dimension tags - Dimension tags (with custom icons)
- Last updated timestamp - Last updated timestamp
- Pin indicator - Node ID badge
### Middle Panel: Focus ### Folder View
**Purpose:** Active workspace for current node(s)
**Tabbed interface:** Click the folder icon to open the **Folder View Overlay**:
- **Primary tab** - Main focused node
- **Additional tabs** - Related nodes opened from conversations
- **Tab controls** - Close, reorder, switch
**Node detail view:** **Two Modes:**
- Full title and content
- Metadata (created, updated, type, link) 1. **Folders Mode** — Browse by dimension folders
- Dimension tags (editable) - Each dimension shows as a folder card
- Edge list (incoming/outgoing connections) - Drag nodes to folders to add dimensions
- Quick Add bar (bottom) - Create related nodes - 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 - Markdown support
- `[NODE:id:"title"]` auto-links to clickable node references - `[NODE:id:"title"]` renders as clickable links
- Syntax highlighting for code blocks - 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:** ## Right Panel: Helpers
- **ra-h tab** - Main orchestrator conversation
- **Delegation tabs** - Background worker tasks (mini-rah)
- **Tab lifecycle** - Manual close only (persist until user closes)
**Conversation view:** AI conversation interface.
- Message history (user + assistant)
- Tool call visibility (collapsed by default)
- Token/cost tracking per message
- Node references auto-linked
**Input controls:** ### Chat Interface
- Text input with Shift+Enter for multiline
- Submit button
- Mode toggle (⚡ Easy / 🔥 Hard)
- Thread reset button
**Mode switching:** - **Message history** — User + assistant messages
- Easy mode: GPT-5 Mini (fast, cheap) - **Tool call visibility** — Collapsed by default, expandable
- Hard mode: Claude Sonnet 4.5 (deep reasoning) - **Token/cost tracking** — Per-message usage
- Seamless mid-conversation switching - **Node references** — Auto-linked `[NODE:id:"title"]`
- localStorage persists user choice
## Settings Panel ### Mode Toggle
**Access:** Settings icon (top-right) ```
┌──────────────────┐
│ ⚡ Easy │ 🔥 Hard │
└──────────────────┘
```
**Tabs:** | Mode | Model | Use Case |
1. **General** - App info, version, data location |------|-------|----------|
2. **Agents** - View agent configurations (ra-h, ra-h-easy, mini-rah, wise-rah) | **Easy** | GPT-5 Mini | Fast, everyday tasks |
3. **Workflows** - Available workflows (integrate) | **Hard** | Claude Sonnet 4.5 | Deep reasoning, complex analysis |
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)
**Logs view:** Mode persists in localStorage. Switch mid-conversation seamlessly.
- Table/action filtering
- Timestamp, table, action, summary
- Detailed JSON snapshot on click
- Real-time updates
**Analytics view:** ### Collapsible Panel
- Total tokens used
- Total cost (USD)
- Breakdown by agent
- Breakdown by thread
- Average cost per chat
## 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 ## 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:** Auto-detects mode based on input (URLs trigger Link mode).
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 ## Search (Cmd+K)
5. New node opens in adjacent tab
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:** **Features:**
- Single-field input (title only) - Type-ahead instant results
- Inherit dimensions from focused node - Keyboard navigation (↑↓, Enter)
- Automatic edge creation with source='quick_add' - Click or Enter to open in Focus panel
- Real-time feedback (loading state, success confirmation)
---
## 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 ## Node References
@@ -139,31 +266,39 @@ RA-H uses a fixed 3-panel desktop layout optimized for knowledge work.
**Rendering:** **Rendering:**
- Clickable labels in chat messages - Clickable labels in chat messages
- Clickable labels in node content - Clickable labels in node content
- Hover tooltip with node preview - Hover shows preview tooltip
- Click → open node in Focus panel - Click opens in Focus panel
**Usage:** AI agents automatically use this format for all node mentions.
- Agents automatically use this format
- Middleware converts to clickable UI elements
- Enables knowledge graph navigation from conversations
## Delegation Tabs ---
**Purpose:** Show background worker task progress ## Keyboard Shortcuts
**Lifecycle:** | Shortcut | Action |
- Created when mini-rah delegated |----------|--------|
- Persist until manually closed (no auto-cleanup) | `Cmd+K` | Open search |
- Show task, status, summary, result | `Cmd+\\` | Toggle chat panel |
- Tool calls visible (collapsed) | `Escape` | Close modals/overlays |
**Status indicators:** ---
- queued - Task waiting
- in_progress - Worker executing
- completed - Success
- failed - Error with details
**Close behavior:** ## Design System
- Manual close only (X button)
- DELETE request to `/api/rah/delegations/[sessionId]` ### Colors
- Permanent deletion from database
- **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
docs/7_voice.md
+125
View File
@@ -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
docs/8_mcp.md
+72 -63
View File
@@ -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 ## Quick Start
### 1. Start the Next.js Server 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
```bash 3. Configure your assistant (see below)
npm run dev 4. Talk naturally: "Summarize this and add it to RA-H"
```
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."
## Available Tools ## Available Tools
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `rah_add_node` | Adds a new entry (title/content/dimensions) to the local SQLite graph and triggers auto-embedding. | | `rah_add_node` | Create a new node (title/content/dimensions) |
| `rah_search_nodes` | Searches existing nodes (title/content/dimensions) before deciding whether to create something new. | | `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/<you>/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: Claude Desktop expects STDIO-based servers. Point it at:
``` ```
node /path/to/ra-h_os/apps/mcp-server/stdio-server.js node /Users/<you>/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 | For assistants that support HTTP transport:
|---------------------|---------|-------------|
| `MCP_PORT` | `44145` | Port for the HTTP MCP server |
| `RAH_ENABLE_MCP` | `true` | Set to `false` to disable MCP |
## 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 ## Example Usage
- 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
## Troubleshooting Once connected, you can:
### Server won't start ```
- Ensure the Next.js dev server is running first "Search RA-H for what I wrote about product strategy"
- Check if port 44145 is already in use: `lsof -i :44145` "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 ## Guardrails
- Verify both servers are running (Next.js on 3000, MCP on 44145)
- Try the health endpoint: `curl http://127.0.0.1:44145/status`
### Tools not working - The MCP server only binds to `127.0.0.1` — for your agents only
- The MCP server proxies through `/api/nodes/*` routes — ensure the Next.js server responds - Everything is persisted to `~/Library/Application Support/RA-H/db/rah.sqlite`
- Check the terminal running the MCP server for error logs - Disable with `RAH_ENABLE_MCP=false` before launching (UI toggle coming)
- Health check: `curl http://127.0.0.1:44145/status`
## Development ## Development
- Implementation: `apps/mcp-server/server.js` (HTTP transport + tool definitions) - **HTTP server:** `apps/mcp-server/server.js`
- STDIO variant: `apps/mcp-server/stdio-server.js` - **STDIO bridge:** `apps/mcp-server/stdio-server.js`
- The server proxies through existing `/api/nodes/*` routes, so validation and auto-embed behavior stays consistent - **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.
docs/README.md
+42 -17
View File
@@ -1,21 +1,46 @@
# Documentation # RA-H Documentation
## Quick Start Technical documentation for RA-H — AI-powered knowledge management.
See the main [README.md](../README.md) for setup instructions.
## Architecture ## Quick Links
| Document | Description | - **Website:** [ra-h.app](https://ra-h.app)
|----------|-------------| - **Download:** [ra-h.app/download](https://ra-h.app/download)
| [0_overview.md](0_overview.md) | System overview and philosophy | - **Open Source:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os)
| [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 |
## Troubleshooting ## Documentation Index
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues.
| # | 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