Key Concepts
Understanding how SourceBrain models knowledge will help you get the most out of it. This page covers the five core building blocks.
Lessons
A lesson is a single document in your knowledge base. It contains Markdown content: anything from a short note to a detailed explanation of a system component. Lessons are the atomic unit of knowledge in SourceBrain.
Think of a lesson like a wiki article: it covers one focused topic and links to related lessons with wikilinks, writing another lesson's path in double brackets ([[auth/jwt]]). Those links are two-way: each lesson shows its backlinks, and the whole knowledge base renders as a navigable graph in the web app.
Paths
Every lesson has a path: a slash-separated identifier that determines where it lives in the tree. Paths are freeform; SourceBrain doesn't enforce any schema. Design them to reflect your system's structure.
Common patterns:
auth/jwt # feature / subtopic auth/oauth/google db/migrations # layer / concern db/indexes api/rate-limiting api/errors infra/deployments infra/secrets
Versions
Every time a lesson is created or updated, SourceBrain saves a new version. The current content is always the latest version. Older versions are retained indefinitely so you can see how your understanding evolved.
Each version records:
| Field | Description |
|---|---|
content | Full Markdown text of the lesson at that point in time |
message | Optional note explaining what changed (like a commit message) |
author | Email of the user who saved the version (cloud mode only) |
created_at | Timestamp when the version was saved |
View the version history of any lesson with:
sourcebrain log auth/jwt
Workspaces
A workspace is a shared, named knowledge base in cloud mode. Each workspace has its own tree of lessons. A user can belong to multiple workspaces.
One person creates a workspace and becomes its owner. Owners and admins invite other users by email. Members can read and write lessons; admins additionally manage members and workspace settings. Only the owner can delete the workspace.
Workspace vs. local database
| Local mode | Cloud workspace | |
|---|---|---|
| Storage | .sourcebrain/sourcebrain.db (SQLite) | Server-side PostgreSQL, shared |
| Access | Only on this machine | Any browser or logged-in CLI |
| Collaboration | None (single user) | Multi-user, invite by email |
| Auth required | No | Yes |
| Offline | Yes | No |
Switching workspaces
You can belong to many workspaces. The active workspace is stored in ~/.sourcebrain/config.json. Switch with:
sourcebrain workspace use other-team
Organizations (Pro)
With one workspace per repo, a company quickly has many workspaces and N member lists to keep in sync. An organization fixes that: it groups workspaces behind a single member list, so joining the org grants access to its org-visible workspaces automatically and leaving revokes it. A workspace can also stay private inside the org (grouped, but invite-only). Workspaces keep their own slugs and URLs; the org is a grouping, not a container you switch into.
The sharing model stays a set of concentric circles, each one ring wider: your personal lessons → lessons shared with named people → a workspace → a team inside it → the organization across workspaces. Cross-repo knowledge lives once, in a shared workspace, and is referenced by qualified links ([[ws:Platform/errors]], written with the workspace's name) instead of being copied around.
Plans & limits
Cloud workspaces are subject to per-plan limits. When you hit one, the server responds with a clear message (for example, "free plan allows 150 lessons; upgrade to Pro for unlimited") instead of silently failing. Upgrade from the Workspaces page in the web UI.
| Limit | Free | Pro | Enterprise |
|---|---|---|---|
| Workspaces you own | 1 | Unlimited | Unlimited |
| Organizations you own | None | 5 | Unlimited |
| Members per workspace | 3 | 25 | Unlimited |
| Lessons per workspace | 150 | Unlimited | Unlimited |
| Search | Keyword | Keyword + semantic | Keyword + semantic |
| Relevance scores | No | Yes | Yes |
| AI lesson suggestions | 3 (trial) | 300 / month | Unlimited |
| Staleness checks (sourcebrain doctor) | Stale references | + symbol-level drift | + symbol-level drift |
| Conflict detection | No | Yes | Yes |
.sourcebrain/ database can hold as many lessons as you like; plan limits apply only to cloud workspaces.Sync: push and pull
When you have both a local .sourcebrain/ database and a cloud workspace, you can sync between them with push and pull.
How sync works
SourceBrain compares lessons by content hash (SHA-256 of the latest version content). If hashes match, the lesson is in sync and nothing happens. If they differ, SourceBrain classifies the state:
| State | Description | Action |
|---|---|---|
| In sync | Same hash on both sides | Skip |
| Local only | Exists locally, not on cloud | Push: upload to cloud |
| Cloud only | Exists on cloud, not locally | Pull: download locally |
| Conflict | Both sides changed independently | Prompt you to resolve |
Conflict resolution
When a conflict is detected, SourceBrain shows a unified diff of the two versions and asks you what to do:
Conflict: auth/jwt --- local +++ cloud @@ -1,3 +1,3 @@ -JWTs expire after 30 days. +JWTs expire after 7 days (tightened in v2.4). Secret is in env SOURCEBRAIN_JWT_SECRET. [k] keep local [c] cloud wins [e] edit manually [s] skip
| Choice | Effect |
|---|---|
k | Upload local content to cloud, overwriting the cloud version |
c | Write cloud content to local, overwriting the local version |
e | Open your editor with both versions for manual merge |
s | Skip this lesson; neither side is modified |
Context export
The context command is SourceBrain's AI integration feature. It searches lessons by keyword and bundles the matching ones into a single Markdown document you can paste into an AI chat.
sourcebrain context "rate limiting" sourcebrain context "database" sourcebrain context "auth" # > context.md
The output is a well-formatted document with each matching lesson under its own heading. No configuration needed; it just works.
sourcebrain context "auth" > context.md