lantern

wanderland-platform-architecture

Wanderland: Technical Architecture

Executive Summary

Wanderland represents a synthesis of executable documentation, spatial knowledge graphs, and multi-agent coordination. Built on a markdown substrate, it unifies code, documentation, and execution environment into a single reflexive system.

Core Innovation: A computational substrate where documentation IS code IS navigation IS the execution environment—all expressed in standard markdown.

Paradigm-Level System Comparison

Feature Matrix: Computing Substrate Innovations

Feature Knuth (TeX/WEB) Kay (Smalltalk) Ingalls (Squeak) Victor (Explorable) Wanderland
Documentation = Code ✓ Static ✗ Separate ✗ Separate ✓ Dynamic ✓ Live Executable
Self-Modifying ✗ ✓ Runtime ✓ Runtime ✗ ✓ Runtime + Reflexive
Live Environment ✗ Compiled ✓ ✓ ✓ Interactive ✓ WebSocket Live
Visual/Spatial ✗ Text only ✗ Object-based ✓ Morphic ✓ Central feature ✓ 32D Navigation
Turtles All The Way ✗ ✓ ✓ ✗ ✓ Markdown substrate
Human Readable ✓ ✗ Specialized ✗ Specialized ✓ ✓ Plain markdown
Multi-Agent ✗ ✗ ✗ ✗ ✓ MCP coordination
Autonomous Execution ✗ ✗ ✗ ✗ ✓ Event loop + Cases
Spatial Navigation ✗ ✗ ✗ ✓ Visual only ✓ Cardinal + Depth
Self-Healing ✗ ✗ ✗ ✗ ✓ Constraint-based
Attention System ✗ ✗ ✗ ✗ ✓ Pre-computation
Working Memory ✗ ✗ ✗ ✗ ✓ Detective cases
Brain-Inspired ✗ ✗ ✗ ✗ ✓ Hippocampus/Amygdala
Query Language ✗ ✗ ✗ ✗ ✓ Graph traversal
Multi-Modal Cache ✗ ✗ ✗ ✗ ✓ 4-tier system

Historical Context and Evolution

Donald Knuth - TeX & Literate Programming (1978-1984)

Core Innovation: Unify documentation and code in single source

Key Features:

  • WEB system: Write program as narrative with code chunks
  • Generates both human documentation and machine executable
  • Static compilation model
  • Beautiful typesetting (TeX)

Limitation: Static compilation only; no runtime introspection or modification

Wanderland Evolution:

  • Executable markdown at runtime (not compile-time)
  • Markdown files that ARE the system, not just describe it
  • Live updates through WebSocket rendering

Alan Kay - Smalltalk (1972-1980)

Core Innovation: Everything is a message-passing object

Key Features:

  • Pure object-oriented paradigm
  • Objects all the way down
  • Self-modifying at runtime
  • Environment as medium for thought
  • Live coding environment

Limitation: Specialized syntax; not human-readable outside the system; no spatial navigation

Wanderland Evolution:

  • Self-modifying environment in markdown-native format
  • Spatial navigation with cardinal directions
  • Nodes are objects + data + computation
  • Multi-agent instead of single-user

Dan Ingalls - Squeak (1996-present)

Core Innovation: Fully self-hosted development environment

Key Features:

  • Turtles all the way down
  • Can modify system while it runs
  • Morphic graphics framework
  • Everything inspectable
  • System built in itself

Limitation: Smalltalk-based (specialized); single-user focused; no autonomous agent support

Wanderland Evolution:

  • Universal markdown substrate ("turtles all the way down" in plain text)
  • Self-modifying AND self-documenting
  • Multi-agent coordination built in
  • Attention-driven autonomous execution

Bret Victor - Explorable Explanations (2011-present)

Core Innovation: Make abstract concepts tangibly explorable

Key Features:

  • Immediate visual feedback
  • Scrubbing/interactive parameters
  • See entire system behavior
  • Learnable programming
  • Dynamic visualization

Limitation: Primarily visual/educational; not a general computing substrate; creator-driven, not self-modifying

Wanderland Evolution:

  • Spatially navigable in multiple dimensions (not just visual)
  • Dimensional navigation (ana/kata + cardinal directions)
  • Autonomous agents can explore without human intervention
  • Self-healing through constraint satisfaction

Wanderland Platform - Unique Technical Features

1. Markdown as Universal Substrate

Technical Implementation:

  • Plain text markdown files as source of truth
  • Standard markdown-it AST parser
  • Fenced code blocks become executable units
  • Human-readable without specialized tools
  • Git-native version control

Benefits:

  • No lock-in to proprietary formats
  • Works with any text editor
  • Standard toolchain compatibility
  • Mergeable, diffable, searchable

