Documentation

Knowledge Sync & Brains

Knowledge Sync writes your BlackOps notes to a GitHub repository you own, and reads changes back. Brains compile a folder of those 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.

How it fits together

There are three layers. 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:

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.
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

pendingCreated, not compiled yet.

compilingBuilding the knowledge map.

compiledReady to use. Shows the note count and last-compiled time.

errorSomething 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. From any connected MCP client there are four tools:

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.

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.

Connect BlackOps to your AI client — required to use brains from an AI assistant.
Note Taxonomy — tag-based folder routing for synced notes.