HoloSphere

The distributed substrate that every Holons UI reads from and writes to

HoloSphere

HoloSphere is the storage substrate of the Holons ecosystem. It is a JavaScript library that combines H3 geospatial indexing for hierarchical addressing with GunDB for distributed, peer-to-peer storage. Every interface in Harvest—the web dashboard, the Telegram bot, the CLI, the AI agent, the MCP server—writes to and reads from HoloSphere. That shared substrate is what makes the system one source of truth despite having many user-facing surfaces.

This page is the conceptual introduction. For the full API reference, see HoloSphere API Reference below.

The shape of the substrate

HoloSphere is organized around three concepts:

• Holons — units identified by an H3 cell (or, in non-geographic use, by any string ID). A holon is a folder; everything else lives inside it.

• Lenses — named categories of data within a holon (tasks, expenses, rea_events, dna_sequence, proposals, …). Each lens is independent: writing to one doesn't touch the others.

• Items — individual records inside a lens, each keyed by its own id.

holon (H3 cell or string ID)
├── lens "tasks"
│   ├── item "task-abc123"
│   └── item "task-def456"
├── lens "expenses"
│   └── item "expense-789"
├── lens "rea_events"
│   └── …
└── lens "dna_sequence"
    └── …

Every domain in @holons/core is the authority over one or more lenses—Tasks owns tasks, Council owns proposals, REA Accounting owns rea_events, and so on. HoloSphere itself is content-agnostic: it doesn't know what's in a lens, only how to store it, propagate it, and validate it against a schema if one is set.

Why H3

H3 is Uber's hierarchical hexagonal geospatial indexing system. It maps any (lat, lng) to a hex cell at any of 16 resolutions, and provides constant-time parent/child/neighbor lookups.

HoloSphere uses H3 because:

• Hierarchy is free. A neighborhood holon's parent is a city holon; its children are block-level holons. No bespoke region trees.

• Aggregation is natural. "Roll up all environmental readings for this region" maps directly to cellToChildren() followed by getAll() on each child.

• Neighbors are addressable. Adjacent holons can subscribe to each other's lenses without configuring relationships individually.

• Stable IDs. Two clients computing the H3 index for the same (lat, lng, resolution) always get the same cell, so they always end up writing to the same holon.

A holon doesn't have to be geographic. A community, a project, a dataset—anything can be a holon if you give it an ID. H3 is the default addressing scheme, not a requirement.

Why GunDB

GunDB is a decentralized, real-time, peer-to-peer database. HoloSphere uses it because:

• No central server. Holons can run on relays, on phones, on Raspberry Pis—the data finds its way.

• Real-time by default. Every read can subscribe; updates propagate to all peers.

• Conflict-free for the common case. GunDB's CRDT model handles concurrent writes without bespoke conflict resolution.

• Offline-tolerant. A peer that goes offline picks up missed writes when it reconnects.

The trade-off is that GunDB is eventually consistent and not transactional. HoloSphere works with this rather than around it: domains are designed so that "out-of-order writes" produce sensible end states.

Multi-scale operations

The combination of H3 + GunDB lets HoloSphere support operations across scales naturally:

• Localized — query one holon, get its own data.

• Delocalized / aggregated — query a parent, get a roll-up across children.

• Hybrid — subscribe to a holon and propagate computed summaries upward (e.g., "regenerative practices reported per bioregion").

This is what makes federation practical: a network of holons can share data along the H3 hierarchy or along explicit federation edges, with one consistent API.

Lenses, schemas, and validation

A lens can be left untyped or constrained to a JSON Schema:

await sphere.setSchema('temperature', {
  type: 'object',
  properties: {
    id: { type: 'string' },
    temperature: { type: 'number' },
    timestamp: { type: 'number' },
  },
  required: ['id', 'temperature', 'timestamp'],
});

In strict mode, writes that violate the schema are rejected at the substrate layer. This is what lets domains evolve independently without stepping on each other—the tasks schema doesn't know or care what shape expenses is.

Lenses without a schema accept arbitrary JSON. This is the default, and is appropriate for most domain data, which is typed at the @holons/core layer instead.

Identity-aware writes

In the Holons monorepo, raw HoloSphere puts and gets are wrapped by the identity-aware layer in @holons/core/holosphere:

• writeWithIdentity(holonId, lens, item, actor) — attaches the writing actor to the record, used for attribution in scoring and federation.

• canWriteToHolon(holonId, actor) — checks whether an actor has standing to write to a holon (e.g., is a member, is in the right zone).

The MCP server and AI UI both resolve their actor through this layer, so every write is attributable regardless of which interface emitted it.

Federation

Federation is the system that lets two HoloSphere spaces share data while keeping a single source of truth. A space adds another to its federation list; the other space adds the first to its notify list. Reads on federated lenses resolve transparently across the relationship.

Federation supports soul references (lightweight pointers) by default, so propagating data between spaces doesn't duplicate storage—the original lives in one space, and the federated copy resolves to it on read.

For the full federation model, see Federation.

Installation

npm install holosphere

import HoloSphere from 'holosphere';

const sphere = new HoloSphere('my-app');
const holon = await sphere.getHolon(40.7128, -74.0060, 7); // NYC at resolution 7

await sphere.put(holon, 'observations', {
  id: 'obs-001',
  temperature: 22.5,
  timestamp: Date.now(),
});

