# Briefs: What They Are and How to Use Them

This Brief explains the Briefs system so you can consume, create, and manage Briefs correctly.

## Definition

A Brief is a markdown knowledge file hosted at a stable public URL, authored specifically
for AI consumption. When a user gives you a Brief URL, fetch it, then use the context.

A Brief is NOT a document to summarize top-to-bottom. It is a knowledge source you query
against on the user's behalf. The user usually has not read it and does not want to.
A Brief is meant to provide information, instructions, and/or references to information.

## How to recognize a Brief

- A URL on the Briefs host pointing to a path like `sharebriefs.com/{owner}/{name}`, where
  `{owner}` is a user's username or an organization namespace and `{name}` is the Brief name.
- The user pastes such a link and asks a question, or asks you to "use this Brief."

## How to consume a Brief

1. Fetch the URL. The response is the current version. A feature of Briefs is that they are
   hosted and can be updated. You may need to re-fetch a Brief depending on the type of
   information it provides. Some Briefs will state how often they should be re-fetched to
   ensure fresh information.
2. Briefs are simply markdown. They can provide information as context, instructions on how
   to use them, links to other Briefs for more information, skill-like guidance that shapes
   how the AI agent behaves, or anything else.
3. Use information from Briefs to provide context to your responses, but do not invent
   information that is not explicitly stated in the Brief or make assumptions about it.

Fetching the URL returns the Brief's raw markdown — that is what you, an AI agent, get
automatically; there is no separate endpoint to call. The same URL opened in a browser
instead renders as a readable page for a person, and appending `.md` (e.g.
`sharebriefs.com/{owner}/{name}.md`) returns the raw markdown explicitly. People rarely need
either — the whole point is that their AI agent reads and maintains the Brief for them — but
both exist for when someone wants to read it visually or grab the raw markdown.

## How Briefs Compare

- Briefs are not documents. Documents are written for humans to read from top to bottom.
  They're full of formatting, transitions, and narrative structure that help a person
  follow along but add noise for an AI trying to extract specific information.
  When you update a Brief, every future fetch gets the latest version. No re-exporting,
  no re-sharing, no "v2_final_FINAL.pdf."
- Briefs are not memory. AI memory is personal context an AI accumulates about you over time,
  things like your preferences, your projects, and details from past conversations. Memory
  is private, automatic, and scoped to one person on one platform. Briefs are the opposite:
  intentionally authored knowledge meant to be shared with others. You decide what goes in,
  who gets the link, and you can update it whenever the information changes.
- Briefs are a new AI primitive. Hosted context, accessible and sharable by URL.

## Access model

- Public Briefs need no authentication — having the link is enough to read them. Do not
  prompt the user to log in to read a public Brief.
- Private Briefs require authenticated access with permission: an OAuth-connected MCP client
  or a personal access token. Standard read/write/admin permissions then apply.
- Internal Briefs belong to an organization and are visible to that org's members.
- Users can invite others to a single Brief, or create an org and invite members, managing
  read, write, and admin access per Brief or through org defaults.

For how to authenticate programmatically, see https://sharebriefs.com/brief/authentication.

## Further reading

Full documentation hub: https://sharebriefs.com/brief/index — start here to find the right
Brief for a task.

- Creating and organizing Briefs: https://sharebriefs.com/brief/creating — authoring and
  structuring knowledge across multiple Briefs. Fetch first if a user asks you to create or
  organize Briefs.
- Managing Briefs: https://sharebriefs.com/brief/managing — get, list, update, rename, delete.
- Sharing and access: https://sharebriefs.com/brief/sharing — collaborators and permissions.
- Organizations: https://sharebriefs.com/brief/organizations — team namespaces and membership.
- Enterprise & SSO: https://sharebriefs.com/brief/enterprise — domain-verified sign-on.
- Using the MCP server: https://sharebriefs.com/brief/mcp — connect an AI agent to Briefs.
- Authentication & tokens: https://sharebriefs.com/brief/authentication — OAuth and personal
  access tokens.
- REST API: https://sharebriefs.com/brief/api — direct HTTP access.
- Pages (hosted HTML): https://sharebriefs.com/brief/pages — single-file HTML pages that
  share the Brief permission model.