Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
40.6 KB
Raw Blame

What belongs in shared memory

Say to your agent: "Remember my preference for short recommendations, but keep this session's setup and credentials out of shared memory."

GBrain can carry durable facts and preferences between agents that have access to the same brain and source. It does not replace the harness's identity, instructions, configuration, or permission controls.

Durable knowledge versus runtime state

Save explicit requests to remember with provenance: preferences, corrections, decisions, commitments, and facts the user wants available later. For example, "I want meeting briefs in three bullets" is useful shared knowledge. Recall it before the next brief, and verify corrections against the stored record.

Keep current task progress, temporary tool output, local paths, enabled plugins, MCP connection settings, credentials, and harness activation state in the appropriate local configuration or session state. A remembered preference does not install a skill, change an authorization grant, or override higher-priority instructions. Do not put secrets in memory pages. A durable decision about a setup can be recorded without copying its credentials or assuming that setup is active in another harness.

Automatic capture is opt-in, except the conversation archive: on a personal brain it is on by default and keeps one redacted page per conversation per day from the harness sessions on this machine (nothing leaves a keyless machine; gbrain transcripts archive off stops it, and a shared brain is only offered it). It extracts no facts. Installing the harness hooks opts into the compaction and SessionEnd capture lanes; gbrain config set memory.auto_writeback off stops every capture lane, and gbrain bootstrap harness --remove stops the hooks from banking session text at all (see ambient writeback). Time-limited facts need an explicit TTL; ordinary saved facts do not expire just because they describe a temporary situation.

In a shared chat, the owner's own questions are answered at the owner's full scope, with every item marked by whether the people in the room could have read it (rooms). The marks are for the agent's judgment about what to say; they do not keep the raw results out of a group transcript, so the harness must. forget withdraws a fact from active recall, not from all source material, history, or private backups. To remove the text itself from live stores, the owner runs a purge on the brain host. See ambient writeback.

What a write costs

Saving text or a fact never waits on a generative model: a write is acknowledged and keyword-queryable without one. Embeddings are the configured feature (remember embeds before saving to detect near-duplicates; pages embed just after the save, and a page over 1 MiB embeds later through the stale sweep: see large pages). With default settings each saved page of an extraction-eligible type (note, meeting, email and similar) also gets one facts extraction call after it is saved; it runs as a queued job, is attributed to the write that caused it, and stops with gbrain config set facts.extraction_enabled false. gbrain config set facts.page_write_notability_filter medium-and-up keeps only high- and medium-notability facts from page writes (high-only keeps the high tier, as sync does; all, the default, keeps every tier). Image OCR, when turned on (embedding_image_ocr), runs before the save. Set GBRAIN_AI_CALL_LOG=<path> to record every model call a process makes (kind, model, tokens, duration, and the write request, job or cycle phase it served; no prompt or response text).

Page writes and the graph are separate outcomes

