The SideBrain Handbook

overview

SideBrain turns documents, emails and notes into questionable knowledge - locally on the Mac, at your own AI endpoint.

SideBrain consists of three parts that are delivered together as one app:

• The app — Menu bar icon, overview, brain explorer, chat and the windows for quick notes, question overlay and appointment accompaniment.
• The engine — processes every file fed in: extract text, determine title/type/date using AI, generate preview, write to the brain. Runs with an included Python runtime; nothing needs to be reinstalled.
• The Brain (gbrain) — the knowledge store. Either completely locally on the Mac (PGLite, without server) or as a remote endpoint that is shared by a team. Content is available as Markdown pages with types, tags and links.

Core terms

Brain

A knowledge repository (gbrain endpoint). Several brains can be stored in parallel - e.g. B. a private local and a shared project brain.

Push

The process of transferring content into the Brain: feed file → extraction → preview → confirmation → saved.

Note/Page

One unit in the Brain: Markdown content plus type, title, tags, date and links. Addressed via a stable Slug.

type

Canonical categories like person, company, deal, event, project, note, email, source — suggested by the AI, can be overruled in the preview.

Think

A question for the Brain: relevant notes are searched for, sorted and given to the AI model as context; the answer cites its sources.

AI profile

The stored model access (provider, endpoint, key) with which extraction and answers work.

Language of the surface

SideBrain speaks German, English, French, Italian and Spanish. The Mac's system language is automatically recognized (fr-*, it-*, es-* choose the appropriate language; any other non-German language remains English) — the language switcher in the settings changes manually and immediately at any time, without rebooting. The menu bar tray and the floating secondary windows (quick note, context chip, appointment accompaniment) follow an explicit language choice; System-side notifications (review, due items, scheduled reports) remain unchanged.

Installation & Setup

Three ways, one result: SideBrain comes with its entire runtime - no Python, no dependencies.

Via disk image

Load SideBrain.dmg, open, drag SideBrain into the Applications folder, start. Since the app is delivered without Apple notarization, macOS requires a right click → "Open" (Gatekeeper) the very first time it is started.

Via terminal

One command loads and installs the current version - the gatekeeper detour is automatically eliminated:

curl -fsSL https://dl.sidebrain.eu/install.sh | bash

Requirement: a Mac with Apple Silicon (M1 or newer). This terminal script covers macOS only — a Windows version (x86_64) is available (see the Windows section below). Intel Macs and Linux are not currently scheduled.

Via Homebrew

If you use Homebrew, install SideBrain from its own tap — after that, updates arrive as usual with brew upgrade:

brew install --cask m-dohmen/sidebrain/sidebrain

Since SideBrain is delivered without Apple notarization, Homebrew quarantines the app on download — so on the very first launch macOS asks once for a right click → "Open" (Gatekeeper). To skip that step, install with brew install --cask --no-quarantine m-dohmen/sidebrain/sidebrain. From then on the built-in auto-updater keeps the app current.

Windows (x86_64): Via installer

For Windows 10 (1809 and later) and Windows 11, SideBrain ships as its own Authenticode-signed NSIS installer. Load the installer, double-click, walk through the NSIS wizard (default path %LOCALAPPDATA%\Programs\SideBrain, installMode: currentUser — no admin, no UAC prompt required). The very first launch requires, depending on the machine's configuration, a one-time SmartScreen trust acknowledgement ("More info" → "Run anyway") — normal for signed software that has not yet built up SmartScreen reputation.

Updates: the built-in auto-updater checks https://dl.sidebrain.eu/latest.json on startup (key platforms.windows-x86_64), verifies the signature and installs new versions automatically. For manual updates, simply re-download the latest .exe and run it — SideBrain replaces the previous version without data loss.

Known limitations on Windows

The Windows port shares the core features with macOS and Linux. To make clear at a glance what works and what doesn't, the app shows an honest availability message for each platform-specific source instead of silently failing or leaving a dead button without explanation:

• iPhone capture (iCloud folder as watch folder): On Windows, the "Set up iPhone capture" button docks into the exact same watch-folder pipeline as on macOS — instead of the macOS iCloud container it monitors the iCloud for Windows folder %USERPROFILE%\iCloudDrive. If iCloud for Windows isn't installed, the app reports that honestly ("iCloud for Windows is not installed — install it from the Microsoft Store and sign in with your Apple ID") instead of swallowing the error.
• Meeting companion ("Accompany meeting"): macOS-only — it depends on Calendar.app and macOS audio. No equivalent on Windows v1; the dashboard button is greyed out and its tooltip points to screenshots and typed notes as alternatives. A Windows meeting recorder is planned as a separate effort, not part of this release.

Initial setup (onboarding)

When you start it for the first time, an assistant guides you through the setup in four steps — Welcome · Your Brain · AI · First push:

1. Your brain: “On this Mac” sets up a local Brain (recommended for getting started; installs gbrain including runtime). Alternatively, "Remote Brain" connects an existing team endpoint via URL and token.
2. Local search (recommended, can be deselected): If desired, a completely local semantic search can be set up for the local Brain - a bundled llama server with a multilingual embedding model (bge-m3) and Reranker, one-time ~880 MB download.
3. AI: Four levels to choose from:
   • Own Anthropic key — best quality, direct Claude access.
   • Start for free — One-click login to OpenRouter or LLM Gateway; Free models for answering, at no cost to yourself.
   • Completely offline — the included local model (one-time ~3.2 GB) answers questions completely on the Mac. Good for clear factual questions, noticeably slower (~3-4 s per answer) and inferior to the complex considerations of a cloud model - the assistant says that honestly.
   • Start without a key — first just collect; AI functions can be retrofitted at any time.
