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”
+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.
|
||||
|
||||
Reference in New Issue
Block a user