How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/garrytan/gbrain --skill captureBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
capture — the single ingestion entrypoint
When the user wants to save a thought, an article snippet, a transcript fragment, or any text into their brain, run gbrain capture. Don't reach for gbrain put or commit-then-sync — capture is the front door and it handles both local and thin-client installs the same way.
Contract
- Input: the content to save (inline arg,
--file PATH, or--stdin). - Output: a page in the brain DB AND a markdown file on disk under
<sync.repo_path>/<slug>.md. Receipt printed to stdout.
- Side effect: the page becomes immediately queryable via
gbrain query,
gbrain search, or any MCP-bound agent.
- Idempotency: same content → same
inbox/YYYY-MM-DD-<hash8>slug. The
daemon's 24h content-hash dedup catches re-captures.
- Trust: all captures via this skill are local-CLI trust (
remote: false).
Untrusted webhook ingestion goes through POST /ingest, not this verb.
When to invoke
- "Capture this thought" / "save this" / "drop this into my brain" / "remember this"
- The user pastes content and asks to keep it
- After a meeting summary, a research note, or any synthesis that should land as a brain page
What it does
gbrain capture resolves to a put_page call (local) or a remote MCP call (thin-client). Either way the page lands in the DB AND on disk in one move via the v0.38 write-through plumbing. The default slug is inbox/YYYY-MM-DD-<hash8> so captures cluster in a predictable triage location.
How to use
gbrain capture "the thought I want to remember"
gbrain capture --file ./notes/today.md
echo "from a pipe" | gbrain capture --stdin
gbrain capture "..." --slug daily/2026-05-21
gbrain capture "..." --type idea --source voice-whisper
gbrain capture "..." --quiet # script-friendly: prints just the slug
gbrain capture "..." --json # structured output for agentsDefaults
- Slug:
inbox/YYYY-MM-DD-<hash8>(stable for same content; the daemon's 24h dedup catches re-captures). - Type:
note(override with--type ideaetc.). - Frontmatter stamps:
captured_via: capture-cli,captured_at: <ISO>. - Title: first non-empty line of the body, capped at 80 chars (truncation appends
…).
Output Format
Default prints a 5-line receipt:
captured:
slug: inbox/2026-05-21-abcdef12
status: created_or_updated
content_hash: f3a7b9c0d1e2f3a4…
file: /Users/you/brain/inbox/2026-05-21-abcdef12.md
captured_at: 2026-05-21T04:15:00.000Z--quiet prints only the slug (use for SLUG=$(gbrain capture "..." --quiet)). --json prints structured output for downstream tools.
When it fails
Follow the agent operator protocol for any gbrain error code, exit code, [AGENT] block or notice block. Specific to this skill:
- Exit 10 (
write_pending): the thought was accepted and may still commit. Tell the user it is saved and pending, and pollgbrain write-request <request_id>; never capture it a second time. - A secret-scan or slug-fence refusal: nothing was saved. Tell the user what was refused; do not edit the content to sneak past the scanner.
source_binding_requiredorinsufficient_scopeover MCP: this connection cannot write the target source; tell the user which source needs a grant from the brain host's operator.
Anti-Patterns
- Don't reach for `gbrain put`. That's the old per-page primitive that
doesn't know about default slug generation, content-type heuristics, or the receipt block. capture is the human-facing wrapper.
- Don't try to bulk-import dozens of files by looping over `gbrain capture`.
That's what gbrain sync (or gbrain import) is for. Capture is for single thoughts, single notes, single transcripts.
- Don't pre-format the content yourself with frontmatter if you don't need to.
Capture wraps plain prose in sensible frontmatter (type + title + capturedvia + capturedat). The body becomes # Title\n\n<your prose>. Pass --file PATH if you already have a fully-formatted markdown file.
- Don't pass secrets as inline content. Inline args land in shell
history. Use --file or --stdin instead.
When NOT to use this skill
- Bulk ingestion of many files →
skills/media-ingest/SKILL.mdorgbrain syncinstead - Article/link with author + publication metadata →
skills/idea-ingest/SKILL.md(it knows to build the people page) - Meeting transcripts →
skills/meeting-ingestion/SKILL.md(attendee enrichment)
This skill is for the simple "I have a thought, save it" case. Specialized ingestion paths handle their own slugging + cross-referencing.