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
This commit is contained in:
“BeeRad”
+48
-10
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
|
||||
+138
-125
@@ -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.
|
||||
|
||||
+284
-142
@@ -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.
|
||||
|
||||
+256
-121
@@ -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
|
||||
|
||||
+125
@@ -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
|
||||
+72
-63
@@ -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/<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:
|
||||
|
||||
```
|
||||
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 |
|
||||
|---------------------|---------|-------------|
|
||||
| `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.
|
||||
|
||||
+42
-17
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user