4. First push: Drag a file in, check the preview, apply – done.

If the setup was skipped or no usable brain is stored later, SideBrain offers the guided setup again when you start.

Updates

SideBrain updates itself: The built-in updater checks against dl.sidebrain.eu, loads signed update archives and installs them after confirmation. Each version is also available as a DMG in the download archive.

Uninstall

Settings → “Remove SideBrain” deletes the app completely — including Finder quick action, services and settings. If desired, the brain data is retained and can be accessed beforehand export as ZIP.

Capture knowledge

Every capture source flows into the same pipeline: validation → extraction → plausibility → preview → push. No special routes, the same reliable behavior everywhere.

Supported formats

• Documents: PDF, Word, Excel, PowerPoint, Keynote, Pages, Markdown, plain text files
• Emails: .eml files (e.g. pulled from Mail/Outlook) — subject, sender and date are recognized
• Pictures: Screenshots and photos with text content (vision extraction transcribes and categorizes)
• Audio: m4a, mp3, wav — transcribed locally
• Web: URLs — the page text is read and stored as a citable source
• Free text: about the Quick note or the share menu

Push preview & confirmation

Before each push, SideBrain shows what would be saved - nothing ends up in the brain unchecked:

• Title, type and date the AI suggests from the content (instead of “Image (3)” a meaningful title; instead of push date the actual document date). The type can be overridden using a switch.
• Edit content: The extracted text can be corrected directly before it is accepted.
• Context field: A sentence of your own classification (“belongs to Project Nordstern”) is also saved.
• Important star: Marks the note as priority - pre-assigned by the AI for decisions and deadlines. Important notes are given priority in the brain's relevance weighting.
• Skip discards the push; If auto-push is activated, the preview is automatically adopted after an adjustable period of time has expired.

Watch Folders

Any folder can be monitored - every file stored there is automatically added. Default is ~/SideBrain Inbox furnished.

• With confirmation (Default): The file goes through the normal preview.
• Auto push: The file is transferred directly without asking - for folders where only what you want goes anyway.
• Target brain per folder: If you have multiple brains, you can choose a different target for each folder - "everything from this folder goes into the team brain, the rest stays local". Folders with different destinations run as separate sessions so that each file ends up safely at the right Brain.

Quick note ⌥ N & Screenshot

The menu bar icon (and the shortcut ⌥ N) opens a small floating window for thoughts in between - type in text, enter, saved. “Screen clipping…” in the menu starts the macOS interactive area selection; The screenshot then goes through the normal vision extraction including preview.

Voice memos (audio files)

m4a, mp3 and wav files are pushed like any other file: SideBrain transcribes them first completely local (included Voxtral model, same infrastructure as that Appointment transcript) and then sends the text through the normal pipeline. Strict transcription instructions ensure that transcription is carried out verbatim rather than summarized - numbers and instructions in the audio remain untouched. No audio leaves the Mac.

Requirement: the local language model is installed (one-time ~3.2 GB, see Appointment transcript). Without a model, the push reports the reason instead of silently failing.

iPhone capture

Settings → Watched Folders → “Set up iPhone tracking” creates a folder SideBrain-Erfassung in iCloud Drive and monitors it. Together with a one-time Apple shortcut (Share menu → Save file to this folder), photos, links, texts and voice memos from the iPhone automatically end up in the Brain - voice memos including local transcription. The step-by-step instructions for the shortcut are included with the app.

Other recording methods

Finder Quick Action

Right click on each file → “SideBrain”. No opening, no pulling necessary.

Drag and drop

Drag files into the main window, into the chat window (there additively, without a preview dialog) or into the appointment window.

Services Menu “Send to SideBrain”

Highlighted text or link in any app → right click → Services → “Send to SideBrain”. A pure URL (also marked in quotation marks, angle brackets or with punctuation marks at the end) is pushed as a link note with page content read; anything but a quick note. Feedback via message - no window interrupts the flow.

Print → SideBrain

Save as a PDF note from any app using the print dialog - even where there is no export.

Double click / “Open with”

SideBrain is registered as a destination for PDFs.

URL scheme

sidebrain://push?path=… pushes a file out of shortcuts and scripts — see automation.

Notes.app import

Adopt existing Apple Notes as inventory — see Import & Export.

Extraction & Structure

SideBrain doesn't just store text - it builds structure so that files become context.

• Canonical types: Each note gets a type (person, company, deal, event, project, concept, note, email, source …). Resumes and LinkedIn profiles are automatically saved as person recognized; Offers, tenders and contracts as deal; meetings as event — each with real ones event_date for the timing.
• Avoiding duplicates: The same person or company lands on one Page, even if it comes from different files — existing entities are reused instead of creating hash suffix duplicates.
• Auto link: If a note mentions people or companies that already exist in the Brain, a graph edge ("mentioned") is automatically created - conservative (full names, word boundaries), the text remains unchanged.
• Timeline milestones: Dated milestones in the document (go-live, deadline, kickoff) are created as timeline entries.
• Line of origin: Every file/mail note ends with “Source: …” (origin + date) — the provenance is part of the content and can therefore be quoted.
• Noise filter: Almost empty extractions (e.g. screenshots without text) get the tag braucht-nacharbeit, instead of ending up unnoticed as a blank page.
• Fact extraction (opt-in, experimental): If desired, the AI creates a structured fact block for clear, permanent facts, from which the brain builds a fact table - the basis for Trajectories and targeted Forget.
• Follow-up detection: If there is a timed point in a document (“Offer out by August 15th”, “Cancellation period: September 30th”), SideBrain notes it - purely rule-based, without an AI call, only saved locally. Points due appear on the Overview and report once via message.

