Oculus Theory Guide

Understanding the "why" behind Oculus

Welcome. Sit down, have some tea, and let me tell you a story about how Oculus works and why it works that way.

This guide is your patient companion - the one who explains not just what to do, but why things are the way they are. If you need quick practical guidance, navigate west to the Agent Admin Guide.

Philosophy: Knowledge as Space

Oculus treats knowledge like physical space. You don't "query" knowledge - you navigate to it. You don't "update records" - you visit a location and leave notes.

This spatial metaphor isn't just aesthetic. It fundamentally changes how you think about information:

• Location matters: Where information lives tells you something about its relationship to other information
• Direction matters: North/south/east/west aren't arbitrary - they encode semantic relationships
• Navigation matters: The path you took to find information is part of understanding it

Why This Guide Exists

The Agent Admin Guide tells you "use peek for simple values." This guide explains:

• Why peek exists separately from look
• What tradeoffs were made in its design
• When the rule "use peek for simple values" breaks down
• How peek relates to the four-layer cache architecture

Guide Structure

Navigate south to explore theoretical foundations:

Each topic corresponds to a practical guide to the west.

Core Principles

1. Caching as Layers of Transformation

Oculus doesn't just cache "the result." It caches each transformation step independently. This means:

• Changes ripple through only what they affect
• Expensive operations stay cached even when cheap ones change
• You can reason about cache behavior predictably

2. Markdown as Executable Structure

Fences aren't "embedded code" in documents. They're first-class callable functions that happen to be stored in markdown. This means:

• Every fence has an identity and can be called directly
• Markdown structure (headings, sections) creates an addressing system
• The graph becomes a filesystem of executable knowledge

3. Composition Over Complexity

Rather than building one powerful query system, Oculus composes simple primitives:

• Variables substitute values (${node:path})
• Includes compose documents (<<include>>)
• Fences execute and inject results
• Middleware transforms outputs

Each layer is simple. Combined, they're extraordinarily expressive.

Why the Dual Guide Structure?

You're reading this guide right now, which means you asked "why?" That's exactly what this guide is for.

The Agent Admin Guide optimizes for action - get the answer, move on.

This guide optimizes for understanding - know why, build intuition.

Together, they create:

• Fast learning: Get practical answers immediately
• Deep learning: Understand theory when you're ready
• Easy navigation: Flip between them as needed

When to Read This Guide

Read the theory guide when:

• You're stuck and the practical guide isn't helping
• You want to understand why a best practice exists
• You're designing new patterns and need to understand constraints
• You're curious about the design philosophy
• You're debugging something unusual and need mental models

Don't read it when:

• You just need to get something done quickly
• You're following a known pattern
• Time is critical

Navigation

• North: Back to main Oculus documentation
• South: Detailed theoretical topics
• East: Related conceptual guides
• West: Agent Admin Guide (practical guidance)

---

For quick answers, go west. For deep understanding, stay here and explore.

Slots

North

slots:
- oculus

South

slots:
- cache-theory
- operation-theory

East

slots: []

West

slots:
- oculus-agent-admin-guide