Skip to main content

Core Concepts

A quick tour of the nouns you'll meet everywhere in Sophic — in the dashboard, the API, and the MCP tools.

Workspace​

A workspace is a team's container: its members, billing, integrations, and knowledge all live inside one workspace. Most things in Sophic are workspace-scoped — an API key, a Slack connection, or a document belongs to exactly one workspace.

A user can belong to several workspaces. The web app tracks your active workspace in the sophic-workspace cookie; the API resolves the workspace from the credential instead (a workspace API key is bound to one; a PAT names the workspace via the x-sophic-workspace header).

Members & roles​

Each membership has a role, from most to least privileged:

RoleCan
ownerEverything, including billing and deleting the workspace
adminManage members, integrations, and settings
editorCreate and edit documents, review proposals
viewerRead documents
agent-onlyA non-human seat for automated/agent access

Roles also gate role-restricted folders (see below).

Captures​

A capture is one piece of raw, unprocessed input — a Slack thread, a GitHub PR discussion, a meeting transcript, an imported file, a note from an agent. Captures land in an immutable buffer: once written they aren't edited or deleted, only marked as processed. Every capture records where it came from (source_kind: slack, github, mcp, waterfall, web_manual, import) and is de-duplicated by content hash.

Captures are the raw material. They are not the documents your team reads — that's the next step.

The librarian sweep​

A background librarian sweep periodically scans unprocessed captures and uses an LLM to consolidate them into clean, structured documents — deduping near-identical notes, merging related material, tagging topics, filing into folders, and cross-linking. Each sweep produces a proposal: a batch of suggested operations (create a document, merge two, link them) that a human can review.

Depending on the workspace's ingestion mode, proposals are either auto-applied when confidence is high (smart) or always held for review (always review). Reviewing happens in the dashboard's inbox.

Documents​

A document is the synthesized, readable output — the thing search returns and the dashboard renders. Documents come in two kinds:

  • Source documents — distilled from captures (a runbook from an incident thread, a decision record from a PR).
  • Topic pages — higher-level syntheses that summarize everything Sophic knows about a topic.

Documents carry a title, content, a source, a status, an optional folder_id, an author, timestamps, and a vector embedding used for semantic search. Documents can link to each other (related, supersedes, duplicate_of).

Folders & topics​

Folders organize documents into a nestable hierarchy. A folder has a visibility:

  • workspace — visible to everyone in the workspace (and to the public KB, if enabled).
  • role — restricted to members at or above a required_role.

Topics are an automatic taxonomy: the sweep clusters related documents under a topic and maintains a topic page for it. A single document can belong to multiple topics without being duplicated.

The v1 REST API and the MCP read tools only ever return workspace-visible content — documents in role-restricted folders are never exposed through a workspace API key.

Search is semantic and operates at the section-chunk level: it embeds your query (Google Gemini, 768-dim) and matches it against document-section vectors with pgvector, returning the most relevant passages plus their heading breadcrumbs. There's also grep for exact-string / regex matching when you know the literal term. See the Search API.

Public knowledge base​

A workspace can publish a public, read-only knowledge base — its workspace-visible folders and documents, browsable and searchable by anyone, with an optional custom domain. Role-restricted content never appears in the public KB. It's toggled from workspace settings.

How it fits together​

 Slack · GitHub · Linear · Google Drive · Granola · MCP · imports
                              │
                              ▼
                      ┌──────────────┐
                      │   Captures   │   immutable buffer
                      └──────┬───────┘
                              │  librarian sweep (LLM)
                              ▼
                      ┌──────────────┐
                      │  Proposals   │   reviewed (smart / always-review)
                      └──────┬───────┘
                              ▼
                      ┌──────────────┐
                      │  Documents   │ → folders, topics, links
                      └──────┬───────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
   Dashboard              REST API           MCP (agents)
                                              + Public KB

Next steps​