“BeeRad”
0f408bc907
- 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
113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
# System Architecture
|
|
|
|
> How RA-H's AI agents work together to manage your knowledge.
|
|
|
|
**How it works:** RA-H has three AI agents: orchestrators (ra-h/ra-h-easy) handle your conversations and delegate work, wise-rah executes multi-step workflows, and mini-rah handles background tasks. All agents can read your knowledge graph; only some can write.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
RA-H uses a multi-agent architecture with three specialized AI agents that collaborate to manage your knowledge base. The system is built around **nodes** (knowledge items), **edges** (relationships), and **dimensions** (categories).
|
|
|
|
## Core Concepts
|
|
|
|
### Nodes
|
|
Knowledge items stored in the database (papers, ideas, people, projects, videos, tweets, etc). Each node has:
|
|
- **Title** and **content**
|
|
- **Dimensions** (multi-tag categorization)
|
|
- **Metadata** (structured JSON)
|
|
- **Embeddings** (for semantic search)
|
|
- **Links** (for external sources)
|
|
|
|
### Edges
|
|
Directed relationships between nodes. Edges capture how nodes connect ("relates to", "inspired by", etc).
|
|
|
|
### Dimensions
|
|
Multi-select categorization tags. Nodes can have multiple dimensions. Some dimensions can be marked as "priority" for focused context.
|
|
|
|
## Agent Architecture
|
|
|
|
### Orchestrator Agents (Easy/Hard Mode)
|
|
|
|
**ra-h-easy (Easy Mode - Default)**
|
|
- **Model:** GPT-5 Mini (`openai/gpt-5-mini`)
|
|
- **Purpose:** Fast, low-latency orchestration for everyday tasks
|
|
- **Caching:** OpenAI implicit caching
|
|
- **Reasoning:** `reasoning_effort: light` for speed
|
|
|
|
**ra-h (Hard Mode)**
|
|
- **Model:** Claude Sonnet 4.5 (`anthropic/claude-sonnet-4.5`)
|
|
- **Purpose:** Deep reasoning for complex tasks
|
|
- **Caching:** Anthropic explicit prompt caching
|
|
- **Reasoning:** Stronger analytical capabilities
|
|
|
|
**Tools Available:**
|
|
- `queryNodes`, `queryEdge`, `searchContentEmbeddings`
|
|
- `webSearch`, `think`
|
|
- `executeWorkflow` (delegates to wise-rah)
|
|
- `createNode`, `updateNode`, `createEdge`, `updateEdge`
|
|
- `youtubeExtract`, `websiteExtract`, `paperExtract`
|
|
|
|
**Mode Switching:**
|
|
Users toggle via UI (⚡ Easy / 🔥 Hard). Choice persists in localStorage. **Seamless mid-conversation switching** - context maintained across mode changes.
|
|
|
|
### Wise RA-H (Workflow Executor)
|
|
|
|
**wise-rah**
|
|
- **Model:** GPT-5 (`openai/gpt-5`)
|
|
- **Purpose:** Executes predefined workflows (integrate, deep analysis)
|
|
- **Direct write access:** Calls `updateNode` directly (no delegation)
|
|
- **Context isolation:** Returns summaries only to orchestrator
|
|
|
|
**Tools Available:**
|
|
- `queryNodes`, `getNodesById`, `queryEdge`, `searchContentEmbeddings`
|
|
- `webSearch`, `think`
|
|
- `updateNode` (append-only, enforced at tool level)
|
|
|
|
**Key Workflows:**
|
|
- **Integrate:** Database-wide connection discovery (5-step: plan → ground → search → contextualize → append)
|
|
|
|
### Mini RA-H (Delegate Workers)
|
|
|
|
**mini-rah**
|
|
- **Model:** GPT-4o Mini (`openai/gpt-4o-mini`)
|
|
- **Purpose:** Spawned for write operations, extraction, batch tasks
|
|
- **Execution:** Isolated context, returns summaries only
|
|
|
|
**Tools Available:**
|
|
- All read tools + `createNode`, `updateNode`, `createEdge`, `updateEdge`
|
|
- Extraction tools (`youtubeExtract`, `websiteExtract`, `paperExtract`)
|
|
|
|
## Prompt Caching
|
|
|
|
**Anthropic (Claude):**
|
|
- Explicit cache control blocks in system prompts
|
|
- Caches tool definitions, workflows, base context
|
|
|
|
**OpenAI (GPT-5/4o):**
|
|
- Implicit caching based on prefix matching
|
|
- Optimized prompts for cache reuse
|
|
- `reasoning_effort` parameter for speed/quality tradeoff
|
|
|
|
## Context Hygiene
|
|
|
|
**Orchestrator:**
|
|
- Maintains full conversation history
|
|
- Sees auto-context (top 10 connected nodes) + focused node
|
|
- Delegates isolation ensures clean context
|
|
|
|
**Workers (wise-rah/mini-rah):**
|
|
- Execute in isolated sessions
|
|
- Return structured summaries only
|
|
- Do NOT pollute orchestrator context with tool execution details
|
|
|
|
## UI Integration
|
|
|
|
Users interact with a single interface that automatically routes requests to the appropriate agent based on:
|
|
- **Mode selection** (Easy/Hard)
|
|
- **Workflow triggers** (executeWorkflow → wise-rah)
|
|
- **Delegation needs** (mini-rah spawned in background)
|
|
|
|
Orchestrators see **auto-context** (your 10 most-connected nodes) plus the **focused node** for consistent knowledge access. See [Context & Memory](./3_context-and-memory.md) for details.
|