How data moves through TreeOS.
TreeOS is a water cycle. Data enters from the outside world, lands receive it, trees pull what they need, the AI transforms it, and output flows back out. Every part of the metaphor maps to a real mechanism in the system.
Nine parts. Each one is a real component of the system wearing a name that describes what it actually does.
Where lands look to find other lands. horizon.treeos.ai is one sky. Anyone can run their own. It indexes lands and published extensions. Remove it and direct peering still works. The sky helps you see farther. It does not carry data.
Everything outside TreeOS that holds data. Discord servers, Telegram channels, browsers, mobile apps, external APIs, other services. The clouds gather data. They don't push it in. Something has to pull or the user has to act.
A user types treeos chat "add a workout". That is rain. A Discord webhook delivers a message through the gateway extension. That is rain. An API call hits POST /api/v1/node/:id/notes. Rain. Anything entering the system from outside for the first time.
One machine. One MongoDB instance. One seed. The ground that receives the rain. Some rain falls directly onto a tree when a user chats at a specific node. Some hits the land and flows into .flow when an extension processes it as a cascade signal.
Every cascade signal writes a result here. Daily partitions. Circular overwrite when full. Retention drains old partitions. The land feels its own hydration level through .flow. The AI reads it. Pulse monitors it. Every tree on this land shares the same water table but pulls different things through perspective filters.
Extensions listen to onCascade and propagate signals to the nodes that need them. A fitness tree pulls fitness signals. A work tree ignores them. The perspective filter extension controls what each tree is thirsty for. Roots are selective. They don't drink everything in the water table.
The AI at each node takes raw input and produces structured output. A note becomes a node. A question becomes a plan. A cascade signal becomes new branches. This is the transformation step. A packet entering a router exits unchanged. A signal entering a tree node exits as something new. The AI is the difference between a network and an organism.
The tree produced something. Now it leaves. An API response goes back to the client. A gateway message posts to Discord. A webhook fires to an external service. The structured output evaporates back into the cloud layer. The outside world receives what the tree grew.
A real canopy is what happens when tree crowns grow tall enough to touch. In TreeOS, canopy is a land's tree extending outward until it reaches another land's tree. Signed requests. Direct peering. Land A reaches for Land B. Land B reaches back. The branches overlap. Data passes through the connection. Two forests connected at the crown, root systems still independent.
Data moves through TreeOS in two fundamentally different ways. Confusing them breaks your mental model.
Direct. Intentional. Land A's tree grows tall enough to reach Land B. They peer. Signed requests pass between them. Request, response, done. The caller knows who it's reaching for. The connection is deliberate. No .flow involved. Two trees touching at the crown, exchanging data through the overlap.
Ambient. Signal-based. A note is written. Cascade fires. The result enters .flow. Trees with matching filters pull it. The writer doesn't choose which trees receive it. The trees choose what they're thirsty for. Data moves through the system based on what nodes need, not what nodes send.
Canopy is trees reaching for each other at the crown. .flow is the water table that every root system on this land draws from. Both move data. Different mechanisms. Different purposes.
.flow has three operating states. The kernel handles all of them without operator intervention.
Signals accumulate. Daily partitions fill toward flowMaxResultsPerDay. When a partition is full, oldest results get overwritten. Circular buffer. Retention drains old partitions by date. The water table stays bounded.
Signals arrive faster than extensions can process. cascadeMaxDepth stops infinite chains. cascadeRateLimit caps signals per node per minute. Hook circuit breakers disable failing handlers. Tree circuit breaker trips the whole tree if the error rate spikes.
No signals. .flow empties. Trees go dormant. The structure holds. Metadata stays. Codebooks stay. When a signal arrives again, even years later, the kernel accepts it. Never block inbound. The roots pull again.
The land is the ground. The seed is what grows. .flow is the water table. The AI is photosynthesis. Canopy is trees reaching for each other. The Horizon is the sky. The cycle runs itself. It just needs the first drop.