Write path Graph behavior
Trusted local put_page / capture Extracts supported page references without an LLM when auto-linking is enabled.
MCP put_page / capture / edit_page, including stdio Saves body references as text; no inline graph extraction. The receipt reports auto_links.skipped: remote.
Post-commit links effect of an MCP page write Adds untyped mentions edges (link_source: mcp-remote-mention) for the body's markdown links, [[wikilinks]] and page-path mentions whose target already exists in the same source, is not deleted, is visible to the writer and is inside its slug grant. No typed, frontmatter, timeline or cross-source edges and no new pages. The receipt reports auto_links.mention_links: queued; get_write_request lists the effect with added/removed counts, plus invalid_targets (reason invalid_slug) for any target that is not a valid slug ([[../x]], a backslash, an encoded separator): those are skipped and the page's other edges still land (#7008). A remote append_page to the page body queues the same effect over the appended text only: it adds edges for what that text mentions and never removes one (#7122). gbrain config set mcp.remote_auto_links off (or auto_link off) disables it.
Stdio gbrain serve Has bounded, best-effort startup and idle maintenance sweeps, unless disabled. This is eventual maintenance, not a guarantee that a remote write immediately has edges.
gbrain serve --http Does not self-sweep. The host must run maintenance explicitly.

For an HTTP brain, ask the host operator to run gbrain sweep --once (it can delegate to the live server over local IPC), or explicitly extract links and timeline entries for the intended source. Use an authorized add_link operation for an edge needed immediately, then verify it with get_links or a graph query. Check the write receipt and the graph separately; a saved page is not proof of graph reconciliation. See graph setup.

A timeline entry has no update or remove operation: add_timeline_entry returns the rendered bullet, and editing or deleting that bullet in the page's Timeline section through edit_page (with expected_revision) refreshes or removes its row, because the page is the system of record for timeline rows.

Large pages

Say to your agent: "Import this long conversation export as one page and make it searchable. Tell me what embedding it will cost before you spend anything." The agent imports the file on the brain host with gbrain import <file>, checks that keyword search finds it, and asks before running gbrain embed.

Say to your agent: "I upgraded gbrain. Which of my big pages couldn't be found before, and what would it cost to embed them now?" The agent runs gbrain reindex --oversized --dry-run --json and gbrain doctor --json, then asks before gbrain embed --held --source <id> --max-usd <N>, one source at a time.

A page stays one page whatever its size: one slug, one title, one set of links. Size no longer decides whether search can find it. Every Markdown page up to the page ceiling is stored, chunked and keyword-indexed when it is written: 256 MiB on Postgres and 128 MiB on PGLite (pages.max_bytes lowers it), or 24 MiB (25,165,824 bytes) while segmented storage is off. Don't split a page by hand to make it searchable.

Page body Keyword search Meaning (vector) search
Up to 1 MiB right after the write right after the write
Over 1 MiB, up to the page ceiling (a large page) right after the write after the write commits, when the stale sweep embeds it (gbrain embed --stale, sync's embed pass, autopilot)
Over the page ceiling refused with file_too_large; nothing is stored —

Code files keep a lower limit; see limits per entry point.

A large page commits without vectors, so a big write never waits on the embedding provider. It also differs from a small page in three ways. Its chunks use the free title context tier, never a per-chunk model synopsis. Before it is embedded, the junk check samples its head, middle and tail instead of reading the whole body. And gbrain keeps a bounded number of version snapshots of it, so a page appended to every day doesn't store its whole body again in history on every write.

An operator who set a lower content_sanity.bytes_block (the GBRAIN_PAGE_BLOCK_BYTES env var, the config file, or the database config) stops embedding above that value: such a page is stored with an embed_skip marker and gets no vectors, but it is still chunked, so keyword search finds it. The same holds for any page with an embed_skip marker. The default is the page ceiling, so nothing is skipped for size unless someone lowered it.

What a write says about size. put_page, remember and sync receipts carry the same field for a large or embed_skip page, so the writer learns on the write itself, without reading the sync log. size_state on a page receipt (and on remember when it appended to such a page) is { embedding, reason, bytes }; a sync receipt has size_states: { total, pages } with the first 50 pages, each with its slug, path (a managed sync) and the same fields, and the sync output prints a line per page. An ordinary page carries no field.

embedding reason What happened
deferred large_page Over 1 MiB: committed with chunks and no vectors; the embedding sweep embeds it after the commit, under embed.max_usd_per_page.
partial spend_cap The per-page cap stopped embedding; the rest stays keyword-only.
held e.g. upgrade_backfill Embedding waits for the user's approval of the previewed cost (gbrain embed --held --dry-run, then one source at a time).
skipped oversized Over the operator's bytes_block: chunked and keyword-searchable, never embedded.
skipped operator_marker Another embed_skip marker: chunked and keyword-searchable, never embedded.

A body over the page ceiling, or put_page content over 24 MiB, has no receipt: the write is refused as request_too_large.

Adding to or uploading a large page

Don't send a growing page back whole to add a line. append_page (CLI gbrain append <slug>, text from --file or stdin) adds text to the end of a page in time proportional to the text. It takes a request_id, so a retry never appends twice, and expected_tail_sha256 refuses tail_changed when another writer appended first. edit_page on a page stored in segments rewrites only the segments a body-text match touches (an edit that reaches the header or the timeline marker prepares the whole body instead); within restricts the match to a range a window read returned.

A page bigger than one request (see the limits below) goes in an upload session: begin_page_upload, then upload_page_part from part 0, then commit_page_upload, which returns put_page's receipt. get_page_upload resumes after a lost reply and abort_page_upload discards the session. On a remote brain, gbrain put --file, gbrain capture --file and gbrain append switch to a session when the request is over the connection's limit. A session belongs to the connection, source and page that began it, its staged bytes count against the persistence.limits upload quotas, and an idle session expires.

Reading part of a page

Say to your agent: "Show me just the Next steps section of the acme-example meeting page." The agent runs gbrain get <slug> --section "Next steps" (MCP: get_page with section) instead of reading the whole page.

Say to your agent: "Where does the widget plan page mention pricing?" The agent runs gbrain get <slug> --grep pricing --context 1 (MCP: get_page with grep and context).

--section returns the first section whose heading matches (case does not matter), down to the next heading of the same or a higher level, with the headings above it. If no heading matches, the error lists the page's headings (up to 20). --grep returns each paragraph with a line containing the text (plain text, not a pattern) plus --context paragraphs either side (default 1, at most 5), with line numbers and total_matches. It returns at most 50 matching paragraphs and 100,000 characters, and says truncated when it stops early. The line numbers are the ones a --body window read takes: gbrain get <slug> --body window --lines 100-140 reads lines 100 to 140 (--lines 100 reads one line, --bytes 0-999 the first 1,000 bytes). Both read the same text a window does, so they show a remote caller nothing a window would not, and they work on segmented pages one segment at a time. Every get_page response carries chars, the characters of page text it returned.

Segmented page storage

A page over 1 MiB is stored as segments of about 256 KiB instead of one text column (pages.segmented_storage, on by default). Reading a window, an outline or a chunk's context costs the size of the window, not the page, and a rewrite re-indexes only the segments that changed. Pages at or under 1 MiB are stored exactly as before; a segmented page goes back to one column when a write leaves it at or under 512 KiB.

A body that arrives as one string (put_page, put_pages, capture content and gbrain put stdin) stays limited to 24 MiB per call. A larger page comes in by gbrain import or gbrain sync of its file. On a source backed by files that is only the file at its own place in the checkout, which gbrain never rewrites; a database-only source takes it by gbrain import.

The switch stays off while an older gbrain writes to the same brain: a gbrain older than the release that turned it on by default (v0.60.290.0 included), or one that stamps no version, that in the last 7 days admitted or published a managed write, logged an import, sync or connector run, or ran a resident process keeps new pages inline, even when the setting is on. gbrain doctor check segmented_storage shows the configured and effective value and names each blocking host by UUID. Run gbrain upgrade there; the hold clears 7 days after that writer's last write. An older binary's single-page write on a brain without managed persistence (a classic brain shared by several hosts) is not detected: upgrade every host that writes to such a brain, or run gbrain config set pages.segmented_storage off until they are upgraded.

When a segmented write is searchable. The receipt of a write that stores a page in segments says searchable. A new page up to 4 MiB, and every rewrite of a segmented page, is searchable when it commits (searchable: true). A larger new page commits first and builds its chunks and keyword index right after, about 10 seconds for 20 MB: its receipt says searchable: "pending", with searchable_retry_after_ms and a searchable_fix that reads the receipt again (get_write_request, gbrain write-request -- <id>). Read it at that interval until it says searchable: true; search finds the page from then on. Until then, search does not return the page. If it still says "pending" after a minute, no running gbrain process is building it (a brain with no resident writer, or a build that died): gbrain projections drain, the fix's fallback, builds it now, and doctor text_projection_readiness names how many such pages wait. A quarantined page says searchable: false. A managed gbrain import or gbrain sync of such a page replies the same way, when the write commits: its result says searchable: "pending" and projection: "pending" with the request_id to read again, searchable_retry_after_ms and searchable_fix, and the build does not hold up the source's next write. A new page up to 4 MiB still imports searchable (searchable: true).

Deleting and restoring a segmented page on a source backed by files works up to the page ceiling. A restore reserves room for its file twice (the staging file and the file) in the worktree recovery budget, so with the switch on persistence.limits.worktree_recovery_bytes defaults to twice pages.max_bytes plus 2 MiB, never less than 256 MiB (514 MiB on Postgres and 258 MiB on PGLite at the default ceilings). A value you set is kept; a page that does not fit it is refused with request_too_large before anything is touched. A restored page is searchable when the restore commits, or, when its chunks were never built, right after it (gbrain projections drain builds it if that build dies).

Withdrawals rewrite a segmented page's file. forget, forget_fact and purge_fact on a page stored in segments, on a source backed by files, rewrite its canonical file as they rewrite an inline page's: the file shows the row forgotten, or loses the purged row, and holds the bytes gbrain export writes for the page. The file is streamed from the segments into its staging file, one segment at a time, and never held whole. forget and forget_fact publish the struck file in their own write, before the withdrawal commits; purge_fact's mirror writes it afterwards and its Git effect commits it. The mirror's recovery record names that staging file by path and SHA-256 instead of holding the file, so the mirror reserves the file once in the recovery budget. A mirror interrupted before, during or after writing the staging file finishes on the writer's next pass: a staging file a crash cut short is discarded and written again.

What doctor does not read on a segmented page. Some doctor checks read a page's whole body as one string, and a page stored in segments has none. Those checks say how many such pages they passed by: oversized_pages, scraper_junk_pages, markdown_body_completeness, link_resolution_opportunity, fence_integrity, core_memory and extract_health (its facts-backlog overlay) carry skipped_segmented: N in gbrain doctor --json and end their message with skipped (segmented): N. gbrain repair frontmatter reports the same count (residual skipped_segmented and a warning) for the stored bodies it does not check; it still checks their files. An ok from such a check covers only the pages it read. The field is absent when no page is stored in segments. Core memory reads a core page stored in segments back whole up to 24 MiB, as it reads an inline page, so core_memory counts only the core pages over 24 MiB, which core leaves out of every session and of its budget. A frontmatter re-import of a page stored in segments works the same way up to 24 MiB; over it the file is listed needs_review with page_body_segmented and nothing is written.

While the switch is off (gbrain config set pages.segmented_storage off, or held by an older writer), new pages are stored inline up to 24 MiB as before. Pages already stored in segments stay readable and exportable; a write that would leave one over 24 MiB is refused until the switch is on again.

Limits per entry point

The page ceiling applies everywhere, but some transports carry less. When one of them refuses a page under 24 MiB, send the page by file instead: nothing is wrong with the page.

Entry point Limit What to do above it today
Markdown import and sync (gbrain import, gbrain sync, the managed sync blob read) the page ceiling: 256 MiB on Postgres, 128 MiB on PGLite (24 MiB while segmented storage is off); above 24 MiB on a source backed by files, only from the file's own place in the checkout —
CLI stdin (gbrain put, gbrain capture --stdin) 24 MiB (was 5 MB) gbrain import the file
MCP stdio (local agents, gbrain serve) 64 MiB per JSON-RPC message (the MCP SDK default of 10 MiB is raised), so a JSON-escaped page at the ceiling fits —
MCP over HTTP (gbrain serve --http) 4 MiB request body (the MCP SDK default; GBRAIN_HTTP_MAX_BODY_BYTES overrides it) an upload session, or sync or the CLI on the brain host
Legacy HTTP transport 1 MiB (GBRAIN_HTTP_MAX_BODY_BYTES) the same
put_pages batch 8 MiB per batch send large pages one per put_page, or by file
Persistence journal 64 MiB of outstanding JSON-escaped write intent per principal (was 32 MiB), 256 MiB per brain nothing: a second large write waits for the first
Local persistence socket (IPC) 32 MiB per frame, JSON-escaped nothing for ordinary text; only a pathological page (mostly quotes or backslashes) reaches it below the ceiling
Pre-push secret scan 512 MiB per staged file: up to 25 MiB a file is scanned whole, above it in bounded windows streamed from git; gbrain still never writes a canonical file over 25 MiB split the file, or git rm --cached it
GitHub warns at 50 MB, rejects at 100 MB —
Export streams a page stored in segments, up to the page ceiling; aborts on an inline page whose payload is over 32 MiB, which the 24 MiB ceiling makes unreachable —
Company-brain inspection 5 MB per file unchanged
Transcript ingest input (Claude Code .jsonl) 10 MiB by default, 50 MiB hard cap unchanged
Code files 5 MB unchanged

Reading a large page. Large reads come back in windows, not as one response, because agent transports and harness result caps can't carry tens of megabytes. The get_page reference describes how to read the next window.

Cost. Chunking and keyword indexing run locally and cost nothing. Embedding a large page costs about $0.15 per 10 MB at the default embedding model, so a 24 MiB page costs about $0.40 and one at the 256 MiB ceiling about $4. Each page has a paid spend cap, embed.max_usd_per_page (default $2), covering its embedding at every paid entry point (the stale sweep, gbrain embed, the post-write embedding job). A large page uses the free title context tier, never paid per-chunk synopses; conversation facts keep their own 25 MiB input bound and are not yet metered by this cap. When several caps apply, the lowest wins: the per-page cap, the run's consent cap (--max-usd), embed.backfill_max_usd and embed.backfill_max_usd_per_source_24h. A page over its cap is still keyword-searchable, and its newest chunks are embedded first, up to the cap. Doctor's partial_embedding check counts such pages by source and prints each source's approve command with a concrete N, gbrain embed --held --source <id> --max-usd <N>; raising a cap is the user's call.

After upgrading. Older releases stored a page over 500 KB with an embed_skip marker (reason oversized) and no chunks. gbrain upgrade (its gbrain post-upgrade step) re-chunks and keyword-indexes those pages itself for up to two minutes, on the CPU, on keyless brains too, and prints a receipt; gbrain reindex --oversized does the rest. The backfill is idempotent and resumes where it stopped. It removes only gate-written markers whose reason is oversized, and the matching content_flag: oversized; a page above the operator's effective bytes_block keeps both and is re-chunked for keyword search with no vectors. The backfill never embeds. A page whose rewrite is refused (an invalid fence the canonical owner will not write, for example) keeps its marker and is listed under failed; the hold placed for it is put back, so it is not left waiting for an approval that cannot embed it. Until its content is repaired, the chunk safety net (gbrain embed --stale, the cycle's embed phase) gives it chunks for keyword search with no vectors, and doctor oversized_pages counts the marked pages with and without chunks. Backfilled pages over 1 MiB are held for consent; the post-upgrade notice, gbrain embed --stale (its budget_limited line) and doctor's partial_embedding check show how many are held and what embedding them would cost; doctor also says how many holds have waited more than a day without a decision, and since when. Pages between 500 KB and 1 MiB cost a cent or two each and embed through the normal sweep under the existing caps.

Nothing releases a hold automatically. gbrain embed --held --dry-run lists every source, writes nothing and prints one approve command per source; an approval covers one source, so --held --max-usd needs --source when held pages span several sources. --max-usd N is two things at once: the run's hard cap and the extra allowance saved on each page it approves, so the printed N is a ceiling (the estimate x1.5, at least $0.25), not the estimate. It works on every provider; on a local one that bills nothing the printed N is $0.01 and the run costs nothing. A run stopped by its cap, or interrupted, keeps every vector it wrote: the page it was on is no longer held and the stale sweep finishes it under its new allowance, and pages it never reached stay held for the next approval. --yes never approves a held page. An approval is refused, with every hold and cap unchanged, when embeddings are unavailable (disabled, no provider credentials) or the paid model has no price.

gbrain reindex --oversized --dry-run --json      # preview the backfill: free, no provider calls
gbrain reindex --oversized --source <id>         # run it now for one source
gbrain embed --held --dry-run                    # every source: held pages, the cost to finish, one approve command each (free)
gbrain embed --held --source <id> --max-usd 2    # embed one source's held pages: $2 caps the run and is each page's extra allowance (paid)
gbrain embed --slugs <slug> --source <id> --max-usd 1  # embed one page, capped at $1 (paid)
gbrain search "<a phrase from deep in the page>" # keyword search finds it before any embedding
gbrain doctor --only partial_embedding --json    # pages embedded only up to their cap
gbrain config set embed.max_usd_per_page 5       # raise the per-page cap (ask the user first)

Where text goes

Local storage does not mean every enabled feature runs locally. Keyless keyword retrieval and deterministic link extraction need no model API. Configured cloud embeddings receive the text being embedded; rerankers receive the query and candidate passages; expansion receives the query; synthesis and LLM extraction receive the relevant retrieved content or source text. Self-hosted providers have their own deployment boundary. The connected agent's own model also receives whatever memory its harness includes in context, even on a keyless GBrain setup.

Access designations decide who reads a page, not which configured providers process it, and they do not exclude a page from processing that is turned on. A page with readable_by, a folder rule or visibility: private is embedded like every other page, so the configured embedding provider receives its text. Private facts and takes are embedded on their own, so the provider receives their text too. When contextual retrieval runs at the synopsis tier, the chat model also receives the page's title and text (with private fact rows and takes removed). GBrain cannot tell a local endpoint from a remote one, because a recipe's base URL can point anywhere. A self-hosted embedding provider (and synopsis model) on hardware you control keeps restricted text in house for embedding and contextual retrieval only. Every other enabled provider, such as a reranker or a chat model, can still receive restricted text, so self-host or turn off each one that must not. The decision provider is stricter by default: while decide.egress.private is deny (the default), System One calls to TypeSafe withhold restricted pages, private facts and conversation text, except for the reranking slot and the fact and conversation items of a slot turned on by the key-aware default. An llm: decision provider, or setting decide.egress.private allow, removes that guard.

Reporting back through Wakeshift (off by default, owner opt-in) sends a watched job's, write request's or cron's id, status and times (and a removed member's hashed id to forget), never page text, titles or slugs; see what leaves the machine.

