AI Integration

SourceBrain is built to feed your codebase knowledge to AI agents. There are three ways to do it, from a one-line copy-paste to a live two-way connection: the context export, the built-in MCP server, and the HTTP API.

1. Context export

The simplest integration. sourcebrain context searches your lessons and bundles the matches into a single Markdown document you can paste straight into any AI chat.

sourcebrain context "authentication"        # matching lessons
sourcebrain context                          # everything
sourcebrain context "auth" -o context.md     # write to a file

No account or configuration required; it works in local mode too. This is the right choice when you just want to give a model a snapshot of the relevant knowledge.

2. MCP server

The Model Context Protocol (MCP) is an open standard that lets AI tools call external tools. sourcebrain mcp starts an MCP server over stdio, giving an agent live, two-way access to your knowledge base: it can search and read lessons before answering, and write new lessons when it learns something worth keeping.

Setup

1. 1

   Pick your backend

   The MCP server uses the same auto-detection as every other command. For a cloud workspace, log in and select it first:

   sourcebrain login
   sourcebrain workspace use my-team

   For a local-only knowledge base, just make sure you launch your AI tool from a directory that contains a .sourcebrain/ folder.

2. 2

   Add SourceBrain to your AI tool

   In Claude Desktop, edit claude_desktop_config.json (Cursor and other MCP-capable editors use an equivalent settings file):

   claude_desktop_config.json

   {
     "mcpServers": {
       "sourcebrain": {
         "command": "sourcebrain",
         "args": ["mcp"]
       }
     }
   }

   Make sure the sourcebrain binary is on your PATH, or use an absolute path for command.

3. 3

   Restart your AI tool

   Restart the app so it picks up the new server. SourceBrain's tools will appear in the tool list, and the agent can start using them.

Available tools

The server exposes a full set of tools, grouped below. A well-behaved agent calls get_workspace_info first to orient itself, then searches, reads, and navigates as needed.

add_lesson, edit_lesson, list_lessons, search_lessons, and get_lesson also accept scope: "personal" to use your private My Lessons space on request. get_workspace_info leads with your active plans, so an agent has current-work context before it starts.

Workspace AI instructions

In cloud mode you can steer how agents use a workspace. Open the workspace's AI Settings page in the web UI and write Workspace AI Instructions: naming conventions, what to check before making suggestions, which namespaces matter most. These instructions are returned at the top of get_workspace_info, so every agent that connects sees them.

If you leave the field blank, SourceBrain uses a sensible built-in default that tells the agent to search before answering and to save new knowledge as it goes. Example of your own instructions:

Always check the auth/ namespace before suggesting authentication changes.
Our API follows REST conventions documented at api/conventions.
Path format for this team: layer/feature, e.g. backend/auth, frontend/routing.
When you add a lesson, use clear headers and include code examples.

The organization layer (Pro)

Workspaces grouped in an organization get two extra inputs to the AI context, both managed on the org page:

Org AI instructions apply across every workspace in the org and are included before the workspace's own instructions, which take precedence where they conflict. Shared context designates one org-visible workspace (say, platform) as the cross-repo conventions space: search, ask, the context bundle, and MCP retrieval then rank its lessons alongside the current workspace's own, slightly down-weighted so repo-specific knowledge wins ties. Shared lessons appear under their qualified path (ws:platform/errors), which get_lesson reads directly, and lessons can link across workspaces the same way, with [[ws:platform/errors]].

How agents get context: the layers

Guidance reaches the agent in two ways. Instructions are pasted into every agent's orientation document the moment it connects. Knowledge is retrieved by relevance while it works. Knowing which is which tells you where any piece of guidance belongs.

The rule of thumb: if the agent must always see it, it's an instruction; if it should be found when relevant, it's a lesson. If you find yourself writing the same sentence in several workspaces' instructions, it belongs in the org layer or the shared context workspace; if your instructions are explaining one function's behavior, that's a lesson with an anchor, not an instruction.

