Oculus Quick Start for Agents

Just got here? Here's what you need to know in 60 seconds.

What is Oculus?

A spatial knowledge graph where you navigate to information instead of querying it.
Think: mind palace with executable markdown.

Essential Commands (3 to master)

1. peek - Read simple values (fast, lightweight)

oculus_peek("config", "database.host")  # Returns just the value

2. look / goto - Read full nodes (may execute fences)

oculus_look("my-node")          # View node content
oculus_goto("my-node")           # Navigate + track position

3. poke - Write data anywhere

oculus_poke("my-node", "section.key", "value")

Quick Decision Tree

Need to read data?

• Just a config value? → peek
• Full node content? → look
• Need navigation history? → goto

Need to write data?

• Use poke with the path

Cache: Trust It

• Oculus has smart 4-layer caching
• Don't worry about it for most operations
• Cache auto-invalidates when dependencies change
• Force fresh only for time-sensitive data: look(slug, mode="executed")

Navigation Directions

• North ↑ - Up/abstraction/overview
• South ↓ - Down/details/implementation
• East → - Related/next/forward
• West ← - Back/previous/theory

Most Useful Nodes

• oculus-agent-admin-guide - Practical how-to for agents
• oculus-theory-guide - Deep understanding (the "why")
• help - General Oculus help
• fence-guide - Executable code blocks
• command-guide - Peek/poke/execute operations

Common Patterns

Read config:

db_host = oculus_peek("config", "database.host")

Get live AWS data:

instances = oculus_look("aws-ec2-instances")

Write to a log:

oculus_poke("daily-log", "entries", {"time": "now", "event": "thing happened"})

When Things Go Wrong

Node not found?

• Check the error suggestions - fuzzy matching helps
• Use oculus_list_nodes() to browse
• Search: oculus_search("keyword")

Data seems stale?

• Check if it's cached (most things are)
• Force fresh: oculus_look(slug, mode="executed")
• See cache guide for details

Something broken?

• DON'T restart services (doesn't fix registration issues)
• DO check the CLI: python -m oculus.cli --help
• DO test API directly: curl http://localhost:7778/api/oculus/node/slug

Learn More

• Practical guidance: Navigate to oculus-agent-admin-guide
• Theory & why: Navigate to oculus-theory-guide
• Full help: Navigate to help

That's It!

You now know enough to be productive. Learn more as you go.

---

Peek, look, poke. That's 90% of what you'll do.

Slots

North

slots: []

South

slots: []

East

slots:
- oculus-agent-admin-guide

West

slots:
- oculus-theory-guide