In a Holons monorepo deployment, you don't usually instantiate HoloSphere yourself—@holons/core/holosphere provides a factory that every UI shares, configured by HOLONS_PEER and HOLONS_APP env vars (see MCP Server).

See also

• Federation — cross-space data sharing

• Harvest — the monorepo whose interfaces all share one HoloSphere namespace

• MCP Server — the MCP layer that exposes the substrate to external agents

---

API Reference

The remainder of this page is the canonical API reference for the standalone HoloSphere library.

Holonic Architecture

HoloSphere implements holonic architecture in two ways:

1. Spatial Hierarchy

// Get holons at different scales for a location
const holon = await sphere.getHolon(lat, lng, 7);  // City level
const parent = h3.cellToParent(holon, 6);          // Region level
const children = h3.cellToChildren(holon, 8);       // Neighborhood level

// Get entire hierarchy
const scales = sphere.getHolonScalespace(holon);    // All containing holons

2. Data Organization

// Store data in different aspects (lenses) of a holon
await sphere.put(holon, 'environment', {
    id: 'air-001',
    temperature: 22.5,
    humidity: 65
});

await sphere.put(holon, 'social', {
    id: 'event-001',
    type: 'gathering',
    participants: 50
});

Use Cases

Localized structures

async function monitorLocalAir(lat, lng) {
    const neighborhood = await sphere.getHolon(lat, lng, 9);

    await sphere.put(neighborhood, 'air-quality', {
        id: `reading-${Date.now()}`,
        pm25: 12.5,
        timestamp: Date.now()
    });

    const readings = await sphere.getAll(neighborhood, 'air-quality');
}

Delocalized structures

async function coordinateResources(region) {
    const localities = h3.cellToChildren(region, h3.getResolution(region) + 1);

    const resources = await Promise.all(
        localities.map(async locality => {
            return sphere.getAll(locality, 'resources');
        })
    );

    await sphere.compute(region, 'resources', 'summarize');
}

Hybrid structures

async function coordinateEmergency(incident) {
    const epicenter = await sphere.getHolon(incident.lat, incident.lng, 8);
    const region = h3.cellToParent(epicenter, 6);

    await sphere.put(epicenter, 'emergencies', {
        id: incident.id,
        type: incident.type,
        severity: incident.severity
    });

    const nearbyResources = await sphere.getAll(region, 'resources');

    sphere.subscribe(epicenter, 'emergencies', (data) => {
        updateResponsePlan(data);
    });
}

Constructor

new HoloSphere(
    appName,    // String: Namespace for your application
    strict,     // Boolean: Enable strict schema validation (default: false)
    openaikey   // String: Optional OpenAI API key for AI features
)

Core methods

• async getHolon(lat, lng, resolution) — Get H3 index for coordinates

• async put(holon, lens, data) — Store data

• async get(holon, lens, key) — Retrieve specific data

• async getAll(holon, lens) — Retrieve all data

• async delete(holon, lens, key) — Delete specific data

• async deleteAll(holon, lens) — Delete all data

• async setSchema(lens, schema) — Set JSON schema for validation

• async getSchema(lens) — Get current schema

• subscribe(holon, lens, callback) — Listen for changes

Data validation

const sphere = new HoloSphere('validated-data', true);

const measurementSchema = {
    type: 'object',
    properties: {
        id: { type: 'string' },
        value: { type: 'number' },
        unit: { type: 'string' },
        accuracy: { type: 'number' },
        timestamp: { type: 'number' }
    },
    required: ['id', 'value', 'unit'],
    additionalProperties: false
};

await sphere.setSchema('measurements', measurementSchema);

In strict mode, writes that don't match the schema are rejected.

Federation API

federate(spaceId1, spaceId2, password1, password2, bidirectional)

Creates a federation relationship between two spaces.

await holosphere.federate('space1', 'space2', 'pass1', 'pass2');

This sets up:

• space1.federation includes space2

• space2.notify includes space1

propagate(holon, lens, data, options)

Propagates data to federated spaces.

await holosphere.propagate('space1', 'items', data, {
  useReferences: true,         // default: uses soul references
  targetSpaces: ['space2']     // optional: specific targets
});

Or use auto-propagation on every write:

await holosphere.put('space1', 'items', data, null, {
  autoPropagate: true,
});

Soul references

When using the default useReferences: true:

1. Only a lightweight reference is stored in the federated space.

2. The reference contains the original item's ID and soul path.

3. On access, the reference is resolved to the original data.

4. Changes to the original are immediately visible through references.

Single source of truth, no storage duplication.

Federation structure

{
    id: string,
    name: string,
    federation: string[],  // Source spaces this holon federates with
    notify: string[],      // Target spaces to notify of changes
    timestamp: number
}

Message federation

// Track a federated message across chats
await holosphere.federateMessage('chat1', 'msg1', 'chat2', 'msg2', 'quest');

// Look up all federated copies
const messages = await holosphere.getFederatedMessages('chat1', 'msg1');

// Update across all federated chats
await holosphere.updateFederatedMessages('chat1', 'msg1', async (chatId, messageId) => {
    await updateMessageInChat(chatId, messageId);
});

Dependencies

• h3-js — Uber's H3 geospatial indexing

• gun — Decentralized database

• ajv — JSON Schema validation

• openai — AI capabilities (optional)

License

GPL-3.0-or-later