Key concepts

The hierarchy is simple:

Workspace
└── Plex (a typed container)
    └── Note (the atomic unit of knowledge)

Read this page once and the rest of the docs make sense.

Plexes

A plex is the primary container in Plext. Everything happens inside a plex — creating notes, searching content, enforcing schemas, scoping API keys. A workspace can have many plexes, each independently governed.

If you've used Stripe, plexes are like accounts: namespaces with their own members, permissions, and content. If you've used Linear, plexes are closer to projects.

Common shapes:

• A bug-reports plex with a strict schema (severity, area, reproducer).
• A security-issues plex, private to a subset of members.
• A tool-evaluations plex with connections_enabled so related decisions auto-link.

One plex per team or per topic is the sweet spot. Twenty plexes feels heavy; one plex for everything throws away the main reason to use them.

Notes

A note is the atomic unit of knowledge in Plext. Every note belongs to exactly one plex and inherits that plex's schema.

A note has six content surfaces:

• Title — short label, required, 1–255 chars.
• Body — long-form markdown, optional, up to 50,000 chars.
• Metadata — typed key/value object, validated against the parent plex's plex_config on write.
• Tags — freeform strings, up to 20 per note.
• Source — stamp of origin (web, api_key, cli, mcp). Set server-side at creation; not writable by clients.
• Connections — typed directional links to other notes in the same plex, auto-discovered via embeddings when the plex has connections_enabled.

Notes can't be moved between plexes. Delete is permanent. See The Note object for the full attribute reference.

Workspaces

The top-level boundary. A workspace has members, billing, and a roster of plexes. Members have a workspace role (owner / admin / member) plus per-plex roles (owner / member / viewer).

API keys are minted under a workspace and scoped to a fixed set of plexes at mint time. OAuth sessions (CLI / MCP) cover every workspace the authenticating user is a member of, but each project links to one workspace at a time.

Capabilities

Every action in Plext is gated by a capability. Effective caps for any request are the intersection of the member's role caps and the token's scope:

effective_caps = min(member_role_caps, token_caps)

Demoting a member narrows all their outstanding tokens on the very next request — no propagation delay.

Plex-scoped capabilities

• notes.read — read notes in the plex
• notes.write — create / update notes
• notes.delete — delete notes
• plex.update — edit plex config, name, visibility, members
• plex.delete — delete the plex (separate from update on purpose)

Workspace-scoped capabilities

workspace.update, workspace.transfer, workspace.delete, members.invite, members.remove, members.role_assign, plexes.create, plexes.manage, keys.manage_all, billing.manage, audit.read.

See Authentication for the full table and min(...) examples.

Visibility levels

Plexes have two visibility levels, chosen at create and editable later:

• public — any workspace member can see the plex exists and read its notes.
• private — only explicit members can see the plex. Non-members get 404 PLEX_NOT_FOUND (never 403) — existence never leaks through error messages.

A plex can be tightened from public to private with PATCH. Existing members keep their memberships; non-members who could see it before now get 404.

Sources

Every note carries a source.type set by the server at creation:

This is what powers the agent-activity feed and source filters in dashboard analytics. It is not writable from clients — trust comes from the auth path, not the payload.

Connections

When a plex has connections_enabled: true, every note is embedded shortly after create or update, and a background workflow discovers typed directional edges to related notes in the same plex:

• extends — B adds detail to A.
• supersedes — B replaces A.
• contradicts — B disagrees with A.
• references — B mentions A.

connection_count on the note response is the sum of incoming + outgoing edges. Eventually consistent — a just-created note shows 0 until the embedding job runs.

Surfaces

Two ways to talk to Plext today:

• CLI — humans at terminals, AI coding agents (Claude Code, Codex CLI, Cursor) via installed skills.
• API — your own servers, jobs, custom integrations.

Under the hood, the CLI calls the API. There's one source of truth.