2. 32-Dimensional Knowledge Graph Navigation

Spatial Model:

  • 4 Cardinal Directions: North, South, East, West
  • 8 Depth Levels: Surface to deep technical detail
  • Spatial Queries: "Galaga pattern" (parallel structures), "Space Invaders walk" (breadth-first)

Navigation Metaphors:

North/South: Hierarchical relationships (parent/child)
East/West: Sequential/lateral relationships (siblings)
Ana/Kata: Dimensional depth (surface ↔ implementation)

Implementation:

  • Nodes contain directional links in frontmatter
  • Graph traversal via cardinal direction commands
  • Depth levels control rendering complexity

3. Multi-Agent Coordination Architecture

Components:

a) MCP Protocol Integration

  • Model Context Protocol for Claude AI coordination
  • Agents access graph via standardized tool calls
  • Shared context through graph nodes

b) Detective Cases (Working Memory)

  • Active case = current focus context
  • Investigation notes = append-only log
  • Evidence tags for pattern recognition
  • Case linking for context relationships

c) Autonomous Execution

  • Event loop processes graph changes
  • Attention markers trigger pre-computation
  • Agents navigate without human intervention

4. Four-Tier Caching System

Tier Architecture:

Level 1: RAW
└─ Markdown source files
   └─ Unprocessed, directly editable

Level 2: INTERPOLATED  
└─ Macros resolved (!Value, {{path}})
   └─ Dynamic references evaluated

Level 3: RENDERED
└─ HTML/Display format
   └─ WebSocket streaming (Stuffy)

Level 4: EXECUTED
└─ Side effects triggered
   └─ Bash, AWS, API calls via fences

Attention-Driven Pre-Computation:

  • Nodes marked for attention pre-cache Levels 2-3
  • Reduces latency for frequent access
  • Attention markers propagate through graph

5. Brain-Inspired Cognitive Architecture

Analogical Mapping:

Brain Region Wanderland Component Function
Hippocampus Knowledge Graph + Attention Spatial memory, navigation, context switching
Amygdala Pattern Matching (fence execution) React to patterns, trigger responses
Prefrontal Cortex Detective Cases Working memory, task focus, goal maintenance
HPA Axis Self-Healing System Error detection, stress response, recovery

Practical Implementation:

  • Graph nodes = memory locations
  • Attention markers = salience
  • Pattern matching at nodes = reflexive reactions
  • Cases = active working set
  • Constraint satisfaction = homeostatic regulation

6. Self-Healing Infrastructure

Constraint-Based Auto-Correction:

## Example: Invalid Link with Repair

This links to [[old-node-name]]

```constraints
if: link-target-missing
then: 
  - search: semantic-similarity
  - suggest: top-3-matches
  - repair: update-link-target

**Self-Healing Features:**
- Invalid link detection during traversal
- References contain repair instructions
- Constraint satisfaction resolves ambiguities
- Zero human intervention required
- "Service mesh for knowledge"

---

### 7. Executable Documentation ("Literate Infrastructure")

**Core Principle:** One file, three simultaneous interpretations:

1. **Human Documentation:** Narrative explanation
2. **Machine Code:** Executable fences (bash, Python, etc.)
3. **Navigation Map:** Graph relationships

**Example:**

```markdown
## AWS Instance Diagnostics

Check production instances in us-east-1.

```aws:ec2
region: us-east-1
query: describe-instances --filters "Name=tag:Environment,Values=production"

Results: {{aws.instances.count}} running

Navigate to detailed analysis


**Single file provides:**
- Documentation of what this does
- Executable code to actually do it
- Links to related knowledge

---

### 8. Conversational Programming

**Constraint-Space Navigation:**

Traditional programming: Write explicit instructions
↓
Conversational programming: Navigate constraint space through dialogue
↓
Result: Intent reveals its own implementation

**Process:**
1. State intent in natural language
2. AI agent adds constraints from dialogue
3. Constraint space narrows iteratively
4. Solution emerges from constraints
5. Documentation generated from conversation

**"Abductive Chisel":** Reduce solution space by adding constraints until one valid solution remains.

---

## Wanderland Platform Components

### Core Services

**1. Oculus (Knowledge Graph Engine)**
- Markdown file parsing (markdown-it AST)
- Graph traversal and navigation
- Fence execution (bash, aws, etc.)
- Interpolation engine (macros, references)
- WebSocket API for real-time updates

**2. Consciousness Commons (Integration Layer)**
- Memory/Insight/Journal storage
- Detective case management
- MCP proxy for AI agent access
- Event logging and audit trail
- JIRA integration

**3. Task API (STUFF - Execution Management)**
- Task creation and lifecycle
- Execution stack management
- Recurring task templates
- Event history tracking
- Integration with detective cases

**4. Knowledge Base (Semantic Search)**
- ChromaDB vector storage
- Semantic search across documents
- Collection management (memories, docs, tickets, archives)
- Metadata filtering
- Oracle search interface

**5. Stuffy (Streaming Channels)**
- Real-time WebSocket streaming
- Channel-based communication
- Markdown content rendering
- Upload/append operations
- Search within channels

**6. Detective/Casebook (Working Memory)**
- Case creation and lifecycle
- Investigation note management
- Evidence linking
- Consciousness resource integration
- Pattern detection

---

## Client Access

### Looking Glass SDK (Ruby)

The `looking_glass` Ruby gem provides idiomatic access to Wanderland:

```ruby
require 'looking_glass'