Enable paid capabilities and automatic capture only with consent, using the provider's actual data-handling policy. See installation capabilities and spend controls. A spending cap is not a promise that no text leaves the machine.

Sharing and backup limits

Remote access depends on authenticated source/operation grants and visibility filters. Sources organize memory; they do not isolate agents that share local files or database credentials. Stdio is local access, not an HTTP client grant. Read brains and sources before choosing a sharing topology. Tests cover specific boundaries, not a universal security guarantee.

A brain that serves several people (two or more enabled members, or config access.serves = several) refuses remote reads from a connection bound to no member (requester_scope_required, after a 14-day grace for connections that already existed), so a shared bot cannot read everyone's unmarked notes for whoever is asking. That covers reads only: writes keep their own rules, and a page that names no readers is still read by every member. The refusal and its fix.

Fence markers quoted in code. Since 0.60.97.0 the readers (the fence parser, projections, repair) ignore a takes or facts fence marker that sits in inline code or inside a fenced code block, and since 0.60.162.0 a marker written into a cell is encoded, never live, so documenting the marker no longer creates a phantom fence (#5395). The remote privacy boundary deliberately does not follow: sanitizeRemoteBody still treats the first begin marker it sees, quoted or not, as the start of a protected region and hides everything after it from remote readers, and a remote whole-page replace of a page with an unpaired quoted marker is refused with "The takes fence must be repaired before replacing this page." The boundary only ever changes toward hiding more; a remote reader that cannot see the tail of a page that quotes the marker is seeing that rule, not a bug. To publish such a page remotely, write the marker in a form the scanner does not match (split it, or describe it) or move the mention after the real fence. Pinned by test/fence-marker-code-context.test.ts ("remote privacy boundary" and "remote page replacement").

Markdown export is a portable view of pages, not a full database backup. DB-only facts and pages (extract receipts included), revision history, the belief ledger (what the brain had recorded, and when; gbrain beliefs), withdrawal state, jobs, settings, and authentication records may not be recoverable from Markdown. On a brain with several sources or members, an import of an export puts every page in one source with no members, tokens or facts, so a page from a personal source comes back readable by everyone in that source. Use the engine's full backup/restore path and verify a restore into a separate location:

  • PGLite: gbrain backup create --output <absolute path>, restored with gbrain backup restore (isolated local backup guide).
  • Postgres: a dump of the brain's database, pg_dump --format=custom --file <dump> --dbname <database>, restored into a new, empty database with pg_restore --no-owner --dbname <new database> <dump>; gbrain init --url <new database> under a separate GBRAIN_HOME then opens it with its sources, members, tokens, folder rules and facts. gbrain backup create refuses on Postgres. The restored brain's sources still name the original's content folders, so keep only one of the two brains writing to them. See embedding migrations for a quiesced dump with service files that keep the password off the command line.

Treat database backups as sensitive. See the system-of-record contract.

Expire versus purge

A write's reason is stored with the page's history and, when the page's file reaches Git, in the commit message. A purge removes the database copies it covers, but a commit already pushed keeps its message text, just as it keeps the file's earlier contents. Purge records those commits so no later sync stores the reason again (purge and reasons).

forget expires: the fact stops being recalled, cannot be saved again in the same source and visibility, and its row is struck in the page's Markdown. The text stays in the row, the file, page history and backups.

The struck rows are written first: every page file that carries the claim is published in one write (one Git commit on a source that commits through gbrain), and the withdrawal commits with it. A forget waits for the source's writer like any other write, so while that writer is unavailable the forget is accepted and pending, and the fact is still recalled. The withdrawal itself is a database row, and only forget records one: a page write or sync of a struck row imports an expired fact and withdraws nothing, so a brain rebuilt from Git can save that claim again until it is forgotten there. A fact saved without an entity is a row of the memory/unattributed page, so its withdrawal has a file too.

Automatic extraction (sync import, put_page, extract_facts, the sweep) skips a candidate whose exact claim was forgotten in that source and visibility and still saves the other facts it found about the same entity; the entity and completion write receipts and the extraction result count the skips as withdrawn_skipped, and a group of only forgotten claims completes with nothing inserted. Explicitly remembering the forgotten claim still refuses with fact_withdrawn, and a purge tombstone still refuses the whole write with purged_content. A claim forgotten after an extraction's facts were prepared refuses that entity's write with revision_conflict and a detail naming the withdrawal; nothing is published. An extraction keyed by its input alone (sync import or the sweep, which have no request id) recovers on its next run from such a refusal, and from a batch an older release refused for a forgotten claim, by re-admitting the retained facts without another model call (at most three follow-ups per batch, each visible as its own write receipt; the refused receipts stay as they were). An extraction admitted under a request id replays its receipt; give it a new request_id to extract again.

gbrain forget <id> --purge purges: an owner-only command on the brain host that removes the claim from the live stores gbrain controls and returns a receipt. It is a separate operation (purge_fact), never a mode of the forget verb, and no MCP connection can call it; agents get trusted_local_only with the command to give the user.

Say to your agent: "I saved a secret by mistake. Show me what purging fact 42 would remove, then purge it once I confirm." The agent runs gbrain forget 42 --purge --dry-run and hands the purge itself to you.

What one purge does, in one transaction:

  • deletes every fact row with the same normalized claim in the fact's source, visibility and entity (--all-subjects: every entity), and verbatim take copies (consolidated takes, takes with the same claim);
  • drops the row (not a strike) from the page's facts or takes fence, from the stored page body and from every saved page version, then rebuilds that page's chunks; the canonical file is rewritten by the owner and committed as gbrain: purge fact <hash8> (no claim text in the commit). A purge of a fact held on a holding page (memory/unattributed, or a folder's <folder>/memory/unattributed) for an entity with no page also drops every copy of the same claim text on that page, whether it is held for another entity or has no entity;
  • redacts stored write intents that carry the claim (a write that is running or recovering blocks the purge with purge_blocked_pending_recovery until it finishes; retry with the same request id; a write still queued, or deferred behind a gbrain sources refresh, whose staged body holds the claim is cancelled with purged_content instead), deletes legacy query-cache rows and drops the fact's rewording-review rows (close active matches are returned first as similar_active);
  • hides rows a model derived from the fact (through the derivation edges derivers record) and marks them needs_rederive; the receipt reports them as retained_inactive, not as removed text;
  • records a text-free tombstone: the claim's fingerprint, its source, visibility, entity, request id and reason. Any later write of the same normalized claim is refused with purged_content, and a stale file, re-sync or revert drops the row on import. The tombstone applies to the whole brain: it refuses a member's save on its own member page too, even when that member could never read the purged fact, so a member who saves matching text learns that a purge exists.

On a terminal the CLI prints the dry-run receipt and asks you to type the fact's 8-character token; without a terminal it needs --yes and --request-id. --match "<text>" lists candidate ids and never purges. --status --request-id <id> reports completion: committed (effects such as the file rewrite still running, exit 10), complete (exit 0) or incomplete (an effect failed or a swept store still holds the claim, exit 75; retry with the same request id).

The receipt lists residuals first. Purge removes content from live stores; it is not physical erasure. Out of its reach, and named in every receipt: the brain repository's git history (the commits that carry the row are listed, never rewritten) and every other clone or remote, backups taken before the purge (a restore brings back the content and an older purge ledger; with the belief ledger on, gbrain doctor --only belief_ledger_coverage asks you to replay those purges when the restore could not), provider copies (embedding and decision providers), Markdown exports and compiled context files, and deleted rows in database pages and the write-ahead log until vacuum. On PGLite, --vacuum compacts the touched tables; on Postgres the receipt names the VACUUM the operator runs, and WAL archives, replicas and point-in-time recovery stay outside gbrain. Claim text in page prose (outside a facts fence) is reported as source_prose: edit or purge that page. Each store in the receipt is deleted, retained_inactive, unverified (a probe hit its time or row bound) or out_of_reach; "verified" covers only the swept stores. The vector probe lists close same-model facts as possible rewordings; it is not a residual count.

The tombstone fingerprint of a short claim is guessable: anyone who already knows the claim can confirm it was purged. It never reveals what an unknown claim said.

gbrain delete <slug> --purge purges a whole page the same way: facts filed on it (tombstoned), its takes, take proposals, open loops, core notices, stored write intents, attached file records and blobs, and the page row with its chunks, versions, timeline, links and raw data. It records the page's content hash and the hash of every saved version, so the same content or an older version of it is refused under any slug until gbrain pages unpurge <slug>; gbrain pages purges list shows the tombstones. An edited file imports normally. Its response carries the same store-by-store receipt as a fact purge, naming other pages whose prose still states one of the purged page's facts. A write refused because it carries purged content, or accepted as a no-op after its purged rows were dropped, keeps no copy of that content in its stored write request.

An owner purge held to keep a derived page private (derived_origin_parked) stays owed until its page is removed or restored: whichever purge later removes the page, the automatic one included, writes the purge tombstones.

A restore replays every purge newer than the backup from the purge mirror, purge-events.jsonl in gbrain's config directory ($GBRAIN_HOME/.gbrain, else ~/.gbrain), and a replayed page purge sweeps the same stores as the live purge. A host that runs each gbrain writer in a home directory it removes after the run loses that mirror, so run every writer with GBRAIN_HOME set to one durable directory. gbrain doctor --only purge_mirror warns when a purge from the last 30 days has no line in the mirror this process uses.

Verify in the actual harness

Use a generic, unique test fact: remember it, recall it, correct it, recall the correction, withdraw it, and confirm active recall no longer returns it. Then open a new conversation in the intended harness and repeat recall with another saved test fact. A local CLI test proves local storage, not skill activation or cross-conversation recall in Grok Bot, Muse, Codex, or Claude Code.