Recipes
Practical things to do with SourceBrain and an AI agent, in the order you tend to need them: get what you already know into the knowledge base, make agents read it without being asked, then work the loop day to day. Every recipe below maps to a real command or MCP tool.
For what the MCP server and the HTTP API are, see AI, MCP & API. This page assumes you have one of them connected already.
| Group | What it covers |
|---|---|
| 1. Bring in what you already have | Memory files, note vaults, DDL dumps, AI drafts from your own source |
| 2. Make agents use it automatically | Hooks, house rules, and bridges for tools without MCP |
| 3. The session loop | Read before editing, capture after, keep the graph connected |
| 4. Keep it trustworthy | Review agent writes, catch secrets, retire wrong knowledge |
1. Bring in what you already have
Most teams are not starting from zero. There is a CLAUDE.md, a rules file, a folder of half-finished notes, maybe a schema dump. Getting that in first means the knowledge base is useful on day one instead of after a month of discipline.
Turn your agent memory files into lessons
Needs Nothing. Works in local mode.
sourcebrain import is the inverse of an export. Point it at a CLAUDE.md, an AGENTS.md, a notes folder or a vault, and each file becomes a proposed lesson you review before anything is saved. A multi-section document is split into one lesson per top-level section, so a sprawling CLAUDE.md becomes per-topic lessons an agent can pull individually rather than one monolith it has to swallow whole. YAML front matter is stripped and the lesson path is derived from the file's name and location.
sourcebrain import CLAUDE.md # one file, split per section sourcebrain import ~/vault/work/ --dry-run # see what it would create, save nothing sourcebrain import docs/notes/ --under legacy # park them all under legacy/ sourcebrain import ~/personal-notes/ --personal # into My Lessons, not the team sourcebrain import CLAUDE.md --no-split # keep the file whole, one lesson
Files can live anywhere on disk, inside the repository or not. Start with --dry-run on a big folder: it is the cheapest way to see how the paths will come out before you commit to them.
add_lesson is slower and less consistent.Turn a schema dump into data-model references
Needs Nothing. Works in local mode.
Point the same command at a SQL file and each table becomes a draft schema node, which agents can later read as structured JSON instead of prose.
sourcebrain import schema.sql # DDL dump, one draft schema per table
Draft lessons for the files that matter most
Needs Pro, logged in
sourcebrain scan bootstraps a workspace from your own source. The CLI sends a list of file paths and sizes, then prints a link. You open it, pick which files are worth documenting while watching a budget bar, and only then are those files' contents uploaded and drafted. You review and accept the drafts in the browser. Nothing is saved automatically.
sourcebrain scan
Pick ten files, not two hundred. The value is in the code a newcomer would misread, not in the code that explains itself.
Draft one lesson from a file or a selection
Needs Pro (free trial), inside a repo initialized with sourcebrain init
When you have just finished reading something gnarly and want it written down, sourcebrain suggest drafts a lesson for a file, or for a line range inside one.
sourcebrain suggest internal/auth/token.go sourcebrain suggest internal/auth/token.go --lines 40-58 sourcebrain suggest src/app.jsx --json # for editor integrations
The MCP equivalent is suggest_lesson, which returns a draft and does not save it. Your agent should show you the draft and save it with add_lesson only once you agree.
Say to your agent
“Draft a lesson for the retry logic in internal/queue/worker.go lines 80 to 140, show me the draft, and save it only if I say so.”
2. Make agents use it automatically
A knowledge base an agent has to remember to consult is a knowledge base that gets consulted about a third of the time. These three recipes remove the choice.
Install the hooks so lessons arrive on their own
Needs Claude Code, sourcebrain on PATH
sourcebrain integrate claude-code wires three hooks into Claude Code's settings, so the loop stops depending on the agent deciding to call a tool:
| Hook | What it does |
|---|---|
| SessionStart | Injects orientation and the lesson index at the top of the session |
| PreToolUse | Before a file is edited, surfaces the lessons anchored to that file |
| PostToolUse | After an edit, flags the lessons that edit may have invalidated |
sourcebrain integrate claude-code # personal, .claude/settings.local.json sourcebrain integrate claude-code --shared # committed, whole team sourcebrain integrate claude-code --print # preview, write nothing sourcebrain integrate claude-code --remove # uninstall
The merge is additive and only touches handlers that call sourcebrain hook, so your other hooks survive install, reinstall and removal. On a machine with no knowledge base configured the hooks are silently inert, which is what makes --shared safe to commit before everyone has set up.
Set house rules once, for every agent that connects
Needs Cloud workspace
Organization AI instructions are served at the top of get_workspace_info, the orientation document every connecting agent is told to read first. Set them once and every agent, every teammate, gets the same standing guidance.
sourcebrain ai-instructions # show current sourcebrain ai-instructions set "Check auth/ before touching sessions" sourcebrain ai-instructions set # edit in $EDITOR sourcebrain ai-instructions set "" # clear, back to default
This is the CLI counterpart to the web AI Settings page. Good instructions are about precedence and process, not facts. Facts belong in lessons.
Bridge to a tool that does not speak MCP
Needs Nothing. Works in local mode.
Two exports cover everything else. sourcebrain export assembles your lessons into a single rules file, and sourcebrain context bundles a query's worth of lessons for pasting into any chat window.
sourcebrain export # CLAUDE.md (default) sourcebrain export agents-md # AGENTS.md sourcebrain export markdown # sourcebrain-export.md sourcebrain context # everything sourcebrain context "authentication" # just the matching lessons sourcebrain context "auth" -o ctx.md # write to a file
Re-run the export after editing lessons to refresh the file. It also means no lock-in: your knowledge goes back out to plain Markdown whenever you want it.
3. The session loop
These are the recipes you use every day once the connection exists. They are worth saying out loud to your agent a few times, until the hooks and habits take over.
Ask what is documented before touching a file
Needs MCP server running inside the local repository
lessons_for_file is the reverse of a lesson's reference list: given a source file, it returns the lessons anchored to it, including the specific symbol or line range each one covers. It is the cheapest possible check against rediscovering a gotcha the hard way.
Say to your agent
“Before you change internal/auth/token.go, check what lessons are anchored to it and tell me if any of them constrain what we are about to do.”
Catch the lessons your change just invalidated
Needs MCP server running inside the local repository
check_lessons with changed_files reports what a specific change may have broken, and it catches two kinds: lessons anchored to a file you touched, and lessons whose content is about what changed even when they point somewhere else entirely. That second kind is the one people miss.
Say to your agent
“I just changed the session table and the login handler. Check which lessons that invalidates, then walk me through updating each one.”
Without arguments the same tool sweeps the whole repository for lessons whose referenced code has changed or disappeared. The CLI half of this is sourcebrain doctor, and sourcebrain verify clears the warning on a lesson you have checked and found still accurate.
sourcebrain doctor # what looks stale sourcebrain verify auth/sessions # checked it, still true, clear the flag
Capture at the end of a session, then wire it in
Needs MCP server
The end of a debugging session is when you know the most and are least inclined to write it down. That is exactly the moment to spend a sentence on it.
Say to your agent
“We just spent an hour on that timezone bug. Write it up as a lesson with add_lesson, then call suggest_links and weave in the ones that genuinely fit.”
Use edit_lesson rather than add_lesson when changing part of an existing lesson: it replaces an exact string, so nothing outside the changed text can be silently rewritten. Either way the result is saved as a new version, so the old one is never lost.
suggest_links is advisory. A couple of strong links beat a dozen weak ones, and an agent left unsupervised will happily add the dozen.
Have the agent query against the real data model
Needs A schema node in the workspace
Ask for a schema with format="schema" and get_lesson returns the parsed data model as structured JSON rather than prose. For writing a query or reasoning about a field, that is meaningfully more reliable than having the model read a table rendered in Markdown.
Say to your agent
“Read the subscriptions schema as structured JSON before you write this query, and tell me which columns have gotchas recorded on them.”
sourcebrain schema diagram # every schema as a Mermaid ER diagram
Check the accepted plan before starting work
Needs Cloud workspace
Plans are forward-looking, status-tracked lessons. Before an agent starts building in an area, it can check whether there is already an accepted or in-progress plan for it, and advance that plan as the work lands.
Say to your agent
“List the plans for the billing area and check whether any is accepted or in progress before you start. If one covers this, follow it.”
Statuses run draft, proposed, accepted, in_progress, done and archived, and only valid transitions are allowed. Proposing a draft is what publishes it from private to the team, so a plan can be drafted in the open without being announced.
Answer from the knowledge base instead of re-reading the repo
Needs search_lessons is free; sourcebrain ask is Pro
search_lessons returns the full content of the top matches ranked by relevance, so an agent can answer without opening a single source file. Where semantic search is configured, matches by meaning are included and marked as such.
sourcebrain search "rate limit" # ranked lessons sourcebrain ask "why do we retry twice?" # answered from your lessons (Pro)
4. Keep it trustworthy
A knowledge base agents can write to needs a way to be wrong safely. These are less recipes than the guardrails worth turning on before you invite anyone else in.
Review what agents write
With the approval workflow on, a write from an agent or a non-admin parks as a change request instead of landing. The MCP tools say so plainly in their response, so the agent knows to tell you rather than assuming it succeeded.
sourcebrain requests # pending change requests, to approve or reject
The MCP counterpart is list_change_requests. Admins see everything pending, members see their own.
The secret guardrail
Content entering the knowledge base flows into search, embeddings, AI context and every member's agent, and deleting the lesson later does not un-share it. So writes are scanned for likely credentials. Detection is warn-and-confirm rather than a hard block: interactively you are asked, non-interactively the save is refused with guidance, and --allow-secrets is the escape hatch when the match is a false positive. MCP writes get a warning appended to the tool result.
Retire knowledge instead of destroying it
When a lesson stops being true, trash it rather than deleting it. The trash is a soft, recoverable delete that keeps the lesson and its full history.
sourcebrain delete auth/old-flow # to the trash sourcebrain trash list # what is in there sourcebrain trash restore auth/old-flow
The agent-facing version is the trash tool with action="delete", "restore" or "list". To see how a lesson got to where it is, get_lesson_history returns every saved edit newest first, and takes diff_from and diff_to for a unified diff between two versions.
A note on scripting
sourcebrain add and sourcebrain edit open your $EDITOR when no content is supplied, which will hang any script that calls them unattended. Always pass the content explicitly when automating.
sourcebrain add auth/jwt --content "JWT tokens expire after 1 hour" -m "initial"