🔗 Clusters

Hierarchical groupings of signals based on time, space, or theme.

What is a Cluster?

A cluster is a structured grouping of related signals within a realm. Think of it as a container that holds signals together based on shared characteristics:

Temporal proximity — Signals from the same time period (a day, week, month, or custom span)
Spatial proximity — Signals from the same location or geographic area
Thematic similarity — Signals with related content, topics, or patterns

Clusters are not folders. They're not tags. They're structured containers with their own metadata, hierarchies, and synthesis capabilities.

Why Clusters Matter

Individual signals capture moments. Clusters reveal patterns.

When you group signals together, you enable synthesis at a different scale. A single photo might show a beach. A cluster of signals from a week at the coast reveals trajectory, rhythm, and emergent narrative.

Clusters are where pattern recognition becomes possible.

Common Cluster Patterns

⏰ Temporal

Signals grouped by time period

• Daily journals
• Weekly summaries
• Monthly reviews
• Year in review

📍 Spatial

Signals from the same location

• Signals from Oregon coast
• Signals from state parks
• Signals from a specific beach
• Trip documentation

💭 Thematic

Signals with related content

• Research on a topic
• Creative project documentation
• Observations about X
• Pattern tracking

🏗️ Project-Based

Signals related to a specific project

• Building Autonomy
• YouTube series creation
• Field research
• Writing a document

Cluster Structure

Core Fields

cluster_idUnique identifier (ULID)

realm_idWhich realm this cluster belongs to

cluster_nameDisplay name for the cluster

cluster_descriptionWhat this cluster is about

cluster_typeTEMPORAL, SPATIAL, THEMATIC, or custom

parent_cluster_idOptional parent for hierarchies

Metadata & Organization

cluster_metadataStructured data about the cluster (JSON)

cluster_payloadFull cluster data (JSON)

cluster_tagsArray of tags

cluster_annotationsUser notes and annotations (JSON)

Cluster Hierarchies

Clusters can have parent-child relationships, allowing you to build nested structures:

2024 (parent cluster)
  ├─ Q1 2024 (child of 2024)
  │   ├─ January 2024 (child of Q1)
  │   ├─ February 2024
  │   └─ March 2024
  ├─ Q2 2024
  └─ Q3 2024

Oregon Coast (parent cluster)
  ├─ Shore Acres State Park
  ├─ Cape Arago
  └─ Sunset Bay

This allows synthesis at multiple levels of granularity. You can reflect on a single day, a month, a quarter, or an entire year.

Signal Positioning in Clusters

When you add a signal to a cluster, you can specify its position. This preserves ordering when signals need to appear in a specific sequence.

The clusters_signals join table tracks:

cluster_id — Which cluster
signal_id — Which signal
position — Order within the cluster (optional)

This means signals can appear in multiple clusters, and the order can differ in each cluster.

Realm Isolation Rules

Critical: Signals and Clusters Must Share a Realm

You cannot add a signal from one realm to a cluster in another realm. This is enforced at the query layer.

Why: Epistemic integrity. Cross-realm data mixing would break sovereignty guarantees.

Synthesis on Clusters

Clusters enable synthesis at scale. Instead of reflecting on a single signal, you can generate:

Mirror — Summary of all signals in the cluster
Myth — Archetypal patterns across the cluster's timespan or theme
Narrative — Coherent story woven from multiple signals

This is where patterns become visible. A single signal shows a moment. A cluster shows trajectory.

Learn more about synthesis →

Creating Your First Cluster

1. Navigate to Clusters in the admin panel
2. Click Create Cluster
3. Select your realm
4. Choose a cluster type (TEMPORAL, SPATIAL, THEMATIC)
5. Add a name and description
6. Optionally set a parent cluster for hierarchies
7. Add signals to the cluster
8. Optionally specify position for signal ordering
9. Save

Common Use Cases

Daily Documentation

Create a cluster for each day. Add all signals from that day. Generate narrative synthesis to see what the day looked like in retrospect.

Research Projects

Group all signals related to a research topic. Extract patterns across interviews, observations, and notes.

Location-Based Collections

Cluster signals by place. See how your relationship to a location evolves over time.

Creative Projects

Document a creative process from conception to completion. All signals in one cluster, synthesis reveals the arc.

Key Principles

Clusters reveal what signals alone cannot

Individual signals are moments. Clusters show patterns, trajectories, and emergent narratives.

Hierarchies enable multi-scale synthesis

Nest clusters to generate understanding at different levels of granularity.

Signals can belong to multiple clusters

The same signal can appear in temporal, spatial, and thematic clusters simultaneously.

Clusters enforce realm boundaries

All signals in a cluster must be from the same realm. Sovereignty is maintained.