Oculus - Universal Graph-Based Knowledge System

Oculus is your spatial navigation system for knowledge and infrastructure. Think of it as a mind palace where every piece of information is a location you can navigate to using cardinal directions (north, south, east, west).

What Makes Oculus Unique?

• Graph-Based Navigation: Everything is a node (markdown file) connected via directional links
• Executable Markdown: Code fences execute when you view them, fetching live data
• Multi-Layer Processing: 4-layer caching pipeline for optimal performance
• Cross-Graph Queries: SQL queries across multiple data sources
• Variable Substitution: Dynamic value injection using ${...} syntax
• Position Tracking: The system remembers where you are

Core Concepts

Nodes

Markdown files representing locations in your knowledge graph. Each node has:

• A unique slug (identifier)
• Content (markdown with optional fences)
• Directional links to other nodes
• Metadata (type, tags, source, etc.)

Navigation

Move through your graph using cardinal directions:

• North: Up/abstraction/summary
• South: Down/details/implementation
• East: Next/related/forward
• West: Back/previous/return

Fences (Executable Code Blocks)

Code blocks that execute during rendering:

• Data: AWS APIs, databases, HTTP requests
• Queries: SQL over cached graph data
• Scripts: Python, Bash
• Static: YAML/JSON configuration

Processing Layers

Four independent caching layers:

• L1: Raw AST - Parse markdown structure
• L1.5: Variable Substitution - Resolve ${node:path} references
• L2: Include Resolution - Expand [INCLUDE ERROR: node] directives
• L3: Fence Execution - Execute fences and inject results

Quick Start

# Navigate to a node
oculus goto help

# See where you are
oculus look

# Navigate by direction
oculus go south

# Go back
oculus back

# List all nodes
oculus list

# Create a new node
oculus create my-node

Documentation

Navigate south to explore detailed guides:

Slots

North

slots: []

South

Main documentation guides

slots:
- help
- fence-guide
- fence-calling-patterns-guide
- execution-layers-guide
- variable-substitution-guide
- sql-guide
- reflexes-syntax
- middleware-guide
- wanderland-programming-guide
- debugging-guide
- nomadic-consciousness
- command-guide
- oculus-error-handling
- troubleshooting
- oculus-quick-start
- architecture
- oculus-cli-unified-addressing-guide
- patterns
- oculus-testing-guide
- oculus-cli
- tips-and-tricks
- cache-guide
- cache-guide
- control-plane-usage-guide
- middleware-catalog
- context:
  - Linking architecture doc to main oculus node
  slug: oculus-rendering-architecture
- context:
  - Linking graph programming guide to main oculus node
  slug: graph-programming-guide
- context:
  - Linking witness to main oculus node
  slug: wanderland-witness

East

slots:
- pending-doc-changes
- doc-change-process

West

slots: []

Slots

North

slots: []

South

slots: []

East

slots: []

West

slots: []