Groups

Groups are how you organize. They are nested containers that can hold any kind of entity — docs, tasks, emails, sub-groups, agents, anything. They look like folders, but they know more about what's inside.

If Spaces are the rooms you work in, Groups are the shelves and drawers you organize work on.

What makes Groups different from folders#

In a traditional filesystem, a folder is dumb. It holds files, and that's it. In River, a Group:

• Holds anything — entities of any type can live in the same Group together
• Has metadata — descriptions, tags, color, an icon, custom fields
• Knows what's inside — full-text search, structure, AI summaries
• Can be referenced from many places — the same entity can be reachable from multiple Groups without duplication
• Is a first-class entity itself — you can open a Group in a Window, share it, give an Agent access just to that Group

How Groups nest#

Groups can contain other Groups, with no depth limit. This is how you build out the structure of your work:

Acme Co/
  ├── Customers/
  │     ├── Hyperline/
  │     ├── Loop/
  │     └── Cellar Door/
  ├── Engineering/
  │     ├── PRDs/
  │     └── Postmortems/
  └── Operations/
        ├── Hiring/
        └── Finance/

The hierarchy is yours to design, and you can rearrange it any time. Moving a Group moves everything inside it. Renaming a Group renames its path everywhere it's referenced.

Groups vs. tags#

Use Groups when something has a home — when it primarily belongs in one place. Use tags (and edges) when something has relationships to many things — when it should be findable from many angles.

Most entities have one Group home and many edges. The Group is "where it lives." The edges are "what it's connected to."

Smart organization#

When the AI creates entities on your behalf — extracting a vehicle from a chat, importing a Stripe customer, generating an investor update — it places them in sensible Group homes automatically. You can always move them later, but the system tries to put things where you'd expect.

Tips#

• Don't over-organize early. A flat structure with great search is fine for a while.
• When a Group gets too big, split it into sub-groups by theme.
• Share an entire Group with a teammate to give them the whole context for a project in one click.