Questions & Answers

Each answer is based solely on your brain and cites its sources — no made-up facts.

“Ask your second brain” (overview)

The question panel on the overview answers questions in natural language. The answer shows clickable source chips (open the note in Brain Explorer), recognized gaps in knowledge as a separate reference with a jump to the Quality Boost, and references in the answer text jump directly to the linked note. Questions can be asked in the same conversation (⌘ ⏎ sends).

Verbund: a question for all Brains

If you have stored several brains, select the option in the question panel and in the chat "All Brains (Composite)": The question runs parallel against each connected Brain, the answers appear as a view with one section per Brain. Each source chip has the name of its brain - a click opens the note in the correct brain (the explorer switches there automatically). An unreachable Brain appears as a short note in its section without hiding the rest of the answers.

Chat

The chat tab is the full-fledged conversation window with the Brain:

• Conversation history remains intact when changing riders; The brain in question can be selected at the top and shows the status and page number - with a clear indication if the active brain is empty or not accessible.
• Attachments: Files added using the attachment button or via drag & drop are permanently loaded into the brain and are immediately available as context for the conversation.
• Correction feedback: "Thumbs down" under an answer opens a field for a correction note, which is pushed into the brain for optimization - optionally with explanatory files.
• Export: Each answer can be saved as a Markdown file (question, answer, list of sources) in downloads - ready for the meeting document.

Question overlay ⌥Space

The shortcut opens a floating spotlight window above everything: type in a question, read the answer with sources, continue working - without opening the app or changing the context. Also via sidebrain://ask?q=… accessible from shortcuts.

Question templates

Own one-click questions (Settings → “Question templates”): Save label + question, e.g. E.g. “Weekly Review” → “Summarize what I added this week.” Saved templates replace the built-in sample questions on the overview.

Quality Boost — closing knowledge gaps

The AI finds specific questions based on the gaps in your brain and asks you them one after the other - you take 5, 10 or 15 minutes, your short answers flow directly back into your brain as notes. “Gap detected” becomes “Gap closed”. Operation with progress display, skipping and ⌘ ⏎.

The overview

The home view bundles key figures, reminders and everything the brain has to proactively tell you. Cards only appear if they have content - no empty boxes.

Key figures & brain status

Pushes (7 days/total), success rate, characters transferred; next to it is the active brain with engine type (local/remote), page number, gbrain version and update note.

Privacy status

Shows live whether extraction, search and answers are currently running locally or via a cloud service - “exit proof” at a glance. Honest even with mixed operation.

Review (Digest)

What came into the Brain this week (or daily, adjustable) — with activity sparkline, new notes, optional objection and due point counters, Markdown export and opt-in notification.

Points due

Appointments for the next 7 days recognized when filing, overdue items marked in red with a “Done” button. Saved locally only.

Contradictions

Conflicts between notes (e.g. different numbers on the same topic) with severity - from the brain's last contradiction check, reading purely, one click opens the note.

Today before…

Events from previous years that fall on today's calendar day — remembering as a function, not just saving.

Noticed something unusual

Statistical activity outliers (significantly more notes of one type than usual) — can be switched off without calling AI, at most ~2 times per week.

Upcoming appointments

Upcoming calendar appointments for the next 7 days, each with an “Accompany appointment” button, which starts the appointment window with title and participants. Requires macOS automation approval for the calendar once.

Last activity

The most recent pushes with status; Jump to the full history with text search and status filter.

MCP addresses

The local HTTP URL of the MCP server (click copied) — for integration into Claude Desktop & Co.

Quick Actions

Quick note, screenshot, accompany appointment and draft directly from the overview.

At the very first start (no pushes yet), the overview shows a greeting with three steps to the first push instead of empty cards.

“Your brain can do something now”

As soon as enough knowledge has been accumulated - from ~50 successful entries according to your local history or 14 days after the first start with this version (for existing users the 50 threshold usually applies anyway) - the overview shows the map once “Your brain can do something now”. You click on “Show example questions”, SideBrain calls the AI once and generates up to five example questions that your brain can now answer with its current knowledge; click one of the questions to ask it directly. With the ✕ ("Hide") or after generation the map disappears permanently - it will not come back, there will be no notification about it and no recurring campaigns. The trigger (counter, date, whether already shown) remains completely local on your computer.

Document workshop: Your brain writes the first draft

The "Draft" button in the quick actions opens "Document workshop": first select a template - the offer, status report, customer letter and project summary are built in, as well as your own Markdown templates from the settings (section “Design templates”; placeholders in square brackets like [Kunde] or [Leistungen]). Then describe the order in one sentence - for example "Offer for Stadtwerke Musterstadt for cloud migration, three phases, starting in September" - and click “Create draft”. The Brain fills the template with proven knowledge from the notes and sources; where knowledge is missing, a placeholder „[offen: …]" remains instead of made-up facts. The preview appears directly in the app, export optional “As Markdown (.md)” or "As Word (.docx)" — without any additional software, using macOS’s on-board resources — the file ends up in downloads and is shown in the Finder. As with questions and the customer dossier, only one long query is running at a time, with a cancel button at any time. A note in advance: The document workshop provides a first draft for further work - not finished stationery or corporate design layout.

Brain Explorer

The Explorer is the inventory view of the brain: search, read, maintain - without a command line.

Search & browse

With several Brains, the sidebar shows a “Brains” section: one entry per connected Brain plus “All Brains (Composite)” — one click switches the active Brain, just like switching drives in the Finder. SideBrain also remembers the last Brain you chose across a restart. In the Composite view, list and search run across every connected Brain, each entry carries an origin chip. Opening, editing, tags and links automatically affect the note's source Brain. The overview also shows the composite key figure (“X of Y Brains accessible · N pages total”).

