Garry's Opinionated OpenClaw/Hermes Agent Brain
Explicit attendance evidence
Only a link's target can become its attendee. Names or slugs inside the link's display label are not additional attendees.
When a schema pack does not override attendance, GBrain records a confirmed
person's attendance as person --attended--> meeting. It requires an explicit
attendance list, not a person mentioned somewhere in the meeting note.
Say to your agent: "Who attended this meeting? Show the source, and don't count people who were only invited or mentioned."
Supported evidence
On a meeting page, use canonical structured attendees frontmatter, a bare
Attendees: link list (the bold **Attendees:** label works the same way), or
a dedicated ## Attendees section containing only bare link-list entries.
Participants works everywhere Attendees does (Participants:,
**Participants:**, ## Participants). Each reference must resolve unambiguously to a live
person page in the allowed source scope. For example:
---
type: meeting
title: Planning
---
Attendees: [Alice Example](../people/alice-example.md)
An alternative body is:
## Attendees
- [Alice Example](../people/alice-example.md)
Free prose, qualified lists, code examples, and ordinary mentions are not canonical attendance evidence. Keep absent or invited-only people outside the attendee list: a bare list asserts that each linked person attended, and link labels are not a natural-language qualification parser. Unsupported or ambiguous references remain mentions or unresolved references.
HTML comments and backtick and tilde code fences are excluded even when they contain headings inside an attendee section. A closing fence must use the opening character, have at least its length, and contain only trailing whitespace. An inline comment beside a visible attendee does not make its hidden references part of the attendee list, even when those references resolve to live people. An example comment opener inside code does not hide real attendance below it. When global basename resolution is enabled, a unique bare attendee wikilink can resolve to a person; missing or ambiguous names remain incomplete.
The existing query surface can read the resulting relationship:
gbrain call query '{"query":"Who attended meetings/planning?","expand":false,"relational":true}'
The meeting owns the derived claim. Re-extracting the person does not delete it; removing the attendance evidence and re-extracting the meeting does. Manual claims and claims from other origins remain separate. Remote writes still follow the existing deferred-maintenance rules in memory boundaries.
Filesystem extraction uses the file as evidence and the database for canonical attendance endpoint types and source identities. A person does not need a local Markdown file. Source-qualified references follow the same explicit opt-in, federation, and configured-default rules as database extraction.
An unresolved or denied attendance reference is not a retraction. The origin's
derived graph stays unchanged, and extraction does not mark it processed or
advance its watermark. Local page publication still accepts the content,
reports an auto-link error, and leaves extraction retryable. Removing the
supported evidence entirely still retracts its owned attendance edge. Ordinary
filesystem links and schema-pack-owned mappings retain their existing behavior.
A linked page changing or disappearing between preparation and the locked
graph check has the same automatic-link error outcome: the note is saved, no
new graph delta is written, and later extraction can retry. This does not
suppress source/authority conflicts or unexpected storage failures.
DB and stale extraction report skipped incomplete-attendance pages; their JSON
summaries add skipped_attendance_incomplete only when it is nonzero. Sweep
reports attendance_resolution_incomplete, not a budget timeout, for that case.
Filesystem extraction omits incomplete pages from its processed set, but does
not currently provide a per-reason skip counter.
Attendance lookups stay within the meeting page's own source. An attendee
name, address or slug resolves only against person pages (slug, title or
aliases) in the source that holds the meeting; a person page carrying the
same address or alias in another source, such as default for a
connector-sourced calendar page, does not satisfy it. This is policy, not a
missing search step: to make such a page converge, create the person page (or
an alias-carrying one) in the meeting's source.
Stale extraction (gbrain extract --stale, managed or not) marks a page it
skips for unresolved attendance as attendance-blocked at the page revision it
read. The links_extraction_lag doctor check leaves those pages out of its lag
count and reports them in their own count (details.attendance_blocked), so
running extract --stale again is not suggested for them. Extraction still
reconsiders every marked page: once the attendee's person page exists, the next
run publishes the page's links, advances its watermark and clears the marker.
Editing the page changes its revision, so it counts as lag again until the next
extraction.
Schema-pack boundary
An unavailable schema pack is not a pack with no attendance override. Link extraction refuses before changing the graph when the active pack cannot load; sweep reports a link/timeline pass error. Local publication still accepts the note but reports an automatic-link error and preserves the prior graph. Repair or restore the pack configuration, then retry extraction.
The shipped gbrain-base and company-brain packs declare attended bound
only to the meeting page type and map meeting attendees to attended. Both
follow the canonical rules above: frontmatter and body attendance are stored
person -> meeting, and a person only mentioned in the notes stays a mention.
This also covers brains with no schema_pack configured, which resolve
gbrain-base. A pack whose attended rule has a phrase regex decides
attendance itself; its body links keep that pack's outgoing semantics and
historical repair reports them as pack_semantics_preserved.
Links extracted before this rule (stored meeting -> person, or typed attended
from a notes mention) re-derive on the next gbrain extract --stale sweep,
because the extractor version changed. Frontmatter edges re-derive only when
frontmatter is included, so run this once per source:
gbrain extract links --source db --include-frontmatter --source-id <id>
It replaces each page's own derived links (markdown, wikilink and frontmatter producers) in one transaction per page; manual links and links other pages created are untouched. A repair on a real brain still deserves a verified full database backup; a Markdown export is not a rollback image.
Preview-bound historical repair
Say to your agent: "Preview historical attendance links in source notes.
Show the proposed additions, removals and skipped origins. Don't apply anything
until I've reviewed that exact preview and verified a full database backup."
Use the existing trusted-local DB extraction surface. It is unavailable to
MCP and thin clients. An explicit live source is required, even when a default
source is configured. DB-only meeting pages work without filesystem sync.
The literal source ID default must also exist and remain live: its incarnation
pins the brain identity even when repairing another source. Either archive
indicator on the selected source or default refuses preview and apply.
umask 077
mkdir -m 700 attendance-review
gbrain extract links --source db --repair-attendance --source-id notes --json \
> attendance-review/preview.json
Preview writes no logical database rows, extraction watermarks, source files,
receipts or checkpoints. It opens an existing database without migrations or
automatic repair; a storage engine may still maintain its locks and WAL files.
The operator's shell creates the private receipt above. Keep it private: it
contains source-qualified page identities and hashes, but no copied source
text or evidence snippets. Review its counts, bounded diagnostics, pack,
direction, and origins before authorizing it.
Each preview invocation creates a new approval ID and exact digest, even when
it proposes no changes. Save and approve that exact receipt rather than
regenerating it between review and apply.
The connection pin hashes only the selected brain and its stable target:
the resolved PGLite path, or PostgreSQL scheme, ordered hosts/ports and database.
Credentials, userinfo, unrelated configuration and query option values do not
participate. PostgreSQL targets require explicit hosts and a database; ordered
multihost and bracketed IPv6 addresses are supported. Socket/service URLs,
query-based target overrides and malformed targets refuse rather than sharing
a fallback identity. Changing the target or brain requires a fresh preview;
rotating credentials alone does not. Previews from the older connection-pin
format also require a fresh preview.
The default window is 250 source pages; --limit accepts 1–1000. The
indexed (source_id, slug) window is selected before filtering deleted or
nonmeeting pages. counts.scanned counts that window, while
counts.eligibleOrigins counts live meetings inside it. A window may have no
eligible origins. After applying a reviewed window, use --after-slug with
its nextAfterSlug to preview the next one. Each window requires a new preview,
confirmation and checkpoint file path. Do not reuse cursor.json with a new
preview: the checkpoint belongs to the exact approved receipt, so use names
such as preview-002.json and cursor-002.json for the next window.
Database ordering determines the cursor, including Unicode
and punctuation; a full-sized final window requires one more empty preview.
The cursor is a bounded traversal, not a snapshot across separate previews:
new or renamed pages behind it require another pass from the beginning.
Historical repair accepts only explicit Markdown attendance links. All frontmatter attendance is report-only, including apparently canonical paths, and existing frontmatter claims keep their IDs and evidence. Repair neither loads frontmatter nor approximates the ordinary extractor's source-wide title/alias uniqueness checks. Body targets use bounded, source-scoped exact slug lookups; missing or ambiguous targets skip the origin without deletion. Mixed person/non-person attendance lists are also report-only: repair does not partially reinterpret them or delete earlier claims to make the list fit.
Each eligible origin is capped at 256 KiB of body text, 256 lookup slugs and 512 adjacent link rows of any type. Three capped adjacency probes each inspect at most 513 logical IDs before selecting attendance edges. An over-limit origin, proposed post-repair adjacency or oversized attendance evidence is report-only. Oversized body and edge evidence are not transferred from the database into the repair process. These are logical row and transfer bounds, not physical MVCC page-scan or total-process-memory guarantees. At most 20 diagnostic details are retained, alongside aggregate counts. Retained origin receipts above 16 MiB are refused; retry with a smaller window.
Repair preserves outgoing attendance only for a pack whose attended rule
has a phrase regex; shipped base and company-brain meetings repair to
person -> meeting like a brain with no pack override. Missing packs are
report-only. It never guesses
ownership for NULL, unknown or manual producers. Legacy outgoing Markdown is
eligible only when authoritative source text proves the same resolved person's
attendance. Other derived/manual links keep their row IDs and evidence.
Before applying on a real brain, quiesce old extraction writers, verify a full
database backup and its recovery procedure, and obtain separate operator
approval. Copy the exact receipt's digest into the following command:
gbrain extract links --source db --repair-attendance --source-id notes \
--apply-preview attendance-review/preview.json --confirm APPROVED_DIGEST \
--yes --backup-verified --checkpoint attendance-review/cursor.json
--backup-verified acknowledges the operator's backup verification; it does
not perform or verify a backup. The receipt and checkpoint must be owned,
private regular files in an owned private directory. Symlinks are refused.
Filesystem, stale, global, parallel, mention/NER and timeline extraction flags
cannot be combined with repair. --yes alone never applies a new scan.
Each origin runs in its own transaction. Brain connection and source incarnation, origin/endpoint IDs and revisions, parser/ontology identity, reference resolution and exact affected edge rows are checked again. Changed state refuses the preview instead of silently recalculating approval. The transaction applies only the attendance delta and banks a private database commit receipt; the private file cursor advances only after that commit. Re-run the exact apply command after interruption. A commit before a cursor write is recognized without deleting/reinserting identical rows. A failed origin is not passed; changed state requires a fresh preview. The cursor also covers revalidated deleted/nonmeeting prefixes and tails, including windows with no eligible origins, but never passes an uncommitted origin. A successful prefix remains committed if a later origin fails.
Version-2 approvals expire seven days after their database-clock issuance time. The commit proof must independently remain within the existing global seven-day checkpoint pruning horizon, measured from the proof row's update time. A late apply or replay extends neither deadline. Version-1 receipts, expired approvals and retained expired proofs require a fresh preview, new confirmation digest and new checkpoint path. Repair has no pruning exemption. If proof is pruned or otherwise lost, obtain and approve a fresh preview; retaining the private cursor does not establish a database commit or extend either lifetime. A still-young no-op approval with missing proof can be indistinguishable from first apply when its approved pre-state is unchanged; repair does not reconstruct missing commit history. Row-identity preservation is an A2 repair/replay property, not a promise about other writers: later ordinary DB re-extraction can preserve attendance semantics while changing repaired row IDs, invalidating replay of the old preview. Preview again then too.
Each origin transaction takes a table-wide link lock, pausing link writers across the database while ordinary PostgreSQL reads remain available. PGLite retains its existing single-owner connection model. Lock waits are capped at five seconds and individual statements at ten seconds; contention refuses the current origin for retry. Existing normal extraction paths and their watermarks are unchanged. Reverting the code does not undo a repair; recovery requires the full database backup or a separately verified reverse repair.