Garry's Opinionated OpenClaw/Hermes Agent Brain
Link facts saved without an entity
A fact is only useful to entity lookups when it is pinned to the person,
company or project it is about. Facts saved without that pin (an agent called
remember without entity, or a page import whose extractor named nobody)
are invisible to entity recall, never show on the entity's page, and the
System One conflict sweep skips them as no_entity.
GBrain now prevents most of them at write time and repairs the backlog with
gbrain facts relink.
Say to your agent: "Link my unattributed facts to the people and companies they're about."
The agent runs gbrain facts relink --dry-run, shows you the plan, then runs it.
Say to your agent: "Why is the conflict sweep finding nothing?"
The agent runs gbrain decide status and gbrain doctor; an unlinked_facts
warning or a no_entity share points at gbrain facts relink.
What happens at write time
When remember gets no entity, it looks for one in the fact text without
calling a model. It links only when the text names exactly one existing
entity page by its full name, slug or alias, and no other name competes. "Acme
Example raised a seed round" links to companies/acme-example. "Alice Example
introduced me to Charlie Example", "Bob said yes" (a bare first name) and
"Northstar Example copied Acme Example's pricing" (a second company with no
page) stay unattributed. The response says what happened: entity_inferred: "mention" when it linked, or warnings: ["NO_ENTITY"] with a hint when it did
not. Pass infer_entity: false to skip inference for one call.
Page imports work the same way, and a fact extracted from an entity page with no other name in it belongs to that page.
CJK subjects need a literal slug or a delimiter
Chinese, Japanese and Korean text has no spaces between words, so write-time
inference and relink's free tiers cannot tell where an unspaced name ends.
They link a CJK subject only from its literal page slug followed by a space or
punctuation. Unspaced natural-name inference is unsupported: name the page
with --entity (or entity) instead. Relink's model tier also needs the name
set off by a space or punctuation.
| Fact text | Free inference |
|---|---|
people/王小明 负责项目。 |
links people/王小明 |
people/王小明负责项目。 |
no link |
王小明负责项目。 |
no link |
Turn write-time inference off with gbrain config set facts.entity_inference off. That does not undo earlier links, and it does not affect gbrain facts relink.
Repair the backlog
Run these on the brain host (thin clients refuse the command).
gbrain facts relink --dry-run # what would link; writes nothing, calls no model
gbrain facts relink # free tiers, then the model tier (default cap $1.00)
gbrain facts relink --no-llm # free tiers only
gbrain facts relink --max-usd 5 # raise the model-tier cap (or: off)
gbrain facts relink --json # machine-readable report (schema_version 1)
Relink finds a subject in three tiers, cheapest first: the page a fact was
extracted from, a unique entity named in the text, and finally the configured
fact-extraction model (facts.extraction_model) for whatever is left. The
model's answer must quote the fact and name an existing entity page, so an
invented or injected name never links. Private facts stay out of the model
tier unless you pass --include-private. Before the first model call relink
prints the provider and an estimated cost.
Each linked fact keeps its id, embedding and provenance and is written onto
the entity page's ## Facts fence exactly as a fresh remember with that
entity would write it (the canonical file too, when the source writes
through). Its context cell records how it was linked (entity relinked from mention, ... from page, ... by model (<model>)). An exact duplicate of a
fact the entity already has is retired: expired, kept in history, never
deleted. Relink never creates pages and never supersedes a fact.
Large brains: continue where you stopped
Each run examines --limit facts (default 1000), walking by fact id. When more
remain, the report ends with the exact command to continue:
gbrain facts relink --after-id 48211
Facts that can never link do not block the ones after them. --since 2026-09-01 limits a run to recent facts.
The conflict sweep
When the System One conflict slot is on, every linked fact is queued for the
next sweep (queued_for_conflict in the report). A large backlog drains over
several sweeps within the sweep's normal per-run quota and daily budget;
gbrain decide status shows the progress. --no-conflict-queue skips the
handoff.
Reruns and cost
The model's verdicts (no_subject, ambiguous, unverified_match) are
remembered, so a rerun does not pay for the same fact again. Pass
--retry-model to ask again. The free tiers always rerun, so creating an
entity page and rerunning links facts that name it.
Fix a wrong link
--json lists the facts each run linked. To move one, forget it and remember
it again with the right entity:
gbrain forget <fact-id>
gbrain remember "<the fact>" --provenance "<source>" --entity <slug>
Conversation facts
Facts gbrain extract-conversation-facts stored without an entity belong to
their conversation page, so plain gbrain facts relink never examines them.
Link them for free, with the same rule as write-time inference (exactly one
entity page named in full, no competing name, no model call):
gbrain facts relink --conversation --dry-run # what would link; writes nothing
gbrain facts relink --conversation # the 50 pages with the most untried unlinked facts
gbrain facts relink --conversation --slugs a,b # exactly these pages
A linked fact stays on its conversation page with the entity set and the note
entity relinked from mention: same row, provenance and trust, no Markdown
edit, so it needs no consent. A re-extraction of the page
(extract-conversation-facts --force) keeps the link on the claim's new row
without a second copy. A fact no entity can be proven for is recorded,
so doctor unlinked_facts then offers a paid re-extraction of its page
(gbrain extract-conversation-facts --slugs … --force, previewed with
--dry-run, capped with --max-cost-usd) instead of this relink again.
A miss the table below does not remember (no_page, no_mention,
withdrawn) is tried for free again once a new page is created in the
source, for example the missing entity page.
Every completed extraction of a page is remembered with the page's content
hash. While the page still has that content, doctor offers no paid
re-extraction for it: facts still unlinked there are listed for linking by
hand (forget each one and remember it again with --entity). Editing the
page's content offers the re-extraction again.
Name tags for people and companies with no page
A brain built only from conversations usually has no person or company pages.
So that a person's facts can still be grouped (their job titles, employers and
cities in date order), conversation extraction gives a fact a name tag when
the extractor named someone in full and no page matches: the name in slug form,
without a folder. "Alice Example", "alice-example" and "people/alice-example"
all give the tag alice-example. A single word ("Alice", "travel") gives no
tag, and the fact is stored without an entity as before. No page is created,
lists of pages never show a tag, and a tag is per source. Only new extractions
get tags; existing facts are not changed. A fact on a tag gets a slot (role,
employer or city) from the same small tagging call that person pages get.
When you later write a page for that person (people/alice-example), reads
of the page include the tag's facts, because the tag is the page's file name.
To move them onto the page for good, preview and then run:
gbrain facts relink --conversation --unbacked --dry-run # what would move; writes nothing
gbrain facts relink --conversation --unbacked # move them
A tag moves to the one page its name resolves to: the exact file name in a
people, companies, hosts, projects or concepts folder, a unique alias, or the
same name ignoring a company suffix ("Acme Example" and companies/acme-example-inc
titled "Acme Example Inc"). A page that was merged into another
(superseded_by) hands its facts to that page. A world fact never moves onto
a private page. A tag that still matches no page, or matches two, keeps its
facts.
Forgetting or purging a fact on a tag applies to that claim across the whole source, and a claim forgotten or purged for any person never comes back on a tag, so writing a page or moving a tag never brings a forgotten fact back.
Two different people with the same full name in one source share one name tag
until a page or alias tells them apart. Today their facts share nothing because
they have no entity at all, so this only matters once both are talked about in
the same brain, which is rare for full two-word names. When it happens, a
history question about that name lists both people's values in one timeline,
and a newer value of one can end the other's stint. To separate them, write a
page for each (for example people/alice-example and people/alice-example-2
with an alias that tells them apart), then run gbrain facts relink --conversation --unbacked to move the facts whose page resolves; facts that
still cannot be told apart need extract-conversation-facts --force on the
pages that mention them (paid; preview with --dry-run). A page written later
at the same file name adopts the tag's facts on reads.
Turn name tags off with gbrain config set facts.unbacked_entity_keys false.
New extractions then store such facts without an entity, as before; facts
already on a tag keep it.
Neither relink attaches what the assistant or a named third party said (a
fact saved with attributed_to assistant or other) to an entity page. Such a
fact is counted as not_user_attributed and left where it was saved: recall
still finds it, and doctor unlinked_facts does not count it.
Why a fact was not linked
| Reason | Remembered | What to do |
|---|---|---|
no_subject |
yes | The model found no single person, company or project in the fact. Nothing to fix; rerun with --retry-model to ask again. |
ambiguous |
yes | The fact names more than one entity, or a name competes with the match. Link it by hand: forget it and remember it again with --entity. |
unverified_match |
yes | The only match is a bare first name or a name that is not in the fact. Add an alias to the right entity page, then rerun. |
no_mention |
no | The fact names no entity. Rerun with the model tier (drop --no-llm), or link it by hand with remember --entity. |
no_page |
no | The fact names an entity that has no page. Create the entity page, then rerun. |
model_unavailable |
no | The extraction model could not be reached. Configure it with gbrain config set facts.extraction_model provider:model. To skip the model tier, run gbrain facts relink --no-llm. |
model_unparseable |
no | The model returned output relink could not read. Rerun; if it persists, set a different facts.extraction_model. |
withdrawn |
no | This claim was explicitly forgotten for that entity, so relink will not attach it there. |
not_user_attributed |
no | The fact records what the assistant or a third party said, not your own claim, so relink never attaches it to an entity page. Nothing to fix: it stays saved and recall still finds it. |
page_file_missing |
no | The entity page exists in the database but its file is missing from the source tree. Restore the file or run gbrain sync, then rerun. |
unfenceable |
no | The source writes through to files but has no canonical owner. Bind the source (gbrain sources writer status |
fence_malformed |
no | The entity page has a ## Facts fence that cannot be normalized. Preview the fence repair of that page (repair fences --slug <entity-slug> on the brain host; read-only, and it names the exact edit for anything it will not repair), apply it, then rerun. |
claim_unfenceable |
no | The claim text cannot be written to a fence row unchanged (for example it is wrapped in ~~). Forget it and remember a cleaned-up claim with --entity. |
visibility_conflict |
no | The entity already has the same claim from the same source with the other visibility, and a page indexes only one. Forget the copy you do not want, then rerun. |
fence_owned |
no | The fact lives in another page fence or is a conversation page's extracted fact. Relink does not move fence-owned facts; conversation facts are linked by relink with --conversation (free, preview with --dry-run). |
budget_exhausted |
no | The model tier reached --max-usd. Raise --max-usd (or pass off) and rerun with the printed continuation command. |
revision_conflict |
no | The fact or the entity page changed while relink ran. Rerun. |
Doctor
gbrain doctor reports unlinked_facts: the share of active facts with no
entity, the share among facts created in the last 7 days, the facts the model
already judged subjectless, and how many links write-time inference and relink
made. It warns when more than a quarter of the last week's facts are unlinked.