• Full-text search across all notes; without a search term, the most recently updated pages.
• Category sidebar: On the left of the Explorer, just like in the Finder — “All notes” and the categories (People, Companies, Projects, Appointments, Offers, Concepts, Sources) with a hit count, empty categories hidden. One click filters the list, the selection is kept when switching between tabs and when switching Brains; fully operable via Tab and arrow keys.
• Column list: The notes appear in columns like in the Finder — Name, Type and Modified. A click on the Name or Modified column header sorts ascending or descending, an arrow icon marks the active column and direction; the column headers are also keyboard-operable. The full-text search still shows result snippets instead of the columns.
• Tags in the sidebar: Below the categories, the sidebar shows the most-used tags of the active Brain, sorted by frequency (“Show more” for further ones). A click filters the list to notes with that tag and can be combined with the category; clicking again removes the filter. In the “All Brains” composite view, a note there explains that tags are only available per Brain; a Brain without any tags does not show the section at all.
• Preview instead of a window: A click on a list entry shows the note directly in a third column to the right of the list — title, type, tags, meta, rendered Markdown with clickable [[Wikilinks]] as well as relationships (“Referenced to” / “Mentioned in”) are available there, while the list stays visible and operable. This lets you click through several notes in a row without opening or closing a window. Without a selection, the preview shows an empty state; on a narrow window it fully replaces the sidebar and the list, and a “Back to list” path leads back.
• Fully operable by keyboard: Arrow up/down moves the selection in the list — the preview follows immediately, the row scrolls into view. Enter additionally focuses the preview, Esc returns to the list. Tab cycles through sidebar → list → preview in a comprehensible order, arrow keys navigate within the sidebar (Brains, categories, tags). Typing a letter / start of a word jumps by typeahead to the first matching note, ⌘F focuses the search. The focus is clearly visible in both themes, and the list carries appropriate ARIA roles for screen readers.

Curate & Clean Up

Edit (Markdown editor)

Change title, type, tags and content directly — with the “Edit / Preview” switch: The preview renders the Markdown live, including clickable ones [[Wikilinks]]. The slug remains stable, references do not break; Cancel with unsaved changes prompts you. The automatic timeline zone (line of origin, transcripts) does not appear in the editor and is guaranteed to be retained when saving - a fold-out note shows it read-only.

Tags & Links

Remove tags with ✕ and add them with “+ tag”; Set links using “+ link” and remove using ✕ - directly in the note view, without editing mode.

Merge

Combine two notes: content is merged, references are changed, the duplicate is deleted.

Duplicate review

SideBrain suggests suspiciously similar pairs (same slug base, included titles, heavily overlapping titles in the same category). For each pair you choose which note stays; The couple permanently remembers “No duplicate.” Nothing happens without a click.

Forget facts

Delete individual incorrect or outdated facts from the fact list of a note without deleting the note - clearly marked and survives a rebuild.

Clean up titles

Existing backfill: Pages with meaningless titles ("Image (3)") get descriptive titles derived from the content - with a preview (old → new) before applying.

Versions & Trash

Versions: The note detail shows previous versions (time + preview); "Restore" resets the note after confirmation - the current status is saved as a version; a rollback never results in data loss. Trash: Deleted notes remain recoverable for 72 hours.

Graph, experts & trajectories

Graph view

Interactive Link Map: the note in the center, relationships radially around it, color-coded by type — outbound references solid, inbound mentions dashed. Clicking on a neighbor centers it (explore with back path).

Expert search

"Who knows about this?" — Enter topic, SideBrain shows the people (and entities) who contributed the most to the Brain with relevance percent. Particularly valuable in the team brain.

Trajectories

Notes with recorded key figures (projects, deals) show a chronological "development over time" list - e.g. B. Budget history and milestones.

Customer dossier

For the quarter of an hour before the customer appointment: The button "Dossier" When a person or company is opened, a one-view file is created - an overview, last interactions and open points as a synthesis with sources, as well as the recorded facts and all linked documents. Each component loads individually and degrades on its own; If one fails (e.g. because no synthesis is currently available), the others still remain visible - a dead component never prevents the entire dossier. The dossier opens as a dialog above the Explorer and can be exported as a Markdown file with a click (ends up in Downloads, then the Finder shows the file directly); a cancel button ends the creation at any time. Only one long request is running at a time - the chat, question panel and overlay also wait until the dossier is finished or canceled. Also available via command line/skill: --dossier "Name".

Accompany appointments ⌥ T

A window for the meeting: notes, attachments, transcripts and participants - when it is closed, a linked, questionable appointment note is created.

• Pre-filling from the calendar: If an appointment is currently running, the title and participants window automatically takes over. From the “Upcoming Appointments” overview card, “Accompaniment to Appointments” starts the window specifically with a selected appointment for the next 7 days.
• Notes & Attachments: Free text plus files and screenshots attached via drag & drop — attachments are pushed and linked to the appointment note; Participants are connected as people.
• Transcript (local): “Start recording” transcribes what is said completely on the Mac (Voxtral Mini via the bundled llama server, 8 languages including German, one-time ~3.2 GB, opt-in). The text appears live in sections and can be corrected immediately. Speech pause editing and silence filters prevent hallucinations; the model is only loaded when needed (~4 GB RAM only during the appointment). Nothing goes online.
• Event summary: When finalizing, the AI combines notes and transcripts into a protocol header - summary, decisions, open points, each with responsible persons and dates. The summary is at the top of the appointment note (preferred by search), the full transcript goes into the timeline zone. If the AI call fails, it saves without a summary — never a blocker.
• Appointment preparation: "What does my brain know about this?" asks before the appointment with title + participants as context and shows relevant facts, open points and sources.
• Design survives everything: The status of the window is continuously saved locally and survives app restarts and accidental closing. Detected open points with dates flow into the Points due.

