diff --git a/README.md b/README.md index a8b46c1..74d62f0 100644 --- a/README.md +++ b/README.md @@ -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?" diff --git a/docs/0_overview.md b/docs/0_overview.md index ab38187..2005a83 100644 --- a/docs/0_overview.md +++ b/docs/0_overview.md @@ -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 | diff --git a/docs/4_tools-and-guides.md b/docs/4_tools-and-guides.md index 35491e5..6443c22 100644 --- a/docs/4_tools-and-guides.md +++ b/docs/4_tools-and-guides.md @@ -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 | diff --git a/docs/6_ui.md b/docs/6_ui.md index 830595c..87d8495 100644 --- a/docs/6_ui.md +++ b/docs/6_ui.md @@ -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 | --- diff --git a/docs/8_mcp.md b/docs/8_mcp.md index 8a5b6f5..0a624c5 100644 --- a/docs/8_mcp.md +++ b/docs/8_mcp.md @@ -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. diff --git a/docs/README.md b/docs/README.md index 31b0daa..83dc4a9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 |