Garry's Opinionated OpenClaw/Hermes Agent Brain
How to get data in
One command, local or hosted, synchronous receipt:
gbrain capture "the thought I want to remember"
gbrain capture --file ./notes/today.md
echo "from a pipe" | gbrain capture --stdin
SLUG=$(gbrain capture "..." --quiet)
Page writes return durable receipts. Replacements require the revision you read or explicit force; keep the request UUID when retrying. Accepted work can remain queued while its owner is unavailable, and uncertain publication has an explicit recovery state. Embedding completion is separate from canonical commitment. A source without a configured repository can hold DB-only pages, which need a database backup alongside withdrawal and receipt records. See concurrent writes and the persistence boundary. Default slug inbox/YYYY-MM-DD-<hash8> so captures cluster in a predictable triage location. On thin-client installs the verb routes through MCP to the server.
Say to your agent: "Remember this: ..." — "Save this thought to my brain" — "Capture this." And to fill an empty brain from your existing life: "Fill my brain" (the cold-start skill walks your email, calendar, contacts, and archives one consented step at a time).
Ambient memory writeback (opt-in, personal brains). Stop having to say "remember this": once enabled, your agents save durable facts you state in passing — preferences, decisions, commitments — with provenance, and transient facts (a cold, a trip) expire when saved with an explicit TTL. Off by default; on a personal brain gbrain asks you once at init/upgrade; company brains are never nudged. Say to your agent: "Turn on ambient memory writeback" — your agent runs gbrain config set memory.auto_writeback salient and gbrain bootstrap harness --yes. Full mechanics, privacy posture, and per-harness limitations: docs/guides/ambient-writeback.md.
Credentials you save stay in the brain, but retrieval withholds them. What
you capture or remember is stored as written. When a search, query or memory
read returns text containing a credential-shaped value (an API key, a password
assignment, a URL with a password, a private key), the value comes back as
<REDACTED:pattern>. A credential you ask the brain to remember is withheld
from remote recall by design: every MCP caller, including stdio MCP, and a
thin-client install count as remote. On the brain host, gbrain recall shows
remembered facts as written. Full page reads (get_page) are not redacted;
they follow page visibility. Details and the full list of what stays raw:
secret scan refusals and redaction.
For webhook ingestion (Zapier / IFTTT / Apple Shortcuts):
curl -X POST https://your-brain/ingest \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: text/markdown" \
-d "# a thought from a Shortcut"
For mobile capture, the inbox folder source picks up anything dropped into
~/.gbrain/inbox/ from iOS Shortcuts / AirDrop / Drafts / Finder.
Your Gmail, calendar, and contacts sync natively. gbrain google setup walks
bring-your-own OAuth end to end (your own free Google Cloud client — you own
the app and the tokens, which live only in a local credential vault), registers
a --kind google source, runs a bounded first sync, and ends with the
open-loop engine's killer output:
gbrain google setup # connect Gmail/Calendar/Contacts → first sync → first digest
gbrain waiting # who is waiting on you, what you promised, with receipts
gbrain google calendars # every calendar the account can read; pass an id to
# `sources add … --calendar-id <id>` to sync a secondary one
gbrain loops mute sender <email> # stop opening loops for a sender (or `thread <id>`)
gbrain loops unmute sender <email> # undo it — exact and forward-only
Say to your agent: "Who is waiting on me?" / "open loops" (routes to the google-loops skill, which also covers muting a sender — your agent runs gbrain loops mute sender <email>, and gbrain loops unmute sender <email> to undo it) — "list the calendars my google account can read" (your agent runs gbrain google calendars).
Setup + troubleshooting: docs/guides/google-connect.md.
How the open-loop engine decides who's waiting: docs/guides/open-loops.md.
Your other agents' histories import in one command. gbrain transcripts ingest
parses agent session logs (Claude Code, Codex, OpenClaw, Hermes, Grok Build) and extracted
consumer chat exports (ChatGPT / Claude.ai conversations.json) into readable
conversation pages with provenance back to the exact session file. Pattern-based redaction runs over message bodies, titles, speakers, and session
metadata before anything is written — vendor key prefixes, JWTs, cloud/API key
shapes, Bearer and Authorization: Basic headers, database and http(s)
URLs carrying a password, private keys (also when an excerpt cut off the
BEGIN or END line), high-entropy KEY=/TOKEN=/password=
assignments (quoted values may contain punctuation), and typed passwords
after a credential label (see Credential redaction) become <REDACTED:…> placeholders (preview with
--dry-run; no pattern set is complete, so if a secret still lands see
"If a secret reached the brain":
rotate it, then gbrain delete <slug> --purge). Embedding is off by default
for bulk backfills, and re-runs are free — unchanged sessions skip on content hash:
gbrain transcripts ingest # discover importable session logs
gbrain transcripts ingest --all # import everything discovered
gbrain transcripts ingest ~/Downloads/conversations.json # consumer export (unzip first)
gbrain transcripts ingest --max-bytes 4gb <store> # oversized store; omit to keep per-format caps
gbrain transcripts status # found vs imported, per harness
For one redacted page per conversation per local day plus a daily index (off until gbrain transcripts archive on), see the conversation archive.
Say to your agent: "Import my conversations from my chatgpt export at ~/Downloads/conversations.json" — "Archive my session transcripts" — and later, "When did I first discuss agent memory?" (the archive answers origin questions with dated quotes).
Codex sessions imported before gbrain read codex 0.153+ rollouts lost their
user turns (#5163): the pages hold the assistant side only, and --since last
never re-reads them. gbrain transcripts recover codex lists those sessions,
re-reads the rollouts still on disk (~/.codex/sessions and the archived
store, or the rollouts you name) and says which it can restore and which it
cannot because the rollout is gone. --apply re-imports the recoverable ones
in place; a rerun finds nothing to do. It extracts no facts and leaves the
watermark alone; for facts from a restored session, run
gbrain transcripts ingest <rollout> --facts --max-cost-usd <n>.
Say to your agent: "Restore the codex sessions that lost my side of the conversation" (your agent runs the preview, shows you the counts, and applies after you agree).
Credential redaction
Transcript pages also redact a password typed after a credential label,
even when it is short and low-entropy (labeled_credential). Two label
forms are recognized, with bare, quoted or backticked values:
- a single label,
password,passwd,passcode,passphraseorpwd(also behind a prefix such asDB_and as a JSON key), followed by:,=or the full-width:—password: hunter2,**Password:** …,{"password": "…"}; - a pair label,
login,log-in,credentials,creds,user/passorusername/password, followed by:,=,:,-or nothing, thenuser / passoruser:pass—login alice / hunter2,creds: alice:hunter2. Only the password half is redacted. A pair whose password starts the next line is redacted too; - a command-line flag with its value after a space,
--password hunter2,--pass "two words"(--password-fileand other suffixed flags are not labels); - an environment name with more after the label,
PASSWORD_DB=…,FOO_PASSWORD_BAR=…, unless the suffix names a setting (_FILE,_PATH,_MIN_LENGTH,_HINT,_POLICYand similar); - a single label that ends its line, with the value alone on the next line
(
password:thenhunter2); - Markdown table cells: every cell under a column headed
Password,pwd,DB passwordand the like, and the value in a| password | … |row, including rows without outer pipes, escaped\|pipes and tables with several credential columns; - a
.netrcentry, on one line (machine host login alice password …) or over several (machine,loginandpasswordeach on its own line); - a key or token label that ends its line (
here is my API key:,ACCESS_TOKEN=), with one value of 12+ characters holding a letter and a digit alone on the next line; - a label that ends one message, with the value alone on the first line of
the next message (
password:, then the password as its own message).
Cookie values are redacted too (cookie_header): after a Cookie: or
Set-Cookie: header (raw headers, curl -H, a copy-as-fetch JSON blob) and
after -b/--cookie in a curl command, including on a continued line
of a multi-line command (what Chrome's "Copy as cURL" produces), every
value of 8+ characters is replaced, quoted values inside escaped JSON
(sid=\"…\") too, and the cookie names and Set-Cookie attributes
stay. These transcript-only rules never run in the sources push gate or
the compiled-context scan.
To keep prose and code intact, a value is never redacted when it is a
placeholder (<…>, ${…}, $VAR), a mask (****), a URL, a path, a
function call, a dotted reference (req.body.password), a code identifier
(hashedPassword), or one of the stoplisted words (n/a, none, string,
required, changed, reset, flow, email, await and similar; the
list is LABELED_STOPLIST in src/core/secret-scan-labeled.ts). A pair's
password must also be 4+ characters with a letter and a digit or symbol, so
login: Google/GitHub SSO and credentials: docs/auth.md stay. Known
misses: an unquoted multi-word passphrase, a label with no delimiter
(the password is …), a short flag joined to its value (mysql -phunter2),
and a meeting link's ?pwd= passcode. A redacted
value of 8+ characters that is not a stoplisted word is also scrubbed where
the session repeats it bare.
Pages imported before this detector (or a later widening of it) shipped are
not rewritten automatically, so run the audit again after upgrading. The audit
finds every shape above except a value sent as its own message: a stored page
no longer marks where one message ends. gbrain transcripts audit-secrets --json (read-only; all
sources, or one with --source-id) lists the conversation pages that still
carry a credential: slug, source, hit count per pattern and line numbers,
never the text. The doctor check transcript_secret_exposure reads the
audit's cached summary (it never scans pages itself) and says when no audit
has run or what the last one found and how long ago. Review, edit and
removal are separate steps: gbrain get <slug>, then gbrain put <slug> < edited.md to remove the credential, or gbrain delete <slug> --purge after
asking the user. Rotate any real credential that reached a page (see
"If a secret reached the brain"),
then re-run the audit.
Say to your agent: "Check my imported transcripts for passwords" (your agent runs the audit, lists the pages by slug and asks before changing any).
Or connect the account and skip the manual export entirely. gbrain connectors
syncs your ChatGPT and Claude conversation history live, using your own browser
session cookie — incrementally (a durable per-provider watermark, plus a
trailing-window gap-heal), through the same redaction + idempotency pipeline, and
optionally on a schedule. Credentials stay on your machine (~/.gbrain/connectors/*.json,
0600) and are sent only to the provider's own host:
gbrain connectors auth chatgpt --cookie - # paste the Cookie header (stdin keeps it out of argv)
gbrain connectors sync chatgpt --dry-run # preview, then --limit 5, then --full
gbrain config set connectors.chatgpt.auto_sync true # opt-in daily auto-sync (+ gbrain autopilot --install)
Say to your agent: "Connect my chatgpt account and pull my whole history into the brain" — "Connect my claude account" — "Keep my conversations synced automatically." Your agent walks you through the cookie capture, runs the dry-run → sample → full sequence, and sets up the schedule if you opt in.
Full contract, automation lanes, and the Cloudflare caveat: docs/guides/chat-connectors.md.
(Not to be confused with the inbound "Connectors" above — those add gbrain
as an MCP connector inside ChatGPT/Claude/Perplexity so those assistants can
search your brain. gbrain connectors goes the other way: it pulls your
conversation history from those accounts into the brain.)
Third-party skillpacks can ship custom ingestion sources (Granola, Linear,
voice, OCR) against the versioned IngestionSource contract at
gbrain/ingestion. See docs/skillpack-anatomy.md.