Calendar access requires macOS approval once (System Preferences › Privacy & Security › Automation). Without approval, the prefill simply remains empty - nothing gets stuck or blocked.

Automation & Reports

Scheduled reports

Recurring questions to the Brain at a fixed time (Settings → “Scheduled Reports”): e.g. B. “Project status Nordstern, weekly Monday 8 a.m.”. A notification will appear at the set time, the answer including the source list is available as a Markdown file in Downloads. "Try Now" checks a report immediately. Each report is a conscious decision (question + schedule created by yourself) - SideBrain never plans paid AI calls on its own.

Knowledge report instead of question: For each scheduled report, you choose the type — “Question Report” (as above) or “Knowledge report”. It reports not on a question asked, but on your brain itself: inventory, new/updated (total and per type, the five largest increases), questions asked from the app (counted locally - chat, overview, question overlay, customer dossier, document workshop; questions from external MCP/skill clients do not count) and open contradictions, each in comparison to the previous period (the first report still had no previous period), plus a short "That's happened done" paragraph from your brain. If a block is missing, it says "not available" - the report still comes. Delivery like any report (notification + Markdown file, optional Teams/Slack); “Try now” also works for the knowledge report without a question being entered. Question counting remains entirely local (60 days) — no telemetry.

Optionally post to Teams or Slack: One per report (and when looking back). Incoming webhook URL deposit — the address that Teams issues under “Add Connector” or “Workflows” or Slack under “Incoming Webhooks” for a channel. If a URL is entered, SideBrain will post an abbreviated version (max. 3,000 characters) at the set time in addition to the notification, indicating that the complete report is in SideBrain. Teams “Workflows” URLs (logic.azure.com) SideBrain automatically recognizes and formats the message as an Adaptive Card; all other targets (Slack, Mattermost, classic Teams connectors) get plain text JSON. The last delivery status for each report is directly in the settings; “Try now” also checks the delivery. Only the self-ordered report content goes to the self-entered URL - no telemetry, no additional data outflow.

URL scheme sidebrain://

Makes SideBrain embeddable in Apple shortcuts, keyboard automations and scripts:

sidebrain://push?path=/Pfad/zur/Datei.pdf   → Datei pushen (wie per Drop)
sidebrain://ask?q=Was%20ist%20offen%3F      → Overlay öffnet mit gestellter Frage

Review (Digest) & Dream Cycle

The Review summarizes what came into the brain on a daily or weekly basis - building blocks (contradictions, due points) can be activated individually, notification as opt-in, export as Markdown. Just like with scheduled reports, the review can optionally be posted to a Teams/Slack webhook URL (shortened, with a link to the full version in SideBrain); “Show now” also checks the delivery. The Dream Cycle (Opt-in) lets the local brain consolidate at night (entity sweep, quote fixes, memory consolidation) — at most once every ~20 hours as long as the app is running, plus at any time at the push of a button with a dry run option.

AI connection

SideBrain does not have a mandatory model and is not tied to any provider. Three layers are separately configurable: extraction, answers and search.

AI profiles (extraction)

Under Settings → AI endpoints, model access is stored as profiles: Anthropic Claude (directly or via gateway with its own base URL/auth token) and OpenAI compatible endpoints with ready-made templates for OpenAI, Azure OpenAI / AI Foundry, Google Vertex AI, LiteLLM, Ollama, LM Studio, vLLM, OpenRouter and Groq. Multiple profiles are possible in parallel; File type rules assign their own profile to certain endings (e.g. “.pdf → Haiku, Rest → Sonnet”).

Answers / Synthesis (Think)

The response endpoint can be selected independently of the extraction:

• Claude (default) — automatically uses the AI profile including complete access data (including gateway constellations).
• OpenAI compatible — any /v1-Chat endpoint with the same templates as above.
• SideBrain locally — the included model responds completely on the Mac, without a key, even in airplane mode. It is the same model as for the appointment transcript: the download only has to be done once, the server is shared.
• Start for free — One-click login to OpenRouter (model openrouter/free) or LLM Gateway (free credit).

Search: Embeddings & Reanchors

The local brain's semantic search is opt-in and open to providers:

• Locally bundled (recommended): Included llama server with multilingual bge-m3 embedding model and bge-reranker-v2-m3 — ~880 MB once, then completely offline. Offered during setup and actively offered once to existing installations.
• Alternatively: Ollama (local), OpenAI, Azure OpenAI, ZeroEntropy (zembed-1) and Voyage AI — some with selectable vector dimensions (Matryoshka: less memory for slightly less accuracy). Or consciously do pure keyword searches.
• Robust model change: Before each change, SideBrain checks what is necessary — same vector width: lossless recalculation; Another dimension: rebuilding with automatic backup. The confirmation says in advance which case will occur.
• Reanchor: re-sorts search hits via cross-encoder before the answer (quality lever) - from, local (bundled) or ZeroEntropy.

Company proxy

SideBrain automatically reads the macOS system proxy and passes it through to all network calls (setup, extraction, search, responses) — even when the engine is started from Claude Desktop or as an HTTP MCP server. NO_PROXY protects localhost and the system exceptions. Without a configured proxy, nothing changes; pure PAC URL configurations are not evaluated.

License & test phase

SideBrain makes licensing questions invisible during the test phase and remains honest afterwards: your own data remains accessible, only new knowledge needs a suitable license.

