River
Ctrl K
Open River

Foundations

How River Works

River is a workspace where your work, your context, and your AI live together. Most of what makes that feel different from any other app comes down to six layers stacked on top of each other.

Each layer is a real product surface you can see and use. Each one solves a problem that the modern stack of "files + chat + AI" leaves broken.

The mental model in one line#

Senses take in. The home stores. The surface shows. The nervous system records. The intelligence acts. The boundary controls.

The six layers#

1. The Home — Entity System#

Everything in River lives somewhere specific. A doc, a task, an email, an image, a contact, an agent — each one is an entity with a permanent home in the entity tree, a path you can find again, and a history you can trust.

The Entity System is River's filesystem. Just like macOS gave every file a path inside Finder, River gives every piece of work a path inside your Dataspace. But it's built for the way modern work actually behaves: rich types, structured metadata, real-time sync, and full search.

When you close a window, nothing is lost. When you open a new device, your work is already there. When an agent needs context, it knows where to look.

→ Entities · Groups · Search

2. The Surface — Spaces, Windows, Apps#

The Surface is what you see. Spaces are rooms you work in — persistent and returnable. Windows are what's open right now — your current working set. Apps are purpose-built environments for specific kinds of work: Mail, Tasks, Docs, Sheets, Image Studio, and more.

Spaces and Windows are ephemeral. The entities inside them are permanent. Closing a window or rearranging a Space never destroys your work — it only changes what you're looking at.

→ Spaces · Windows · Apps

3. The Senses — How the World Gets In#

A workspace that only knows what you typed into it is blind. River's Senses are the channels through which the outside world becomes part of your world model.

  • Integrations — Gmail, Calendar, Drive, Slack, Stripe, GitHub, Plaid, and 100+ more. Connected services flow in continuously as entities you can read, search, and act on.
  • Browser Extension — clip any web page, screenshot, or selection from anywhere on the internet straight into River.
  • Desktop & Computer Use — when you run the desktop app, River can see your screen, control your apps, and observe what you're working on across native programs.
  • Direct ingestion — drop in a PDF, a video, a transcript, a CSV. River extracts the structure and indexes the content.

Once something flows in through the Senses, it becomes an entity. Once it's an entity, every other layer can act on it.

→ Senses & Connections · Integrations

4. The Nervous System — Event Stream#

Every action — yours or River's — gets recorded in real time on the Event Stream. An email arrives. A task completes. An agent finishes a job. A document is edited. A cursor lingers on a section.

This is not a log you check when something breaks. It's the living memory of your workspace, and it's what lets agents wake up at the right moment without being told to. They subscribe to events they care about and act when those events happen.

→ Event Stream · Activity · Notifications

5. The Intelligence — Agents, Skills, Workflows, Signal Intelligence#

The AI in River is not a chat box bolted onto a notes app. It's a layered intelligence stack working continuously on your behalf.

  • SpaceChat — reactive AI you can talk to. The fastest way to do anything in River.
  • Agents — persistent AI specialists with names, personas, tool allowlists, and triggers. Your Deal Researcher. Your Inbox Triager. Your Morning Briefer.
  • Skills — focused, single-shot capabilities the AI invokes during a larger task ("classify this", "extract that", "draft a reply in my voice").
  • Workflows — deterministic visual graphs for processes that must run the same way every time, with branches, approvals, and audit trails.
  • Schedules & Jobs — recurring runs and the execution record of every autonomous action.
  • Signal Intelligence — a background scoring system that decides what deserves your attention and surfaces it before you ask.

→ River AI · Agents · Workflows · Skills

6. The Boundary — Dataspaces#

Everything in River lives inside a Dataspace — your personal one, your team's, or one shared by another organization that's invited you in. Dataspaces define ownership, privacy, and collaboration. Everyone in a Dataspace shares the same world model and the same agents; nothing crosses the boundary unless you explicitly share it.

→ Dataspaces · Sharing · Permissions

How a single thought becomes work#

Stack the layers together and the system comes alive. One example, top to bottom:

  1. Senses — A new email arrives in your connected Gmail.
  2. Home — It's ingested as an entity in your Mail inbox, with metadata, full text, and a permanent path.
  3. Nervous System — An email.received event fires on your Dataspace's stream.
  4. Intelligence — Your Inbox Triage Agent is subscribed to that event. It wakes up, reads the email, classifies it, and drafts a reply. A Job records the run.
  5. Home — The draft is written back as another entity, linked to the original.
  6. Surface — A notification surfaces in your inbox. You open the draft in a Window.
  7. Boundary — Because this Dataspace is shared with your assistant, they can see the same draft and edit it live alongside you.

No part of that loop required you to be online, to have a tab open, or to remember to ask. The system ran by itself.

Why the layers matter#

Most software stops at the Surface. You get an app, you open it, you do work, you close it, the work goes somewhere — usually a folder, a thread, or a chat history.

River pushes through to all six layers because the whole loop is what makes a workspace feel intelligent. Take away any one of them and the magic collapses:

  • Without Home, the AI has nothing to reason over.
  • Without Senses, the AI is blind to the rest of your work.
  • Without the Nervous System, agents can't wake up on their own.
  • Without Intelligence, you're back to doing all the work manually.
  • Without the Boundary, you can't safely share any of it.
  • Without the Surface, you can't see or control any of it.

When all six are present, you stop maintaining context — and start producing it.

Where to go next#