3. HTTP API

Every workspace is reachable over a small REST API, so you can wire SourceBrain into custom scripts or your own agent. Authenticate with the token saved at ~/.sourcebrain/config.json after sourcebrain login.

Authorization: Bearer <token>

How retrieval works

Every search, whether from the web UI, sourcebrain search, sourcebrain context, or an agent calling search_lessons, runs through the same relevance ranking, so an agent gets the lessons that actually matter instead of the whole knowledge base.

On a Pro workspace, semantic search is on automatically: lessons are embedded as they're written, and existing lessons are backfilled in the background. If it's ever unavailable, search transparently falls back to keyword ranking, so nothing breaks.

Lesson suggestion (Pro)

Writing the first draft of a lesson is the part people skip. SourceBrain can do it for you: point it at a file or a range of lines and it returns a draft { path, content } describing that code. It's a starting point; nothing is ever saved automatically. You review and edit the draft, then save it like any other lesson.

It's server-side and Pro-gated: the selected code is sent to the server, which calls a configured AI model and returns the draft. The feature is metered: each workspace gets a monthly quota of suggestions on Pro (Enterprise is unlimited).

Codebase scan (Pro)

A new workspace starts empty, and nobody wants to hand-write dozens of lessons. The codebase scanner bootstraps it: pick a set of files and SourceBrain drafts lessons for them in bulk, capturing the durable, non-obvious knowledge in each. As always, nothing is saved until you review and accept it.

Because your source code lives only on your machine, the scan is a handshake between the CLI (which can read your files) and the web app (where you pick files and review drafts):

1. 1

   Run the scan from your repo

   In a logged-in Pro workspace, run sourcebrain scan inside your project. The CLI sends a manifest (file paths and sizes only, never contents) and prints a link.

   sourcebrain scan

2. 2

   Pick files in the browser

   Open the printed link. The first time, you opt in to scanning for the workspace. Choose the files to scan from a folder-grouped list; already-lessoned files are marked, and a utilization bar tracks the estimated token cost against your budget so a scan can't run away.

3. 3

   CLI uploads, server drafts

   Once you start, the still-running CLI uploads just the selected files' contents. The server drafts 0 or more lessons per file (skipping anything trivial), pins each to the symbol or line range it describes, then runs a linking pass that weaves [[wikilinks]] between related drafts. File contents are never stored, only the drafts and the lessons you keep.

4. 4

   Review and accept

   Back in the browser, edit, accept, or reject each draft (or accept all). Accepted drafts become real lessons, anchored to their source code so doctor and refs work immediately, and already cross-linked so they show up as a connected knowledge graph from the very first scan.

Like lesson suggestion, scanning is metered: each workspace gets a one-time onboarding token grant plus a monthly scan budget on Pro (Enterprise is unlimited), and a per-scan cap bounds any single run.

Answering questions (Pro)

Sometimes you just want an answer, not a bundle to read. sourcebrain ask takes a natural-language question and returns an answer synthesized from your workspace's lessons, with citations to the lessons it used.

sourcebrain ask "how does authentication work?"
sourcebrain ask why do we cache the workspace plan
sourcebrain ask "what is the deploy process" --json

It runs the same relevance ranking as search to retrieve only the lessons most relevant to the question (not the whole knowledge base), then asks the configured AI model to answer from those lessons, so the answer stays grounded and cheap. When the workspace is in an organization with a shared context, those cross-repo lessons are considered too. --json returns a { answer, sources } object for tooling.

Recommended workflow

Connect SourceBrain as an MCP server and write a short set of Workspace AI Instructions. From then on, ask your agent questions normally, and it searches the knowledge base before answering, cites the lessons it used, and saves anything new it figures out. Over time the workspace becomes a shared memory that every agent and teammate benefits from.

For the task-shaped version of all this, see Recipes: how to import the memory files you already have, install the hooks so lessons reach the agent without being asked, and run the read-then-capture loop day to day.