30 days without a license key

The trial period begins when you first start the installation and lasts 30 days. During this time, capture, editing, search and all AI functions are fully available. There is no activation, no account and no online check.

What happens after it expires

Without a valid license, SideBrain blocks the creation of new knowledge: new acquisition, writing and AI synthesis are not possible. History, reading, searching and exporting existing data remain accessible. The app does not delete its own data and shows the reason for the block as well as both ways out.

Deposit license

Private, non-commercial use remains permanently free. Demand under sidebrain.eu/private license After a one-time Google login, apply for a private license, copy the signed key and paste it into SideBrain Settings → License a. The exam then takes place completely offline. Commercial use requires a commercial license; for this please contact vertrieb@incubateit.de.

The same model applies to MCP and Skill: Writing and synthesis are rejected after expiration without a license, but search and lookup remain possible. Details are in End User License Agreement.

EU AI labeling

SideBrain uses AI for extraction and answering — the app labels this accordingly in the footer.

In line with the labeling requirements of the EU AI Act, SideBrain permanently shows the official label for AI-generated content in the overview's footer. In dark mode it's automatically inverted for contrast; a localized alt text also makes the label accessible to screen readers.

Data security

Built for confidential company data: processed locally, without account requirements, without telemetry — and, if desired, provable 100% offline.

• Local processing: Text extraction and indexing run on the device. Plain text and emails are always extracted locally; Documents about the stored AI profile, with a local fallback path in the event of errors.
• Privacy status: The overview shows live and honestly which layer (extraction / search / answers) is currently running locally and which is running via the cloud.
• 100% offline possible: With local brain, local search and local answer model, the entire chain of filing → searching → answering works without a network. An automated flight mode test in the development pipeline proves this with every release: Push + Question works in an environment without any cloud access data.
• No telemetry: no home radio, no tracking, no mandatory account.
• Data sovereignty: All knowledge is available as Markdown and can be completely exported as a ZIP at any time - no lock-in.
• Only you decide where prompts go: AI calls only go to the configured endpoint, and only when someone actively asks or pushes. Time-controlled AI calls only exist where they have been explicitly created (planned reports).

License: SideBrain is proprietary software from IncubateIT (EULA under sidebrain.eu/license). Each installation runs completely without a license key for the first 30 days. The license area of the settings checks an inserted key completely offline (no activation server, no phone home) and, if it is valid, immediately shows the name, email, license type (private/commercial) and term - if there is a problem, an understandable reason without discarding the entry. Without a key, the same area shows the remaining test period and the path to a permanently free private license. You get them sidebrain.eu/private license: log in once with your Google account, request the key, copy it, paste it into the settings - done. The key then remains completely valid offline; Visiting the page again returns exactly the same key, no duplicates are created. This is also purely a compliance anchor, not technical enforcement. From 7 days remaining, a discreet, non-modal bar in the main window supplements this notice with the exact remaining status and a one-click path to the free private license - clickable away, returns the next day at the earliest and never disrupts ongoing recording. If the 30 days without a key have expired, SideBrain blocks new recording, editing and all AI functions (questions, group answers, curating, quality boost, etc.) - hard, without a grace period. Reading and searching through what has already been recorded remains expressly possible; A lock view explains exactly that and offers both ways out (enter the key or get a free private license).

Team brains & multiple brains

From personal storage to shared project knowledge — with clean separation between brains.

• Multiple endpoints: Any number of Gbrain profiles in parallel (local + remote). A profile is the default push target; Overview, chat and explorer allow the brain surveyed to choose freely.
• Team connection: "Connect to Team Brain..." in the settings guides you through joining: URL + token from the operator, connection is checked before creation, and the private Brain explicitly remains the default push target. Read/write permissions depend on the token scope.
• Project router: Watch folders can push to a different brain — project folder → project brain, everything else → private brain, sorted automatically.
• Reliable Identity: The Brain tile shows engine type, version and page number even without an admin token.
• Composite questions: “All Brains (Verbund)” asks private and corporate knowledge at the same time - with sources labeled for each brain (see Questions & Answers).
• Local / private CAs: For each HTTPS target you can relax the TLS certificate verification (opt-in per profile, off by default, confirmation dialog with a security warning). Only affects that exact brain; a second profile stays strictly verified. Applies to pushes, searches, think and “All Brains”.
• OAuth client authentication: For remote Gbrain targets (not for local stdio: brains) you can switch the authentication mode per target in settings from "API key" to "OAuth client" — token endpoint, client ID and client secret come from the target's operator and are stored locally in the existing secret store, never shown in plaintext, exported or logged. SideBrain fetches the access token via the client-credentials flow and renews it automatically before expiry or after a failed request; if renewal fails permanently, you get an understandable error instead of a silent failure. The default for new and existing targets stays "API key", there is no global default for all targets — the setting only applies to the one target you chose. This requires a GBrain operator that actually supports the client-credentials flow; SideBrain does not connect to an arbitrary third-party provider without a matching GBrain agreement.

MCP for developers

Your own knowledge as a model context protocol server — for Claude Desktop, Codex and every MCP client.

SideBrain provides its brain in two ways:

• Local HTTP server (Streamable HTTP): http://127.0.0.1:8765/mcp — port can be set, localhost only by default (optionally also reachable on the network, see “Mac as a Brain server on the network”), runs as a managed child process as long as SideBrain is open. On/off, token protection and live status in settings.
• stdio start command for clients that start processes themselves (e.g. Claude Desktop) — one-click installation of the desktop configuration included.

"mcpServers": {
  "sidebrain": {
    "url": "http://127.0.0.1:8765/mcp"
  }
}

