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

docs(product): update user docs to skills-first and current MCP tools

Browse Source
This commit is contained in:
“BeeRad”
2026-03-07 13:48:00 +11:00
parent bc226b03c8
commit 053c163e31
6 changed files with 94 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+20 -20
View File
@@ -101,7 +101,7 @@ Add to your `~/.claude.json`:
Restart Claude Code fully (**Cmd+Q on Mac**, not just closing the window).
**Verify it worked:** Ask Claude "Do you have rah_ tools available?" — you should see tools like `rah_add_node`, `rah_search_nodes`, etc.
**Verify it worked:** Ask Claude "Do you have RA-H tools available?" — you should see tools like `createNode`, `queryNodes`, and `readSkill`.
**For contributors** testing local changes, use the local path instead:
```json
@@ -115,30 +115,30 @@ Restart Claude Code fully (**Cmd+Q on Mac**, not just closing the window).
}
```
**What happens:** Once connected, Claude calls `rah_get_context` first to orient itself (stats, hub nodes, dimensions, available guides). It proactively captures knowledge — when a new insight, decision, person, or reference surfaces, it proposes a specific node (title, dimensions, description) so you can approve with minimal friction. For complex tasks it reads guides to understand your graph conventions and custom workflows.
**What happens:** Once connected, Claude calls `getContext` first to orient itself (stats, hub nodes, dimensions, available skills). It proactively captures knowledge — when a new insight, decision, person, or reference surfaces, it proposes a specific node (title, dimensions, description) so you can approve with minimal friction. For complex tasks it reads skills to follow your graph conventions and workflows.
Available tools:
| Tool | What it does |
|------|--------------|
| `rah_get_context` | Get graph overview — stats, hub nodes, dimensions, recent activity |
| `rah_search_nodes` | Find nodes by keyword |
| `rah_add_node` | Create a new node |
| `rah_get_nodes` | Fetch nodes by ID |
| `rah_update_node` | Edit an existing node |
| `rah_create_edge` | Link two nodes together |
| `rah_update_edge` | Update an edge explanation |
| `rah_query_edges` | Find connections |
| `rah_list_dimensions` | List all tags/categories |
| `rah_create_dimension` | Create a new dimension |
| `rah_update_dimension` | Update/rename a dimension |
| `rah_delete_dimension` | Delete a dimension |
| `rah_list_guides` | List available guides (system + custom) |
| `rah_read_guide` | Read a guide by name |
| `rah_write_guide` | Create or update a custom guide |
| `rah_delete_guide` | Delete a custom guide |
| `rah_search_content` | Search through source content (transcripts, books, articles) |
| `rah_sqlite_query` | Run read-only SQL queries (SELECT/WITH/PRAGMA) |
| `getContext` | Get graph overview — stats, hub nodes, dimensions, recent activity |
| `queryNodes` | Find nodes by keyword |
| `createNode` | Create a new node |
| `getNodesById` | Fetch nodes by ID |
| `updateNode` | Edit an existing node |
| `createEdge` | Link two nodes together |
| `updateEdge` | Update an edge explanation |
| `queryEdge` | Find connections |
| `queryDimensions` | List all tags/categories |
| `createDimension` | Create a new dimension |
| `updateDimension` | Update/rename a dimension |
| `deleteDimension` | Delete a dimension |
| `listSkills` | List available skills |
| `readSkill` | Read a skill by name |
| `writeSkill` | Create or update a custom skill |
| `deleteSkill` | Delete a custom skill |
| `searchContentEmbeddings` | Search through source content (transcripts, books, articles) |
| `sqliteQuery` | Run read-only SQL queries (SELECT/WITH/PRAGMA) |
**Example prompts for Claude Code:**
- "What's in my knowledge graph?"
docs/0_overview.md
+4 -4
View File
@@ -26,8 +26,8 @@ RA-OS is a minimal knowledge graph UI with MCP server integration. It provides a
- 2-panel UI (nodes list + focus panel)
- Node/Edge/Dimension CRUD
- Full-text and semantic search
- MCP server with 14 tools
- Guides system (context for external agents)
- MCP server with graph and skill tools
- Skills system (shared instructions for internal + external agents)
- PDF extraction
- Graph visualization (Map view)
- BYO API keys
@@ -71,14 +71,14 @@ RA-OS is designed to be the knowledge backend for your AI workflows:
Add this to `~/.claude.json` and restart Claude. Works without RA-OS running.
Available tools: `rah_add_node`, `rah_search_nodes`, `rah_update_node`, `rah_get_nodes`, `rah_create_edge`, `rah_query_edges`, `rah_list_dimensions`, `rah_create_dimension`, `rah_update_dimension`, `rah_delete_dimension`
Core tools include: `createNode`, `queryNodes`, `updateNode`, `getNodesById`, `createEdge`, `queryEdge`, `queryDimensions`, `createDimension`, `updateDimension`, `deleteDimension`, `listSkills`, `readSkill`
## Documentation
| Doc | Description |
|-----|-------------|
| [Schema](./2_schema.md) | Database schema, node/edge structure |
| [Tools & Guides](./4_tools-and-guides.md) | Available MCP tools, guide system |
| [Tools & Skills](./4_tools-and-guides.md) | Available MCP tools, skill system |
| [UI](./6_ui.md) | Component structure, panels, views |
| [MCP](./8_mcp.md) | External agent connector setup |
| [Troubleshooting](./TROUBLESHOOTING.md) | Common issues and fixes |
docs/4_tools-and-guides.md
+46 -176
View File
@@ -1,203 +1,75 @@
# Tools & Guides
# Tools & Skills
> MCP tools for external agents and the guides system for context sharing.
> MCP tools for graph operations and skills for procedural guidance.
**How it works:** RA-OS exposes tools via MCP that external AI agents can call to read, create, and update your knowledge graph. Guides are markdown documents that help external agents understand your knowledge base.
**How it works:** External agents call MCP tools to read and write your graph. For complex tasks, they read skills (`listSkills`/`readSkill`) to follow your preferred operating patterns.
---
## MCP Tools
RA-OS provides 14 MCP tools for external agents:
RA-OS exposes these core standalone MCP tools:
### Node Operations
### Context + Graph
| Tool | Description |
|------|-------------|
| `rah_add_node` | Create a new knowledge node |
| `rah_search_nodes` | Search nodes by title, content, or dimensions |
| `rah_update_node` | Update an existing node |
| `rah_get_nodes` | Get nodes by ID array |
| `getContext` | Graph overview: stats, hub nodes, dimensions, recent activity, skills |
| `queryNodes` | Search nodes by keyword/dimensions/date |
| `getNodesById` | Fetch full nodes by ID |
| `createNode` | Create a node |
| `updateNode` | Update a node |
| `createEdge` | Create an edge between nodes |
| `queryEdge` | Query edges |
| `updateEdge` | Update edge explanation |
| `queryDimensions` | List dimensions |
| `createDimension` | Create a dimension |
| `updateDimension` | Update/rename a dimension |
| `deleteDimension` | Delete a dimension |
### Edge Operations
### Skills + Search
| Tool | Description |
|------|-------------|
| `rah_create_edge` | Create relationship between nodes |
| `rah_query_edges` | Query existing edges |
| `rah_update_edge` | Update edge metadata |
### Dimension Operations
| Tool | Description |
|------|-------------|
| `rah_create_dimension` | Create a new dimension tag |
| `rah_update_dimension` | Update dimension description |
| `rah_delete_dimension` | Delete a dimension |
### Search
| Tool | Description |
|------|-------------|
| `rah_search_embeddings` | Semantic search across chunk embeddings |
### Guides
| Tool | Description |
|------|-------------|
| `rah_list_guides` | List all available guides |
| `rah_read_guide` | Read a specific guide's content |
| `rah_write_guide` | Create or update a guide |
| `listSkills` | List available skills |
| `readSkill` | Read one skill |
| `writeSkill` | Create/update a skill |
| `deleteSkill` | Delete a skill |
| `searchContentEmbeddings` | Search source chunks/transcripts |
| `sqliteQuery` | Read-only SQL (`SELECT`, `WITH`, `PRAGMA`) |
---
## Tool Schemas
## Skills
### rah_add_node
Skills are markdown instructions stored locally and shared across internal + external agents.
```typescript
{
title: string, // Required
content?: string,
description?: string,
dimensions?: string[],
link?: string,
metadata?: object
}
```
### Default seeded skills
### rah_search_nodes
- `db-operations`
- `create-skill`
- `audit`
- `traverse`
- `onboarding`
- `persona`
- `calibration`
- `connect`
```typescript
{
search?: string, // Full-text search
dimensions?: string[],// Filter by dimensions
limit?: number // Max results (default: 20)
}
```
### Storage
### rah_update_node
```typescript
{
id: number, // Node ID
title?: string,
content?: string, // Replaces existing content
description?: string,
dimensions?: string[],
link?: string,
metadata?: object
}
```
### rah_create_edge
```typescript
{
from_node_id: number,
to_node_id: number,
context?: string // Relationship description
}
```
### rah_search_embeddings
```typescript
{
query: string, // Search query
node_id?: number, // Scope to specific node
limit?: number, // Max results
threshold?: number // Similarity threshold (0-1)
}
```
---
## Guides
Guides are markdown documents stored in `src/config/guides/` that help external AI agents understand your knowledge base context, conventions, and usage patterns.
### Why Guides?
When an external agent (like Claude Code) connects to RA-H via MCP, it has access to tools but lacks context about:
- How your knowledge base is organized
- What dimensions mean in your system
- Best practices for creating/linking nodes
- Your specific workflows and conventions
Guides bridge this gap by providing structured documentation that agents can read.
### Managing Guides
**Via UI:**
1. Open Settings (gear icon)
2. Click the "Guides" tab
3. Create, edit, or delete guides
**Via Pane:**
- Click the Guides icon in the left toolbar
- Browse and read guides directly
### Built-in Guides
| Guide | Purpose |
|-------|---------|
| `connect` | How to find and create connections between nodes |
| `integrate` | Deep analysis and integration patterns |
| `prep` | Preparing content for the knowledge base |
| `research` | Research workflow patterns |
| `survey` | Survey and discovery patterns |
### Creating Custom Guides
Guides use markdown with optional YAML frontmatter:
```markdown
---
description: Brief description shown in guide list
---
# Guide Title
Your guide content here...
```
- Live skills: `~/Library/Application Support/RA-H/skills/`
- Bundled defaults: `src/config/skills/`
---
## API Routes
RA-OS exposes REST APIs that MCP tools call internally:
| Route | Method | Purpose |
|-------|--------|---------|
| `/api/nodes` | GET/POST | List/create nodes |
| `/api/nodes/[id]` | GET/PUT/DELETE | Node CRUD |
| `/api/nodes/search` | POST | Search nodes |
| `/api/edges` | GET/POST | List/create edges |
| `/api/edges/[id]` | GET/PUT/DELETE | Edge CRUD |
| `/api/dimensions` | GET/POST | List/create dimensions |
| `/api/dimensions/search` | GET | Search dimensions |
| `/api/guides` | GET | List guides |
| `/api/guides/[name]` | GET/PUT/DELETE | Guide CRUD |
---
## Database Tools (Internal)
These tools are used by APIs and internal operations:
| Tool | File | Purpose |
|------|------|---------|
| `queryNodes` | `src/tools/database/queryNodes.ts` | Search nodes |
| `createNode` | `src/tools/database/createNode.ts` | Create node |
| `updateNode` | `src/tools/database/updateNode.ts` | Update node |
| `deleteNode` | `src/tools/database/deleteNode.ts` | Delete node |
| `getNodesById` | `src/tools/database/getNodesById.ts` | Get by ID |
| `createEdge` | `src/tools/database/createEdge.ts` | Create edge |
| `updateEdge` | `src/tools/database/updateEdge.ts` | Update edge |
| `queryEdge` | `src/tools/database/queryEdge.ts` | Query edges |
| `queryDimensions` | `src/tools/database/queryDimensions.ts` | Query dimensions |
| `searchContentEmbeddings` | `src/tools/other/searchContentEmbeddings.ts` | Semantic search |
| `/api/skills` | GET | List skills |
| `/api/skills/[name]` | GET/PUT/DELETE | Skill CRUD |
| `/api/guides` | GET | Compatibility alias to skills |
| `/api/guides/[name]` | GET/PUT/DELETE | Compatibility alias to skills |
---
@@ -205,9 +77,7 @@ These tools are used by APIs and internal operations:
| File | Purpose |
|------|---------|
| `apps/mcp-server-standalone/` | **Standalone MCP server (recommended)** |
| `apps/mcp-server/server.js` | HTTP MCP server (requires app running) |
| `apps/mcp-server/stdio-server.js` | STDIO bridge to HTTP server |
| `src/tools/infrastructure/registry.ts` | Tool registry |
| `src/services/guides/guideService.ts` | Guide management |
| `src/config/guides/*.md` | Built-in guides |
| `apps/mcp-server-standalone/` | Standalone MCP server (recommended) |
| `src/services/skills/skillService.ts` | Skills runtime service |
| `src/config/skills/*.md` | Bundled default skills |
| `src/components/panes/SkillsPane.tsx` | Skills pane UI |
docs/6_ui.md
+3 -3
View File
@@ -2,7 +2,7 @@
> How to navigate and use RA-OS's interface.
**How it works:** RA-OS uses a 2-panel layout: browse nodes on the left, work with focused content on the right. Settings give you access to workflows, database views, a knowledge map, and more.
**How it works:** RA-OS uses a 2-panel layout: browse nodes on the left, work with focused content on the right. Settings give you access to skills, database views, logs, tools, and MCP setup.
---
@@ -149,11 +149,11 @@ Global search modal with 4-tier relevance:
| Tab | Purpose |
|-----|---------|
| **API Keys** | Configure OpenAI/Tavily keys |
| **Workflows** | View, edit, create workflows |
| **Skills** | View, edit, create skills |
| **Tools** | View available tools |
| **Map** | Knowledge graph visualization |
| **Database** | Full node table with filters/sorting |
| **Logs** | Activity feed (last 100 entries) |
| **Context** | Context/system information viewer |
| **Agents** | External agent (MCP) configuration |
---
docs/8_mcp.md
+20 -18
View File
@@ -76,22 +76,24 @@ If you want real-time UI updates when nodes are created:
| Tool | Description |
|------|-------------|
| `rah_get_context` | Get graph overview — stats, hub nodes, dimensions, recent activity. Called first automatically. |
| `rah_add_node` | Create a new node (title/content/dimensions) |
| `rah_search_nodes` | Search existing nodes by keyword |
| `rah_update_node` | Update an existing node |
| `rah_get_nodes` | Get nodes by ID |
| `rah_create_edge` | Create relationship between nodes |
| `rah_update_edge` | Update an edge explanation |
| `rah_query_edges` | Query existing edges |
| `rah_list_dimensions` | List all dimensions |
| `rah_create_dimension` | Create a new dimension |
| `rah_update_dimension` | Update/rename dimension |
| `rah_delete_dimension` | Delete a dimension |
| `rah_list_guides` | List available guides (system + custom) |
| `rah_read_guide` | Read a guide by name |
| `rah_write_guide` | Create or update a custom guide |
| `rah_delete_guide` | Delete a custom guide |
| `getContext` | Get graph overview — stats, hub nodes, dimensions, recent activity. Called first automatically. |
| `createNode` | Create a new node (title/content/dimensions) |
| `queryNodes` | Search existing nodes by keyword |
| `updateNode` | Update an existing node |
| `getNodesById` | Get nodes by ID |
| `createEdge` | Create relationship between nodes |
| `updateEdge` | Update an edge explanation |
| `queryEdge` | Query existing edges |
| `queryDimensions` | List all dimensions |
| `createDimension` | Create a new dimension |
| `updateDimension` | Update/rename dimension |
| `deleteDimension` | Delete a dimension |
| `listSkills` | List available skills |
| `readSkill` | Read a skill by name |
| `writeSkill` | Create or update a custom skill |
| `deleteSkill` | Delete a custom skill |
| `searchContentEmbeddings` | Search extracted source content |
| `sqliteQuery` | Run read-only SQL queries |
---
@@ -99,9 +101,9 @@ If you want real-time UI updates when nodes are created:
Once connected, the MCP server instructs Claude to:
1. **Call `rah_get_context` first** to orient itself (hub nodes, dimensions, stats, available guides)
1. **Call `getContext` first** to orient itself (hub nodes, dimensions, stats, available skills)
2. **Proactively capture knowledge** — when a new insight, decision, person, or reference surfaces, it proposes a specific node (title, dimensions, description) so you can approve with minimal friction
3. **Read guides for complex tasks** — system guides (immutable) teach it how your graph works; custom guides teach it your workflows
3. **Read skills for complex tasks** — skills provide reusable procedural instructions for graph operations and workflows
4. **Search before creating** to avoid duplicates
You don't need to ask Claude to use your knowledge base — it will offer when it spots something worth saving.
docs/README.md
+1 -1
View File
@@ -15,7 +15,7 @@
|-----|-------------|
| [Overview](./0_overview.md) | What is RA-OS, design philosophy |
| [Schema](./2_schema.md) | Database schema, node/edge structure |
| [Tools & Guides](./4_tools-and-guides.md) | MCP tools, guide system |
| [Tools & Skills](./4_tools-and-guides.md) | MCP tools, skill system |
| [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation framework |
| [UI](./6_ui.md) | 2-panel layout, components, views |
| [MCP](./8_mcp.md) | Connect Claude Code and external agents |