| title | VisionClaw Documentation |
|---|---|
| description | Complete documentation for VisionClaw — the governed agentic mesh for real-time 3D knowledge graph exploration with GPU-accelerated physics, OWL 2 ontology reasoning, and multi-agent AI orchestration |
| updated-date | 2026-04-09 |
Real-time 3D knowledge graph exploration powered by Rust, CUDA GPU physics, OWL 2 ontology reasoning, and a multi-agent AI mesh.
← Back to Project | Quick Start | API Reference | Architecture
git clone https://github.com/DreamLab-AI/VisionClaw.git
cd VisionClaw && cp .env.example .env
docker-compose --profile dev up -dOpen http://localhost:3001 for the 3D graph interface, http://localhost:4000/api for the REST API, and http://localhost:7474 for the Neo4j browser.
Full setup details: Deployment Guide
Known Issues: Before debugging unexpected behaviour, check KNOWN_ISSUES.md — it tracks active P1/P2 bugs including the Ontology Edge Gap (ONT-001) and V4 delta instability (WS-001).
graph LR
subgraph "Tutorials"
T1[Installation]
T2[First Graph]
T3[Neo4j Basics]
end
subgraph "How-To"
H1[Deployment Guide]
H2[Development Guide]
H3[Agent Orchestration]
H4[Features]
H5[Operations]
end
subgraph "Explanation"
E1[System Overview]
E2[Backend CQRS]
E3[Actor Hierarchy]
E4[Client Architecture]
E5[Ontology Pipeline]
E6[Physics/GPU Engine]
E7[XR Architecture]
end
subgraph "Reference"
R1[REST API]
R2[WebSocket Binary]
R3[Neo4j Schema]
R4[Agents Catalog]
R5[Config & Env]
end
Step-by-step lessons that teach VisionClaw by doing.
| Tutorial | Description |
|---|---|
| What is VisionClaw? | Platform overview and key concepts |
| Installation | Docker and native setup from zero |
| Creating Your First Graph | Build and explore your first knowledge graph |
| Neo4j Basics | Query and navigate the graph database |
Practical task-oriented instructions. See how-to/README.md for the full index.
| Guide | Description |
|---|---|
| Deployment Guide | Docker Compose production deployment with NVIDIA GPU |
| Performance Profiling | GPU physics, WebSocket, render, and Neo4j bottleneck detection |
| Quest 3 VR Setup | Connect a Meta Quest 3 to VisionClaw's immersive XR mode |
| Infrastructure Overview | Goalie integration and infra architecture |
| Port Configuration | Service port mapping and networking |
| Infrastructure Tools | Container management and diagnostic tools |
| Infrastructure Troubleshooting | Container and networking issues |
| Guide | Description |
|---|---|
| Development Guide | Rust/React setup, project structure, testing workflow |
| REST API Integration Guide | NIP-98 auth, common API workflows, WebSocket combination patterns |
| Guide | Description |
|---|---|
| Agent Orchestration | Deploy, configure, and coordinate the multi-agent AI system |
| Guide | Description |
|---|---|
| Navigation Guide | 3D interface controls and spatial navigation |
| Filtering Nodes | Graph node and edge filtering |
| Intelligent Pathfinding | Semantic shortest-path traversal |
| Natural Language Queries | Plain-English graph search |
| Semantic Forces | Stress-majorisation layout algorithm |
| Voice Routing | 4-plane voice architecture with LiveKit |
| Voice Integration | STT/TTS pipeline setup |
| Nostr Auth | NIP-07/NIP-98 authentication |
| Auth & User Settings | User settings and session management |
| Ontology Parser | OWL 2 parsing from Logseq Markdown |
| Hierarchy Integration | Class hierarchy visualisation |
| Local File Sync | GitHub-to-local file synchronisation |
| ComfyUI Setup | ComfyUI SAM3D integration setup |
| Guide | Description |
|---|---|
| Configuration | Environment variables and runtime settings |
| Troubleshooting | Common issues and diagnostic steps |
| Security | Authentication, secrets management, and hardening |
| Telemetry & Logging | Observability and log configuration |
| Pipeline Admin API | Admin endpoints for pipeline management |
| Operator Runbook | Production operations playbook |
| Maintenance | Routine maintenance and upkeep tasks |
| Neo4j Integration | Neo4j database connection and migration |
| Solid Integration | Solid Pod integration overview |
| Solid Pod Creation | Creating and managing user Solid Pods |
| ComfyUI Service | ComfyUI Docker service integration |
Conceptual deep-dives that build understanding of how and why VisionClaw works.
| Document | What it explains |
|---|---|
| System Overview | End-to-end architectural blueprint — all layers and their interactions |
| Backend CQRS Pattern | Hexagonal architecture with 9 ports, 12 adapters, 114 command/query handlers |
| Actor Hierarchy | 21-actor Actix supervision tree — roles, message protocols, failure strategies |
| Client Architecture | React + Three.js component hierarchy, WebGL rendering pipeline, WASM integration |
| DDD Bounded Contexts | Domain-Driven Design context map and aggregate boundaries |
| DDD Identity Contexts | DID/Nostr + PodKey + Passkey identity bounded contexts |
| DDD Semantic Pipeline | Semantic pipeline domain model and context boundaries |
| Ontology Pipeline | GitHub Markdown → OWL 2 → Whelk reasoning → Neo4j → GPU constraints |
| Physics & GPU Engine | CUDA force-directed physics, semantic forces, 55× GPU speedup |
| XR Architecture | WebXR / Babylon.js immersive mode, Vircadia multi-user integration |
| Security Model | Nostr DID auth, Solid Pod sovereignty, CQRS authorization, audit trail |
| Solid Sidecar Architecture | JSON Solid Server sidecar for user Pod storage |
| User-Agent Pod Design | Per-user Solid Pod isolation for agent memory |
| Technology Choices | Rationale for Rust, CUDA, Neo4j, OWL 2, and Three.js selections |
| RuVector Integration | RuVector PostgreSQL as AI agent memory substrate |
| Blender MCP Architecture | Blender remote-control via WebSocket RPC + MCP tools |
| Deployment Topology | Multi-container service map, network architecture, dependency chain, scaling |
| Agent-Physics Bridge | How AI agent lifecycle states synchronise to the 3D physics simulation |
Technical specifications for APIs, schemas, protocols, and configuration.
Full reference index: reference/INDEX.md
| Reference | Contents |
|---|---|
| REST API | All HTTP endpoints — graph, settings, ontology, auth, pathfinding, Solid |
| WebSocket Binary Protocol | Binary V2/V3/V4 message formats, connection lifecycle, client implementation |
| Neo4j Schema | Graph node/edge types, ontology nodes, Solid Pod records, indexes |
| Agents Catalog | Complete catalog of specialist agent skills by domain |
| Error Codes | AP-E, DB-E, GR-E, GP-E, WS-E error code hierarchy with solutions |
| Glossary | Definitions for domain terms used throughout the documentation |
| Performance Benchmarks | GPU physics, WebSocket, and API performance metrics |
| Environment Variables | All .env variables with types, defaults, and descriptions |
| Docker Compose Options | Service profiles, volumes, and compose file structure |
| MCP Protocol | Model Context Protocol specification for agent orchestration |
| Protocol Matrix | Transport protocol comparison — WebSocket, REST, MCP |
| Cargo Commands | Rust build, test, and lint commands |
| Docker Commands | Docker and docker-compose operational commands |
Design decisions recorded as ADRs in docs/adr/.
| ADR | Title |
|---|---|
| ADR-011 | Authentication Enforcement |
| ADR-012 | WebSocket Store Decomposition |
| ADR-013 | Render Performance Strategy |
| ADR-014 | Semantic Pipeline Unification |
| ADR-027 | Pod-Backed Graph Views |
| ADR-028 | SPARQL PATCH for Ontology Mutations |
| ADR-029 | Type Index Discovery |
| ADR-030 | Agent Memory Pods |
| RVF Integration AFD | RuVector Federation Architecture Feature Design |
| RVF Integration DDD | RuVector Federation Domain-Driven Design |
| RVF Integration PRD | RuVector Federation Product Requirements |
Exploratory design documents in docs/design/.
- Nostr Relay Integration — Architecture for VisionClaw ↔ Nostr relay bridging
- Nostr Solid Browser Extension — Browser extension design for Nostr + Solid identity
| Document | Description |
|---|---|
| Testing Guide | Unit, integration, and E2E testing strategy |
| Security | Security model, threat surface, and hardening guidance |
| Infrastructure Inventory | Container services, ports, and environment inventory |
| Contributing | Contribution workflow, branching conventions, code standards |
| Changelog | Version history and release notes |
| Use Cases | Industry use cases and case studies |
| Git Support | Git workflow and branching strategy |
Maintained by DreamLab AI — Issues | Discussions