Available tools: Push (feed files/text/URLs), Search and Think — read/write according to token scope. If there are several Brains, the compound tools also appear: think_all asks all Brains in parallel (answer with section and sources for each Brain), and each Brain has its own think_-Tool for targeted questions — so the assistant can route itself. context_for (when activated MCP context tool): provides the appropriate notes on a topic from all connected brains as a finished prompt context; via CLI at any time --context-for "Thema" — regardless of the toggle. Both transports share the same dispatch; Long-lived servers release the local brain when idle so that app and MCP clients don't block each other. An exportable one Skill describes the tools for agent clients. If the 30-day test phase has expired without a stored license, the same lock applies as in the app: writing and synthesis (push, think/think_all) reply with a structured error including a reference to the free private license, search and lookup remain possible without restrictions.

Push tools in detail

The four push tools mirror exactly the App-UI capture paths — same pipeline, no put_page workaround for agents:

• push_file (file path): PDF, Office, images, text, emails as .eml — engine handles extraction (AI conversion, OCR, image description).
• push_url (URL): a web page as a readable note — title and slug derived from the page, the same URL updates its note, schema identical to the App URL-Push (type: source, tags: [url-import, source], source_url, extracted_with, imported_at).
• push_shared (text/URL): auto-route shared content — a lone http(s)-URL becomes a URL-Push, anything else becomes a quick note. Same heuristic as the macOS Services menu “Send to SideBrain”.
• push_text (text, optional note_type): free-text note; with note_type='person' the structured 5-field person capture runs (name, role, company, contact, context) — result schema is bit-identical to the App Quick-Note with type selector “Person”.

Reply is JSON with slug, title and method/chars where applicable; when the trial has expired without a license, all four tools reply with code: license_required.

By default, the local HTTP server answers every process on the same Mac — convenient day-to-day, but on a machine with several user accounts every account reaches the Brain over localhost. In the settings (section “Local MCP server (HTTP)”) you can therefore enable a Bearer token protection: a click on “Generate new token” creates a random token that can be shown and copied. When the protection is active, every request — including the health check — requires the header Authorization: Bearer <Token>; without a token or with a wrong one, the server replies with 401 without running any MCP tool:

"mcpServers": {
  "sidebrain": {
    "url": "http://127.0.0.1:8765/mcp",
    "headers": { "Authorization": "Bearer <Token>" }
  }
}

Protection off (default) changes nothing about today's behavior — existing clients keep running without any adjustment. The stdio start command needs no token: it starts as a local child process without network access.

Mac as a Brain server on the network