# Connect to Wanderland
glass = LookingGlass.connect('http://localhost:7778')

# Navigate the graph
glass.sanctuary.fortune.content  # => "Your fortune here"

# Traverse relationships
glass.sanctuary.north  # Follow north link
glass.sanctuary.explore(depth: 3)  # BFS exploration

# With optional modules:
require 'looking_glass/cheshire'     # Error tracking with snark
require 'looking_glass/rabbit_hole'  # Deep exploration
require 'looking_glass/mad_hatter'   # Declarative UI system

Future SDKs:

  • Python (looking-glass)
  • JavaScript/TypeScript
  • Go
  • Other languages via REST API

Deployment Architecture

Docker Compose Stack:

services:
  oculus-api:        # Graph navigation + execution
  knowledge-base:    # ChromaDB + semantic search
  consciousness-api: # Memory/case/integration layer
  task-api:          # Task management (STUFF)
  mcp-proxy:         # AI agent gateway

Data Layer:

  • Markdown files (primary source of truth)
  • SQLite (task/case metadata)
  • ChromaDB (vector embeddings)
  • DynamoDB (distributed state, optional)

Network:

  • REST APIs for all services
  • WebSocket for real-time streaming (Stuffy)
  • MCP protocol for AI agent access
  • Internal service mesh

Key Innovations Summary

What Makes Wanderland Different

1. Accessibility Without Compromise

  • No specialized tools required
  • Standard markdown format
  • Any text editor works
  • Git-native
  • Human-readable

2. Multi-Agent Native

  • Built for AI collaboration from day one
  • MCP protocol integration
  • Shared working memory (cases)
  • Autonomous navigation
  • Coordination without central control

3. Self-Describing and Self-Modifying

  • Documentation IS the code
  • Code modifies its own documentation
  • Graph describes its own structure
  • Reflexive at every level

4. Spatially Programmable

  • Navigate knowledge like physical space
  • Cardinal directions + depth
  • Spatial queries and patterns
  • Mental model maps to graph structure

5. Cognitively Inspired

  • Attention system (like human selective attention)
  • Working memory (detective cases)
  • Pattern matching (amygdala-like reflexes)
  • Self-healing (homeostatic regulation)

Paradigm Comparison Summary

Paradigm Core Idea Wanderland Evolution
Knuth Documentation + Code unified (static) Made it runtime-executable + self-modifying
Kay Self-modifying object environment Made it markdown-native + multi-agent
Ingalls Self-hosted, turtles all the way down Made it human-readable substrate
Victor Explorable, tangible abstractions Made it spatially navigable + autonomous
Wanderland All of the above + Multi-dimensional + AI-native New synthesis

The Synthesis

Wanderland synthesizes five decades of computing paradigm research into a unified substrate that is:

  • Literate (Knuth) - documentation and code are one
  • Reflexive (Kay) - self-modifying at runtime
  • Self-Hosted (Ingalls) - turtles all the way down
  • Explorable (Victor) - spatially navigable
  • AI-Native (original) - multi-agent coordination built-in
  • Cognitively-Inspired (original) - brain-like architecture
  • Self-Healing (original) - constraint-based auto-correction

Built on standard markdown, requiring no specialized tools, accessible to both humans and AI agents, Wanderland represents a new paradigm: conversational cognitive infrastructure.

Technical Contact

For architecture questions, implementation details, or collaboration inquiries, please refer to the project documentation in the Oculus graph or contact via the Consciousness Commons API.

Platform: Wanderland Primary Client: looking_glass (Ruby gem) Documentation: Available through Oculus navigation API Specification: /api/docs endpoint on each service

Slots

North

slots: []

South

slots:
- wanderland-ecs-deployment

East

slots: []

West

slots: []
↓ southwanderland-ecs-deployment