Guide · Agent skill
How to use the Brain Operations agent skill (brain-ops)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The brain-ops skill is an instruction file for an AI agent that tells it to check a personal knowledge base called a brain before it answers questions or does research. It is built for GBrain, so it assumes you already have a GBrain installation with its gbrain CLI or MCP server and a running brain. After this guide you will know what the skill changes, how to install it, how to ask for lookups and saves in plain language, and what to review before letting it write to your knowledge base.
Brain Operationsgarrytan/gbrain · MIT Download the skill Quick start
- 1Install GBrain. Make sure a GBrain installation with its gbrain CLI or MCP server is available, and that you have a running brain, local or remote.
- 2Download and unzip the skill. Download the brain-ops ZIP from this page and unzip it so that SKILL.md sits inside the skill folder.
- 3Place the skill folder. Move the folder to ~/.claude/skills/ for personal use, or to the project's .claude/skills/ folder to limit it to one project.
- 4Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.
- 5Test a lookup. Run gbrain entity with a known name to confirm the CLI can read your brain before you rely on the agent.
- 6Ask for a brain check. Request a lookup in plain language, such as asking what the brain knows about a company before research.
- 7Review before saving. Make explicit save requests only, and check the source notes and back-links the agent writes.
What the brain-ops skill makes the agent do
An agent skill is a folder containing a SKILL.md file. When the skill is installed, the agent reads these instructions and follows them for matching tasks. The brain-ops skill covers the read and write cycle for a GBrain brain: look up what is already known before using outside sources, save facts you explicitly ask it to save, attribute those facts to a source, and link related pages together.
The skill's core rule is brain-first lookup. Before using any external API to research a person, company or topic, the agent checks the brain. Saved facts are written with inline [Source: ...] citations, and the user's direct statements are treated as the highest-authority data.
- Checks the brain before answering questions or doing research
- Saves facts only when you explicitly ask, with a source note
- Adds back-links from entity pages to pages that mention them
- Writes mainly to people/, companies/, deals/, concepts/ and meetings/
Install the brain-ops skill from the ZIP or the Claude apps
Download the brain-ops ZIP from this page and unzip it. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder instead.
If you use the Claude apps, you can upload the skill instead. Open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/
- Project install: the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills
Confirm your brain is reachable before you start
The skill only works if the agent can reach a running brain. It refers to the tools recall, search, query, get_page, put_page, add_link, add_timeline_entry, get_backlinks and sync_brain, so those must be available through the gbrain CLI or the MCP server. Without them the skill has nothing to read or write.
The skill's lookup sequence starts with the gbrain entity command for a known person, company or project. You can test that your CLI is working by running it against a name in your brain.
- Requires a GBrain installation with the gbrain CLI or MCP server
- Requires a running brain, local or remote
- Runs no scripts, but uses the network
gbrain entity "Jane Example"How to trigger the skill with natural requests
You do not need special syntax. The skill's trigger is any brain read, write, lookup or citation request, so phrase requests the way you would to a colleague. Ask the agent to check what the brain knows before it researches, or tell it explicitly to save something.
For saves, say clearly that you want the fact stored. Explicit save requests trigger the read-then-write loop. Automatic capture stays off until you opt in, and a chat-only instruction in a given turn suppresses writes for that turn.
- "Check the brain for what we know about Acme before you research pricing."
- "Save this to the brain: Jane Example moved to the Berlin office. Source: our call on this date."
- "What's in the brain about our open deals with Northwind?"
Save facts with sources and back-links
When you ask the agent to save a fact, the skill asks it to write the fact to the relevant page with a source note and to link related pages together. The skill treats an unlinked mention of a person or company that has a brain page as a broken brain, so it creates a back-link from that entity's page to the page that mentions it.
Over MCP, the skill prefers the memory verbs remember, recall, entity, synthesize and forget for single facts, and put_page, add_link and add_timeline_entry for page and graph writes. Fall back to the classic operations when the memory verbs are not available to the agent.
- remember saves one formed fact with provenance
- recall reads memory back within a token budget
- entity returns a card for a known name
- forget withdraws active memory, but history and backups may remain
Handle private information and credentials carefully
Visibility depends on how you connect. The source says trusted local CLI callers can recall and withdraw private facts, while every MCP caller, including stdio, currently has world-only fact recall and withdrawal. A request to remember does not authorise making real private information world-visible, so for private memory use a trusted local write and readback path when one is available.
If a result contains a value like <REDACTED:url_credentials>, the brain holds a credential-shaped value that it withheld from that response. A credential you ask the agent to remember is withheld from remote recall by design, so you can only see it as written by running gbrain recall on the brain host.
- Private facts saved over remote MCP may not be readable back or withdrawable through that path
- Do not widen visibility or request broader OAuth scopes just to make a test pass
- For an MCP connection test, use a harmless synthetic fixture with visibility set to world, then withdraw it afterwards
- Automatic capture stays off until you opt in, and reading the skill does not enable it
What people use it for
- Checking what the brain already knows about a contact or company before doing outside research
- Saving a single meeting outcome or decision to a people, company or meetings page with a source note
- Reviewing open deals or recent events for a named entity using the timeline and backlink checks
- Testing the memory verbs remember and recall over MCP with a harmless synthetic world-visible fixture
Frequently asked questions
How do I install the brain-ops skill?
Download the brain-ops ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder for one project. In the Claude apps you can instead upload it under Settings, Capabilities, Skills.
What do I need to run brain-ops?
You need a GBrain installation with its gbrain CLI or MCP server and a running brain, local or remote. The skill refers to tools such as recall, search, query, get_page, put_page and sync_brain, and without them it has nothing to read or write.
Is the brain-ops skill free?
The skill is published under the MIT licence. The source does not state any price for it, and it does not enable paid enrichment on its own.
Does brain-ops save everything automatically?
No. Automatic capture is off until the user opts in. The agent saves facts when you explicitly ask, and a chat-only instruction suppresses writes for that turn.
Why does the agent say it cannot read back a private fact?
According to the source, every MCP caller, including stdio, currently has world-only fact recall and withdrawal. Private facts saved over remote MCP may not be readable or withdrawable that way, so use a trusted local CLI path for private readback.
What should I do if a result shows REDACTED?
A value such as <REDACTED:url_credentials> means the brain holds a credential-shaped value and withheld it from that response. The stored page is unchanged, and the value is readable on the brain host with gbrain recall. The agent should not retry other operations to recover it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use brain-ops if you run GBrain and want your AI agent to check and write to that knowledge base in a consistent way with source notes and back-links. Pick something else if you do not have a GBrain brain, or if you do not want an agent writing to your knowledge base, since the skill's write behaviour needs review first.
Download the skill