Foundations
Entities
An entity is the thing itself. A document, a PDF, a task, an email, a contact, a sheet, a video, a chat thread, an Agent — they are all entities. Every piece of work you create or import lives as an entity in your Dataspace.
If River is the operating system for your work, entities are the files. But they are richer, smarter, and more deeply connected than files have ever been.
What every entity has#
Every entity in River, regardless of type, has:
- A type — Doc, Task, Email, Image, Agent, Workflow, Contact, etc.
- A skeleton — typed metadata fields specific to that type (a Task has a
dueDate; an Email has asubjectandfrom) - Content — the actual body, document tree, or payload, often a Y.js CRDT for real-time collaboration
- A home — the Group it lives in (its path)
- Edges — relationships to other entities ("this Task belongs to that Project," "this Doc references that Contact")
- A history — created when, by whom, every edit
- Permissions — who can see and act on it, inherited from its Dataspace
Together these make every entity findable, addressable, and reasonable-over by the AI.
Why everything is an entity#
Most apps have their own private formats and filesystems. Your todo app stores tasks in a way Google Docs can't see. Your inbox stores emails in a way your CRM doesn't understand. AI tools are walled off from all of it.
River collapses these silos. Because everything — including Apps, Agents, and Workflows themselves — is an entity:
- The AI can read across all of it without integration shims.
- Search finds anything by content, type, or metadata.
- Sharing a single entity (or a group of them) is a single action.
- Edges link Tasks to Docs to Emails to Contacts naturally.
When the AI extracts a Vehicle from a conversation, drafts a reply email, or generates a dashboard — every output is also an entity. Nothing exists in a side channel.
Entity types you'll encounter#
A few of the built-in types:
| Type | What it holds |
|---|---|
Doc, Page, Note, Markdown |
Long-form text and structured documents |
Task |
A to-do with status, due date, owner |
Email, EmailThread |
Inbox messages and conversations |
Sheet |
Tabular data with formulas |
File, PDF, Image, Video |
Uploads and binary content |
Contact, Person, Company |
People and organizations |
Agent, Workflow, Skill |
The intelligence layer |
Job, Schedule |
Execution records and recurring runs |
Group, Space |
Containers and rooms |
There are dozens more, and Apps can register new types of their own.
Custom entity types#
You can register your own entity types — Vehicle, Property, Patient, Lead, Subscription, anything specific to your work. The AI can then extract them from unstructured content and add them to your tree. See Entity Extraction and Custom Apps.
Tips#
- Anything you can search for, share, or open in a Window is an entity.
- If you can't find something, it's almost always because it doesn't have a great Group home — try moving it.
- The AI can act on multiple entities at once. Open a few in Windows and ask SpaceChat to work across them.