By default, the local HTTP server binds exclusively to 127.0.0.1 — no other device can reach it. If you deliberately want to use a Mac as a small Brain server for a team (one machine hosts the knowledge, colleagues access it from the LAN), switch the reachability in the settings under “Local MCP server (HTTP)”: “All networks of this Mac” binds to 0.0.0.0, “Specific IP address” to a fixed address of this machine. Both options mandatorily require the Bearer token protection from above — it is enabled automatically when you switch; there is no network sharing without protection. The status line then shows the actually usable address for copying (with “All networks”, the Mac's LAN IP instead of 0.0.0.0) — colleagues enter it together with the token in their client, exactly as described above.

To be honest: the server only lives as long as SideBrain is open — when the app closes, the team Brain is no longer reachable either (no daemon, no autostart operation). On the first start with a network share, macOS asks once whether incoming connections for SideBrain are allowed (firewall dialog) — without confirmation the server stays unreachable for other devices. An invalid IP address, or one that does not exist on this Mac, is shown by the status line as a clear error instead of a silent failure. No TLS in this step — the share is intended for the local network, not the open Internet.

Using SideBrain in AI assistants

Step by step: your brain as a source of knowledge in Claude, ChatGPT, Codex and other tools - based on the MCP server, which runs locally as long as SideBrain is open.

Prerequisite for the MCP instructions below: SideBrain is running, the local MCP server is active (default; on/off, port and live status under Settings → "Local MCP server"). The addresses are available for copying on the overview (“MCP addresses” card). If you don't want an MCP setup (or also need a quick way), use the context chip.

Context chip ⌃⌥C

The fastest way, with no setup at all: once activated in Settings (section “Context chip”, default off), the shortcut ⌃⌥C (adjustable under "Key combination" - a change only takes effect after restarting SideBrain) opens a small panel with matching notes for the currently active window. SideBrain reads the title of the foreground window for this (macOS asks once for the automation permission under System Settings → Privacy & Security); without this permission, the topic field stays empty and shows a note - you then simply type the topic in yourself. The recognized (or typed) topic stays editable at any time. “Search” searches all connected brains in the network; hits appear with a brain chip and snippet in the order of the engine ranking - the display itself shows no numeric score. Clicking a note opens it in Brain Explorer; "Copy all" places the entire hit list on the clipboard as a Markdown block - ready to paste into Claude, ChatGPT, or any other chatbot. When the feature is enabled, the context chip also appears as an entry in the menu bar icon.

Privacy: the window title is never logged or saved; the search sends the topic exclusively as a query to your own brains. The context chip has no app-specific exclusion list - that's available with the Context agent.

MCP context tool

For external AI clients that connect via MCP (Claude, Codex, any MCP host): once activated in Settings (section “MCP context tool”, default off), the SideBrain MCP server additionally offers the tool context_for. The assistant calls it with a topic; SideBrain searches all connected brains in the network and returns the hit list directly as ready-made prompt context - a Markdown block plus a structured list per note (title, brain, slug, snippet). Here too: no numeric score, the order of the hits is the relevance. If a brain isn't reachable at the moment, the context says so honestly instead of simply finding nothing. The setting takes effect immediately for new MCP requests, with no restart needed. Anyone addressing the app via script instead of an assistant uses the same search, regardless of the toggle, via --context-for "Thema" (details in the MCP for developers section).

Context agent

The third building block runs entirely on its own, with nothing for you to trigger: once activated in Settings (section “Context agent”, default off), SideBrain then automatically watches the title of your active window (poll interval 1/3/5/10 seconds, adjustable) and, on a window change - after a brief settling period - automatically checks all connected brains for the new topic. If at least one matching note turns up, a silent notification without sound appears: "{n} notes on 'topic'" - if the context chip is also enabled, SideBrain adds the configured shortcut as plain text (e.g. "ctrl+alt+c") for details; without an enabled context chip, this addition is left out. An exclusion list (bundle IDs, pre-filled with common password managers) ensures sensitive apps are never inspected - SideBrain excludes itself automatically as well. The most recently captured context is stored locally in a cache file and, when the MCP context tool is enabled, is also available via the latest_context tool (fresh = younger than 60 seconds). Turning it on first shows a confirmation dialog with the privacy note below - the agent only activates if you agree; the toggle itself takes effect immediately, no restart needed.

Privacy (the confirmation dialog shown when turning it on says the same thing): SideBrain then continuously recognizes your active app and window title - locally only, never logged. The current topic is automatically sent to your own brains as a search query, just like with any other search; the last context is stored locally in the cache (deleted when the agent is turned off - this also happens retroactively if SideBrain was restarted in the meantime). Apps on the exclusion list are excluded. One more honest note: for the very first poll, macOS asks once for the automation permission (System Settings → Privacy & Security) - without it, the agent silently does nothing. Like any macOS notification, a triggered notification stays visible in the Notification Center, including the detected topic. There's no numeric score as a threshold - the notification appears from the first hit onward, consistent with the context chip and MCP context tool.

Claude Desktop & Cowork

The fastest way: One-click setup under Settings → Integrations → “Integrate into Claude Desktop” — SideBrain writes the entry into the Claude desktop configuration; then restart Claude Desktop. Alternatively manually in the claude_desktop_config.json:

"mcpServers": {
  "sidebrain": {
    "url": "http://127.0.0.1:8765/mcp"
  }
}

The SideBrain tools are then available in every conversation: “Search my brain for the municipal utility offer,” “Save this summary as a note,” or “What does my brain know about Anna Schmidt?” — Claude invokes Search, Think and Push himself. Claude also sees several Brains think_all (all brains in parallel, sources per brain) and per brain think_tool — “ask all my brains” works literally. Cowork agents use the same connection and can do research and Write results back into the brain.

Claude Code (Terminal)

One command registers SideBrain as an MCP server for coding sessions:

claude mcp add --transport http sidebrain http://127.0.0.1:8765/mcp

This allows Claude Code to question your brain while you work (project decisions, context to customers/systems) and store findings as notes. The skill also knows --think-all: a question to all stored brains in parallel, with brain assignment per source. The exportable one Skill (Settings → Integrations) also provides one SKILL.md, which explains agent setups how to use the tools.

ChatGPT

ChatGPT supports its own MCP connectors (Settings → Connectors, Developer Mode). Important: ChatGPT runs in the cloud and reaches 127.0.0.1 on your Mac not — the connector needs an endpoint that can be reached from the Internet:

• Team Brain: If your gbrain runs as a central endpoint (own server), enter its URL directly as a connector - the natural way for company setups.
• Local Brain: Only make it accessible via a tunnel you control (VPN/Tailscale or similar) - consciously consider whether you want this; without a tunnel, the local brain remains inaccessible to ChatGPT.

As of early 2026 — the providers' connector functions are constantly changing; Their current documentation is decisive.

Codex

There are those here too One-click setup (Settings → Integrations → “Integrate with Codex”) — it adds the SideBrain stdio command to the Codex configuration (~/.codex/config.toml) a. Codex sessions can then search and populate the Brain using the same tools as Claude.

Other MCP clients & own agents

Any tool that speaks MCP over Streamable HTTP (cursors, LM Studio, custom agent frameworks) connects to the local URL http://127.0.0.1:8765/mcp; Clients that start processes themselves use the stdio command from the overview. Read/write permissions follow the token scope of the respective brain - an assistant with read tokens can search and ask, but cannot change anything.

Import & Export

Markdown folder / Obsidian

Import an entire folder (e.g. Obsidian Vault) — each file goes through the normal pipeline, progress is shown live.

Notes app

Apple Notes (optionally a single folder) are exported locally via AppleScript and imported like a Vault. Requires automation approval once; All timeouts are hard-limited so that missing approval never freezes the app.

ZIP export

The entire brain as a ZIP of all Markdown notes — complete data sovereignty, at any time.

Response/digest export

Individual answers and the review can be exported as a Markdown file for downloads.

Maintenance & Diagnostics

diagnosis

Settings → Local Brain → “Diagnostics” carries out the health check of the brain and shows the health value including conspicuous points with fix hints. Read only.

Schema panel

Shows the active schema pack (types, relationship types), the type distribution of the own pages and the orphan check. Read only.

Course

Every push is logged (status, method, character) — with text search, status filter and detailed view; Entries can be deleted along with the Brain page.

Understandable errors

The most common error images are translated instead of displayed raw: Brain occupied, missing token rights, Brain not accessible, missing model access - each with the next sensible step.

Support package

Diagnostic export for error reports (configuration without secrets, version statuses).

Keyboard shortcuts

Release history

Every released version since the first milestone — newest first. Details about each version can be found in the app's changelog.

This documentation is updated with every feature release - new functions appear here in the appropriate chapter and in this history.