Knowledge Sync & Brains

Knowledge Sync writes your BlackOps notes to a GitHub repository you own, and reads changes back. Brains compile your notes into a structured knowledge map your AI can use as context. Together they keep one source of truth for everything you know, in plain markdown you control.

Brains work with or without GitHub

A brain does not require a repository connection. By default, a brain's source notes live in BlackOps directly: create the brain, add notes to it, and it compiles automatically. Nothing to install, nothing to configure.

Connecting a GitHub repository is an upgrade, not a prerequisite. A vault-backed brain reads its source notes from a folder in a repo you own (an Obsidian vault works well), so you can edit notes in your own tools and keep everything in plain markdown files under your control. The rest of this page covers that setup.

How it fits together

There are three layers to a vault-backed setup. You set them up once, in order.

1. A connected repository: You install the BlackOps GitHub App on a repo you own (an Obsidian vault works well). This is where your notes live as markdown files.
2. Repo targets: A repo target is a named folder in that repository where notes are written (for example /notes/ideas). You can have several.
3. Brains: A brain points at a folder and compiles every note inside it into one navigable knowledge map. That map is what your AI reads for deep, structured context.

Step 1: Connect your repository

Go to Settings → Connect Repository. There are two steps on that page:

1. Connect GitHub. Click Connect GitHub and install the BlackOps GitHub App on the account or organization that owns your repository. You choose which repositories it can see.
2. Select knowledge repositories. Tick Use as knowledge repo for each repo you want BlackOps to sync with, then Finish Repository Setup. You can optionally let BlackOps auto-create a few starter folders (Ideas, Daily, Work Initiatives).

The GitHub App connection is yours. BlackOps only touches the repositories you grant, and only the folders you point it at.

Step 2: Choose where notes land

A repo target is a folder where notes get written. Manage them under Settings → Repo Targets. For each target you set:

• Name: a label like "Ideas" or "Daily".
• Repository and Branch: where to write (the branch defaults to the repo default).
• Path: the folder inside the repo, for example /notes/ideas.

You do not have to choose a folder by hand every time. With Note Taxonomy rules, a note's tags decide which folder it routes to automatically.

How sync works (both directions)

BlackOps to GitHub

When a note is promoted to a target (from the app or an AI client), it is written to the repo as a markdown file with a hidden blackops_id in its frontmatter.

GitHub to BlackOps

Edit a file in the repo and BlackOps picks up the change within seconds (a GitHub webhook). The matching note updates in place.

That blackops_id is what keeps the link stable. Move or rename a file in the repo and it stays tied to the same note, so the two sides never drift apart.

Step 3: Build a brain

Open Brain and choose New Brain. You set:

• Name: for example Strategy, Research, or Product.
• Vault Target: which connected repo folder it reads from.
• Source Folder Path: a subfolder to scope the brain, or leave it empty to use the whole target. Subfolders are included recursively.

What compiling produces

A compile reads every note in the folder and builds a single knowledge map: a manifest of every note with its title, summary, and id, plus a folder tree and key themes. That map is small enough for an AI to hold in context and use to pull the full text of any note on demand. Open it any time with View Compiled Note.

Statuses you will see

• pending: Created, not compiled yet.
• compiling: Building the knowledge map.
• compiled: Ready to use. Shows the note count and last-compiled time.
• error: Something went wrong. The reason is shown on the card.

When it recompiles

• Automatically, whenever a note in the brain's source folder changes in the repo. Compiles are incremental: only the notes that actually changed are re-read, so a single edit stays fast even in a large brain.
• On demand, with the Compile button on the brain card.

Using a brain

Once a brain is compiled, your AI can use it as deep context. These are the tools you will reach for most from any connected MCP client:

Tool	What it does
list_brains	See your brains, their status, and note counts.
get_brain	Read the knowledge map, then pull any note's full text by id.
create_brain	Create a new brain over a vault folder.
update_brain	Add a note to a brain's folder. It recompiles on the next sync.
open_brain_task	Record something the brain is waiting on, and start reminding about it.
close_brain_task	Mark that ask resolved and stop the reminders.

When a brain is waiting on you

A brain is often only half useful because something is missing — photos that have not been taken, an answer only one person has, a document nobody uploaded. The brain knows it is blocked, but until you open the next session and the subject happens to come up, nothing asks you for it. A brain can sit that way for months.

Open a task against the brain and the ask becomes durable. It appears at the top of the brain when you next work with it, in the brain's compiled note, and in a daily reminder email sorted by what is due first.

• Addressed to you, tasks go out in one daily digest — never one email per task, and nothing at all on a day with nothing outstanding.
• Addressed to someone the brain is shared with, the reminder is held back first. You get a preview of exactly what is queued and to whom, with time to cancel it, before anything reaches them. They answer by replying to the email; no account needed.
• Due dates are optional. Set one and reminders tighten as it approaches and say how late something is once it passes. Leave it off and the reminders quietly back off as the task ages, rather than nagging at the same volume forever.

You control two things about the rhythm, and they are separate on purpose:

• When the digest arrives is yours, not the task's — one delivery time for everything, defaulting to 9am. Giving each task its own hour would turn one email into a stream, which is the thing the digest exists to prevent.
• How often a task repeats is the task's. Open it with a phrase like "remind me Friday" or "once a week" and it appears in the digest on those days only. Say nothing and it backs off on its own as it ages.

Closing a task removes it from the digest, the note, and any reminder still queued for it.

See Brain Task Reminders for the full behaviour, including how a reply is judged before it closes anything.

Good practices

• Scope each brain to a folder of related notes. A focused brain produces a sharper, more useful knowledge map than one giant folder of everything.
• Let the blackops_id stay in frontmatter. It is how files and notes stay linked across renames and moves.
• Use tags plus Note Taxonomy rules to route notes to the right folder instead of moving files by hand.

Sync runs against your own GitHub connection, which has a limit of about 5,000 requests per hour. Normal note-taking and editing stay far below it. A very large one-time import can approach the limit and briefly slow down. Compiles are incremental and never loop, so day-to-day use is well within budget.

Troubleshooting

A brain is stuck on "error"

The reason is shown on the brain card. Confirm the GitHub connection is still active under Settings, then press Compile to retry.

An edit in the repo did not show up

Changes arrive by webhook within seconds. If a file is not linking, check that it still has its blackops_id frontmatter and that it sits inside a connected repo target's path.

A note went to the wrong folder

Folder placement follows your Note Taxonomy rules and the note's tags. Adjust the rule or the tags and re-promote.

Related

• Connect BlackOps to your AI client: required to use brains from an AI assistant.
• Note Taxonomy: tag-based folder routing for synced notes.
• Brain Task Reminders: what to do when a brain is waiting on something before it can be useful.