Garry's Opinionated OpenClaw/Hermes Agent Brain
How to share skills through your brain
A brain's content source can hold both knowledge and canonical skills. Connected agents read the same authorized revisions instead of maintaining independent copies. The original parent agent follows the same catalog as its children; being the parent does not make its local copy authoritative.
Following skills is not permission to execute scripts, add tools, access more files, install packages, spend money, capture conversations, or replace an agent's identity. Those permissions remain separate.
Where the content lives
For a fresh local brain, gbrain init creates the default source under
configDir()/content/<persistent-brain-id>/default. Normally this is
~/.gbrain/content/<persistent-brain-id>/default. GBRAIN_HOME is the parent
of the config directory, not the config directory itself: setting it to
/absolute/brain-home puts content under
/absolute/brain-home/.gbrain/content/<persistent-brain-id>/default.
content-root/
skillpack.json
skills/
brain-router/SKILL.md
memory-recall/SKILL.md
memory-care/SKILL.md
people/, topics/, ... your existing knowledge layout
The release-pinned gbrain-memory pack contains those three self-contained,
prose-only skills, with provenance and licensing. It needs no development
checkout or helper scripts. The upstream GBrain application repository is not
your content repository.
Fresh owned-root setup also approves following this packaged prose and its existing memory/discovery tool requirements when publication is enabled and no source policy already exists. It does not add scripts, editor grants, spending, or capture. Existing brains, adopted roots, explicit publication opt-outs, and existing source policies are not silently opted into this fresh-setup policy.
An existing registered source root wins. Isolated in-agent setup keeps its
recorded <installation-root>/memory root. Thin clients do not create a second
host repository. New local setup accepts --content-root /absolute/new-root,
--db-only, or --git for explicit Git initialization in a newly owned empty
directory. DB-only mode cannot detach an existing canonical root. No GitHub
repository, commit, push, or off-host backup is implicit. Check the setup
receipt's root, repository_kind, stage, and pending_actions; a
content_directory is not a Git repository, and backup: not_verified is not
a protected backup.
Doctor treats upstream-sync freshness as not applicable only for an owned content
directory or explicitly initialized Git root whose completed, ready setup receipt
matches the current brain, source incarnation, registered root, and active
canonical-owner binding.
The source must have no Git sync commit, external repository, connector, or
company-ingestion policy. Existing external roots and incomplete or mismatched
receipts retain the ordinary never-synced/stale checks; managed persistence alone
does not exempt a source. No last_sync_at timestamp is fabricated. A dedicated
skills source is the other exemption: a source holding an adopted skill pack
(live heads on its current incarnation) whose content is a read-only catalog, with
no Git commit recorded and, when doctor may read the checkout, no .git under
its root, counts as read_only_pack_count in sync_freshness. A git-backed pack
is still judged stale. The separate
canonical_content_writes check reports queued publication and required recovery
for these roots. Both checks classify ownership from database records; remote
doctor does not inspect or execute commands against stored filesystem paths.
Discover the authorized catalog
Use list_skills with {"schema_version":2} over MCP, or:
gbrain skills --schema-version 2 --json
The result contains compact descriptions and triggers, qualified identities,
immutable revisions, policy epochs, requirements, usability, and an opaque
authorized-view token. Follow next_cursor until absent. The default page size
is 50; the maximum is 100. Fetch only the relevant get_skill with
schema_version: 2, the returned qualified_id, and revision. Fetch declared
dependencies through get_skill_asset using that same identity and revision.
Do not turn a returned file into an execution permission.
When supplying separate identity fields instead of qualified_id, pass the
returned brain ID as expected_brain_id (--expected-brain-id on the CLI).
This asserts the already-connected brain; it never routes to another database.
The catalog and receipt field remains brain_id. Shared-skill tools expose no
caller-controlled brain or brain_id routing parameter.
A qualified identity contains the persistent brain ID, source ID, source incarnation, pack ID, and skill name. Copy the returned identity rather than constructing it or choosing a same-named skill from a different source.
Omitting schema_version preserves the legacy response shape. Once shared
publication is active, legacy list_skills, get_skill, and
list_brain_skillpack read the source-scoped sealed catalog too; ambiguous
unqualified names require a qualified selection. Before activation, the legacy
host-directory/resident-pack paths remain. A legacy installed field is not
evidence that the calling harness installed or used a skill.
Resource clients can read gbrain://skills for catalog and revision-bound
body/manifest/asset links. Resources use the same operation, source, surface,
publication, and grant checks as tools. This is GBrain's resource binding, not
a claim of conformance to a draft Skills-over-MCP extension.
The starter surface includes shared-skill discovery and membership tools, subject to authorization. The verbs surface remains exactly the seven memory verbs and does not provide shared skills. Choosing full surface does not add authority. A client can read an authorized catalog without joining.
Approve publication, following, and editing separately
| Permission | What it permits | What it does not permit |
|---|---|---|
read plus discovery operation access |
Read published content in permitted sources | Enrollment or editing |
skills_member_self plus read and membership operation access |
Join, sync, acknowledge delivery, and leave this principal's membership | Memory writes, editing, or another principal's membership |
skill_editor plus write and explicit put_skill/delete_skill operation access |
Publish permitted skill revisions within source and slug fences | Widening the disclosure or follow policy |
skill_publisher plus admin and explicit policy operation access |
Inspect policy with get_skill_policy; approve classes, audiences, requirements, and following with set_skill_policy |
Automatic execution or implicit editor authority |
These named scopes are explicit capabilities, not consequences of admin or
ordinary memory-write access. Standard profiles do not add editor or publisher
authority, including operator and full.
mcp.publish_skills remains the outer remote-publication gate. Migration keeps
an explicit false disabled, maps true to previously approved SKILL.md prose
only, and leaves unknown consent pending. References, assets, and scripts need
separate owner approval; even their metadata is not an implicit disclosure.
Private skills stay excluded from remote publication.
Beyond the fresh-setup default, the owner approves a versioned policy through
set_skill_policy, not through an editor's content update. For example, the
following MCP arguments approve only prose and the tools used by the default
memory pack for existing readers:
{
"source_id": "default",
"expected_policy_epoch": null,
"policy": {
"version": 1,
"enabled": true,
"classes": ["prose"],
"audiences": ["readers"],
"requirements": ["tool:list_skills", "tool:get_skill", "tool:recall", "tool:remember", "tool:forget"],
"allow_follow": true
}
}
Use null only for the initial policy; supply the reviewed current epoch for an update. Inspect the actual pack's requirements before approving. The outer publication gate must also be enabled by the owner. Existing-brain migration and granting client follow access do not approve a source policy; fresh setup's limited packaged policy is not permission to expand disclosure later.
Use get_skill_policy with publisher authority to inspect the current policy
and CAS epoch, including when sharing is disabled. The trusted host can call
these operations through gbrain call; a remote memory grant cannot self-approve.
Connect each installation
Follow hosted access to provision on the host and
install the private handoff inside the intended harness. New gbrain mcp grant
connections default to --skills follow; --skills memory-only opts out of
membership, not necessarily catalog reads. Existing grants are unchanged when
the follow choice is omitted. Reapplying a profile preserves previously
approved membership unless explicit custom scope/operation lists replace it;
it does not enroll an old memory-only client. --skills memory-only explicitly
withdraws follow authority. A profile update is not an implicit skill-editor
regrant.
Use a separate principal and private handoff for every independent installation, including the original parent. Sharing credentials creates one security principal, not independently verified children. Installation IDs come from the server; a client display name is not an identity credential.
For an existing client, preview only the follow change without resetting its profile, finite spending cap, or write fences:
gbrain mcp grant agent-example --client CLIENT_ID --if-version REVISION \
--harness codex --skills follow --url https://brain.example.com/mcp \
--dry-run --json
Review the before/after grant, then repeat without --dry-run. Use the host's
--admin-token-file when administering a running PGLite owner. Added scopes
require a newly issued token; refresh cannot widen the old token's ceiling.
Recover the current private handoff with mcp grant --resume as described in
the hosted guide, then repeat connect ... --install inside that installation.
For a dedicated editor, the trusted host's advanced grant parser accepts the named scope and explicit operation snapshot:
gbrain auth rescope-client EDITOR_CLIENT_ID --if-version REVISION \
--scopes read,write,skill_editor \
--allowed-operations list_skills,get_skill,get_skill_asset,put_skill,delete_skill \
--dry-run --json
This example replaces the scope and operation lists; it is not an append.
Review the existing source and slug fences and include every permission you
intend to retain before applying. Run local auth administration only with
safe database access, never as a second PGLite writer. An editor needs neither
skill_publisher nor enrollment just to publish. A publishing principal needs
its own reviewed admin,skill_publisher and policy-operation permissions;
do not silently turn a memory client into that principal.
The generated adapter reference lists all 13 registry IDs;
gbrain mcp adapters returns their current metadata. Do not infer native skill
support from a name or supported transport.
- Claude Code, Codex, and opencode managed connections install an owned,
namespaced native router. Successful file installation reports
restart_requiredandnative: unverified. Start a new conversation and verify actual use. - Thin CLI and manual clients have visible pending native-registration steps. A downloaded router or connected MCP server is not native activation.
- The router asks the agent to check
sync_brain_skillsbefore selection. That prose is advisory. Only callers routed through the adapter's enforcedadmitseam get its current-view check and pinned revision. No universal per-invocation, offline, or stale-cache guarantee applies to arbitrary vendor sessions.
A newer client connected to an older server reports shared skills unsupported or pending; it does not synthesize a catalog or treat memory access as enrollment. Keep using independently authorized memory while upgrading the host/adapter.
join_brain records an approved follow policy; sync_brain_skills returns a
complete authorized view and accepts an acknowledgment of an issued batch. Acknowledged
installation is a client report, not proof of native use. Policy, source, or
requirement changes can require renewed approval. A server write receipt proves
canonical commitment, not delivery to all members.
sync_brain_skills is the membership operation. It is distinct from the existing
local-only administrative sync_brain content-sync operation.
Existing in-agent installations and legacy bridges
Isolated Grok Bot/Muse local setup uses the recorded installation's private CLI
registration and absolute launcher, not a credential from another brain. Fresh
non-adopted setup defaults to following; existing/adopted roots need an explicit
choice. After upgrading the recorded setup helper, approve with
bash /absolute/installation/bin/gbrain-setup --skills follow --json, or choose
--skills memory-only to stop local following. It writes the owned router and
includes it in instructions/gbrain-skill.md; native saved-skill loading stays
manual with pending / native_registration_required. Inspect the setup
result's shared_skills and the installation's receipts, not connect --status
for a different connection. The local installation is still not an isolation
boundary between agents sharing its files or credentials.
Legacy skillpack scaffold --harness full/stub paths do not copy bundled skill
bodies over an active shared brain. They return a pending migration plan,
inventorying known bridge-ledger files as unchanged, modified, or missing when
the destination is known. An unavailable brain is not permission to fall back
to stale bundled copies. Review and explicitly remove unchanged bridge-owned
copies through the existing harness/destination removal flow before enrolling;
modified or unowned copies require conflict resolution. No legacy body or
native shadow copy is automatically deleted or converted by this plan.
After resolving that inventory, a local bridge can approve following with
gbrain skillpack scaffold --harness codex --dest /absolute/native/skills --skills follow.
Use the actual supported harness and native destination, and --skills memory-only
on that same target for cleanup. The bridge reserves one source/destination per
verified local CLI principal and harness. Reuse that target for repair or rejoin;
leaving does not release its binding. Independent installations need separate
private-handoff principals, not another destination using the same credential.
Conflicting legacy targets can remove unchanged owned local files, but shared server leave is withheld so another target's enrollment is not disabled. The receipt records pending remote cleanup. Edited or unverifiable native files need manual resolution; neither cleanup nor a successful router write proves that a running harness unloaded or used those instructions.
Update a shared skill
An authorized editor calls put_skill with a unique request_id, the current
expected_revision (JSON null for creation), source/incarnation, pack/name,
and the complete declared file set. delete_skill uses the same identity,
request ID, and revision check to publish a tombstone. Inspect the durable
write result: queued or accepted is not committed. Retry a lost response with
the same request ID and identical intent; changed intent needs a new ID.
The publisher validates policy and file hashes, publishes the canonical bundle, and seals its catalog projection. A race returns a conflict instead of last-write-wins. Generic memory writes, raw uploads, and skillpack file-copy commands are not a shortcut around skill publication. Do not resolve a conflict by overwriting the canonical directory or an edited parent copy.
After commitment, refresh the second client and the parent, compare the qualified revision, and test new-conversation routing. Ordinary revisions within the approved policy can follow without individual installation consent; new permissions, file classes, or requirements cannot.
Optimize without bypassing publication
Opt-in run_skillopt calls can select shared_skill: true with the catalog's
source_id, source_incarnation, pack_id, expected_revision, the skill's
skill_name, and a unique stable request_id. The existing benchmark, provider,
budget, and evaluation requirements still apply; connecting or following does
not authorize paid optimization. Remote callers additionally need the existing
administrator/skill allowlist approval, catalog-read authority, and explicit
skill_editor and put_skill permission.
For remote calls, both benchmark and held-out inputs must be approved assets of
that exact selected skill revision, readable through the caller's current
get_skill_asset grant. Their sealed bytes are used for evaluation; a neighboring
skill's file, an unpublished local file, or a changed live file cannot substitute
for the approved input. Trusted-local callers may supply explicitly chosen,
bounded external evaluation files.
The active canonical owner stages the approved closure under private
skillopt-proposals/<proposal_id>, not inside the content root. Only an accepted,
lint-valid body change is eligible for publication; frontmatter and supporting
files stay unchanged. Publication rechecks current authority and the original
revision. Revocation, conflicts, and invalid candidates retain the private
proposal without overwriting canonical bytes. A submitted request UUID refuses
another optimization run before spending; inspect get_write_request rather
than blindly retrying. Shared optimization does not support legacy resume,
write-capture, or evaluation-ablation options.
Publish reviewed filesystem edits
Human/Git edits to canonical files are proposals, not live catalog revisions. The trusted host can publish a reviewed proposal through the same coordinator:
gbrain call --source default import_skill_proposal \
"$(cat /absolute/private/reviewed-skill-proposal.json)"
Prepare that private JSON file from the reviewed current skill identity,
expected_revision, unique request_id, and complete files input used by
put_skill. Add expected_hashes containing the current SHA-256 of every
affected on-disk file and skillpack.json; JSON null denotes an absent file.
Review actual bytes before recording hashes. This local-only operation refuses
changed hashes or revisions and does not approve a broader publication policy.
Do not simply regenerate hashes to dismiss an unreviewed conflict.
Inspect and bound revision storage
Retention administration is local-only, not an MCP editor permission:
gbrain call --source default get_skill_retention '{}'
gbrain call --source default prune_skill_revisions '{}'
Inspect status before pruning. A prune handles at most 128 eligible revisions;
it preserves current heads, tombstones, the most recent 20 revisions per skill,
the 24-hour grace window, active delivery/pin leases, pending publication
references, and permanent write receipts. Source and brain storage budgets can
block new publications with skill_retention_capacity; wait for protections to
expire or prune eligible history rather than deleting active records manually.
retain_skill_revision, also through trusted-local gbrain call, pins an exact
source/incarnation/pack/name/revision for hours greater than zero and at most
24, under bounded quotas. A pin preserves storage, not read or execution
authority. Unpinned old revisions can become revision_unavailable; retain
content backups for longer rollback needs. Retention is not physical erasure of
downloaded files, other history, or backups.
Migrate an existing brain
Use the mechanical v0.53.0.0 migration checklist.
Start on the host with gbrain apply-migrations --dry-run --json. It inventories
registered roots and reports stage-specific conflicts, not arbitrary home
directories or disconnected devices. Keep operational DB and content backups
before applying changes. DB-only export requires an explicit absent destination,
quiescence, and a backup choice; it is not a full database backup.
Writer claim, activation and transfer require deliberate administration intent
and the admin_state from reviewed sources writer status --json output. Neither
routine repair nor --confirm-quiesced supplies that authority. Enable the base
managed writer first when necessary, then inspect fresh status before the separate
--shared-skills activation. The migration checklist gives the exact state-bound
commands; a changed state requires review, not an automatic retry with a new hash.
An existing root is adopted in place. Knowledge folders, private markers,
modified files, and explicit publishing opt-outs are preserved. Unmanifested
skills, malformed manifests, changed hashes, or an ambiguous root remain
conflicts. Host-global catalogs require reviewed source assignment; migration
does not expose them to every source. Do not count pending_host_work or
per-source action_required as completion even if the migration ledger says
the mechanical checkpoint completed.
While a source's inventory, ownership (writer), projection or policy stage, or
a brain-level pending action, is still open, gbrain apply-migrations --list shows 0.53.0 as
applied_pending_host_work (not applied), --list --json adds an
applied_pending_host_work array whose fix.argv is the read-only
inventory, and gbrain doctor warns on minions_migration with
details.code: migration_host_work_pending:
gbrain apply-migrations --migration 0.53.0 --dry-run --json # each source's next step; changes nothing
gbrain apply-migrations --yes # after the work: the re-check records it done
The members stage alone (no installation enrolled yet, as on every new
brain) is not host work, and neither is a source that opted out with
gbrain sources shared-skills <id> off; a brain that declines the migration
(below) never reports it.
The host report's member_installations inventories known members per source,
with joined, refresh_pending, delivery_reported, source_changed, or
left and a next_action. delivery_reported means client-reported artifact
delivery only; every row remains native-unverified. Unknown or disconnected
installations are not proven migrated by that inventory.
Decline the migration for the whole brain
Say to your agent: "We are not adopting shared skills on this brain; stop the v0.53.0 migration from running on every upgrade." The agent runs
gbrain config set shared_skills.migration.enabled false
The key is brain-level database config, so it applies to every machine that
uses that database. From then on gbrain apply-migrations (including
gbrain upgrade and gbrain post-upgrade) skips
v0.53.0 entirely: no inventory, no shared_skills.migration.v1* config
writes, and the applied-migration re-check does not run. gbrain apply-migrations --list and --dry-run show it as declined with the key,
gbrain doctor reports minions_migration ok with declined: ['0.53.0']
(gbrain doctor --fast cannot read the key and never lists v0.53.0 as not run),
and get_health.migrations.declined lists it. An explicit gbrain apply-migrations --migration 0.53.0 refuses with migration_declined (exit
3) and the command that turns it back on instead of overriding the owner's
choice from one machine. To adopt shared skills later:
gbrain config set shared_skills.migration.enabled true
gbrain apply-migrations --yes
Per-source opt-outs (next section) still apply once the migration runs.
Choose which sources adopt shared skills
Say to your agent: "Stop the shared-skills migration from touching the
acme-example source; it already serves its own skills." The agent runs
gbrain sources shared-skills acme-example off on the brain host.
The 0.53.0 migration adopts the skillpack of every owned content source. A
source that already delivers skills another way (its own brain-resident pack
read through list_brain_skillpack/get_skill, or a plugin install) can opt
out. The setting is config.shared_skills on the source; when it is false
the migration preserves the source's files and reports
source_shared_skills_disabled.
Prerequisites: a shell on the brain host (the command reads and writes the
host's source configuration) and the source id from gbrain sources list.
gbrain sources shared-skills acme-example status --json # read-only
gbrain sources shared-skills acme-example off # opt out
gbrain sources shared-skills acme-example on # back to the default
Expected result: every form prints config.shared_skills (false, or unset,
which means on), the effective policy mode (content, preserve_files or
explicit_pack_required) with its reason code, an explanation, and any parked
inventory. After off, the next gbrain apply-migrations --migration 0.53.0 --yes
reports the source as source_shared_skills_disabled and changes none of its
files or grants. on deletes the key; the default is on.
on cannot override the source kind. A connector-managed source stays
preserve_files and an unapproved external repository stays
explicit_pack_required, both with source_skill_adoption_required; status
says so instead of reporting the source as adopted.
Failure example: on a thin client, or from any connection other than the
brain host's own CLI, the command refuses with trusted_local_only. Its fix
is the same command for the host operator (actor: host_admin) and its verify
is the read-only status --json form. On a hosted brain, ask the host's
operator to run it there. An unknown action exits with invalid_params and
names the status form.
Verify: gbrain sources shared-skills <id> status --json, the shared_skills
object in gbrain sources status <id> --json, or
gbrain doctor --only shared_skills_sources, which lists opted-out sources.
Oversized skill packs
The migration inventories a pack within bounded limits. These database config
keys hold today's defaults; gbrain config set refuses a value above the
ceiling. Only the brain host's CLI writes them.
| Key | Default | Ceiling |
|---|---|---|
shared_skills.inventory.max_files |
256 | 4096 |
shared_skills.inventory.max_total_bytes |
4194304 (4 MiB) | 67108864 (64 MiB) |
shared_skills.inventory.max_file_bytes |
262144 | 8388608 (8 MiB) |
shared_skills.inventory.max_entries |
1024 | 16384 |
Symlinks, hard links, unsafe paths and the eight-directory depth limit are not configurable.
A pack over a bound parks its source once: the per-source migration record
holds parked (the bound, the limits in force and when it parked), the stage
reports payload_too_large with the next step, and the rest of the migration
completes instead of recording a partial run. Later runs skip the source
without re-reading the pack. Resume it in one of three ways, then run
gbrain apply-migrations --migration 0.53.0 --yes:
- Raise the named bound:
gbrain config set shared_skills.inventory.max_file_bytes 524288. - Opt the source out:
gbrain sources shared-skills <id> off. - Shrink the pack, then release it:
gbrain sources shared-skills <id> on.
gbrain doctor warns shared_skills_sources while a source is parked.
A pack whose adoption could never publish is refused at inventory instead of
after it: one canonical adoption writes one SKILL.md per declared skill plus
skillpack.json, at most 128 files (the persistence bundle bound), so a pack
declaring 128 or more skills reports payload_too_large as an action (not a
conflict) until it is split across sources or trimmed (#5476). This is separate
from the per-skill bound of 64 declared files.
Reviewed changes after inventory
When skill files change after the migration inventory, the inventory stage
reports a conflict that lists the changed paths and the exact acceptance
command with a digest of the current files. Review the changes with the user;
only after they agree run
gbrain apply-migrations --migration 0.53.0 --accept-reviewed-inventory <source>=<digest> --yes.
A later edit changes the digest, so the old command is refused again. Hashes
are byte-exact, so a checkout that rewrites line endings (CRLF on Windows)
counts as a change: pin *.md text eol=lf in .gitattributes before
inventorying. An inventory that never completed (for example, the root was
missing or wrong when it ran) is simply taken again at the corrected root; a
completed inventory whose root moved still refuses (#5569).
An install whose 0.53.0 migration already shows as wedged (three partial runs
before parking existed) resumes with
gbrain apply-migrations --force-retry 0.53.0, then
gbrain apply-migrations --migration 0.53.0 --yes; the oversized source parks
and the migration completes.
A 0.53.0 migration wedged on a source conflict is reported by gbrain doctor,
gbrain apply-migrations --dry-run and post-upgrade, each naming the sources
in conflict, the code and the next step; ordinary commands say nothing about it
once a newer migration has completed. Run
gbrain apply-migrations --migration 0.53.0 --dry-run --json (it changes
nothing) to see each source's state, then settle each conflict with the user.
For shared_skills_unmanifested (skills in the source's skills/ folder that no
skillpack.json declares), declare the ones to share in a skillpack.json at
the source's root, or keep the source out with
gbrain sources shared-skills <id> off. Doctor stops warning once the preview
has inspected every source and finds none in conflict; a source whose policy it
could not read (a dropped database connection, for example) keeps the warning.
Don't clear the wedge with --force-retry for this:
the next --yes run would also publish each source's pending shared-skills
content.
Troubleshoot, leave, and recover
Inspect this installation's local receipt without credentials or a live host:
gbrain connect --harness codex --status --json
Use the installation's actual harness and connection --name; thin CLI
installations also need their explicit persistent --root. Status reports
desired/installed/acknowledged views, the last authority-check time, pending
files, retained-file count, and remote cleanup state. It does not make a
fresh authority probe: current_authority: unprobed and native_use: unverified
remain explicit. For bootstrap-managed wiring use its bootstrap receipt/status
rather than assuming it shares a connect installation's receipt path.
| State | Safe next action |
|---|---|
writer_not_quiesced |
Stop and exclude old filesystem writers and direct-file skill servers; claim exact roots and activate the shared writer protocol on the host. A confirmation flag cannot stop those processes for you. |
catalog_unavailable / stale_unavailable |
Keep installed files and cursor state; retry the current authorized view. Do not treat failure as an empty catalog or activate a stale cached skill. |
full_resync_required |
Discard the pagination cursor and enumerate again under current authority. |
requirements_changed / approval_required |
Have the owner review the changed disclosure, tools, source, or follow policy. Do not self-grant permissions. |
revision_conflict / local_conflict |
Preserve both edits and inspect current revisions/ownership receipts before retrying. |
restart_required |
Restart the harness and record actual new-conversation evidence. Files alone do not clear this check. |
left_with_retained_files |
Preserve the reported edits, disable native cached instructions through the harness controls, and restart. |
membership_inactive |
The receipt's enrollment epoch was left or superseded. See membership inactive after a re-enrollment. |
Membership inactive after a re-enrollment
Say to your agent: "My shared skills say membership inactive; refresh them."
The agent runs gbrain bootstrap harness --refresh-skills on the harness host.
A leave_brain then join_brain by the same principal (for example to bind a
follow policy the owner approved later) moves the server's enrollment epoch
on, while the receipt and native router keep the old one, so the router's
sync_brain_skills call answers membership_inactive. For a
bootstrap-managed installation:
gbrain bootstrap harness --refresh-skills
gbrain bootstrap harness --status
--refresh-skills re-joins each live entry under its recorded credential
and follow policy, so the receipt and router adopt the current epoch; no
token is minted or revoked. --status prints each entry's receipt epoch, and
gbrain doctor warns bootstrap_harness_health (code
shared_skills_epoch_superseded) when the receipt epoch differs from the
brain's membership row. A refresh whose recorded policy is wider than the
active membership answers follow_approval_required: leave and re-run
gbrain bootstrap harness after owner approval. A rotation leave whose own
epoch was superseded completes locally (remote_membership_reason: superseded) so the previous token can be revoked.
leave_brain stops this principal's membership. The managed adapter's leave
path also removes unchanged owned files; changed files are retained. Neither
leaving nor connect ... --remove revokes credentials, deletes memory, removes
history, or proves that native cached instructions stopped running. Revoke
access separately on the host when intended. Previously downloaded bytes
cannot be recalled, and forget is withdrawal from active memory, not physical
erasure of source material, history, or backups.
Managed removal disables local following and attempts owned-file cleanup even
when offline or already revoked. remote_membership_pending: true means the
host has not acknowledged leave; retry remote cleanup when possible. A
bootstrap-managed enrollment whose credential is already revoked cannot leave
remotely; gbrain bootstrap harness finishes its local cleanup and records it
as left with reason credential_revoked, because a revoked principal's
membership is inert (cleanup pending). Do not
claim a server-side departure from successful local deletion, or delete edited
files to make the status look complete.
There is no automatic content rollback command. To roll back content, an authorized editor reviews an allowed, retained prior revision and republishes its complete files with a new request ID and the current expected revision. Policy rollback is a separate owner decision. Do not lower the writer floor, run an older binary against the activated database, or assume a Git checkout rebuilds permissions or revision history.
Interrupted publications use durable recovery records; unexpected human edits fence the root rather than being overwritten. Preserve the database, staging files, receipts, and root when recovery is pending. Use the current writer's recovery procedure, not manual journal deletion.
Canonical files can reconstruct content, but operational DB state also needs a protected, tested backup: grants, memberships, policy/audit history, revocations, serving identity, and write/delivery receipts are not all in Git. A stale backup may omit a later revocation or withdrawal. Do not clone a live operational database and present both copies as independent brains.
Restore a local archive as a new brain
For supported local PGLite installations, create a private archive with
gbrain backup create --output /absolute/private/brain.gbrain-backup after
pausing writers. It contains sensitive full DB state and installer-managed
files, not every canonical content root, even on the same disk. Inspect the
archive's omitted inventory and back up excluded canonical files separately.
Backup coverage checks and a Git remote are not substitutes for an operational
archive.
Restore only into a new, absent root whose parent already exists:
gbrain backup restore /absolute/private/brain.gbrain-backup \
--into /absolute/restored-brain --json
An archive with shared-skill storage restores as a new independent, unpublished brain. Restore changes the brain ID and serving epoch/key, deactivates memberships and leases, revokes archived credentials and local writers, detaches canonical owners, and disables skill publication/following. Knowledge, retained revision history, and the writer protocol floor remain; unfinished work is quarantined, not automatically restarted. The original installation is not overwritten.
Read restore-receipt.json, reconnect_required, and
.gbrain/restore-detached.json. Restore does not publish a launcher or start
automation. Repair the runtime through the recorded in-agent setup path when
applicable, review restored content, claim the correct restored roots, recheck
writer quiescence, establish publication policy, and issue new credentials
before serving. A backup with unresolved file recovery fails with
restore_recovery_required; preserve the archive/source installation, reconcile
recovery with its current owner, and make a new backup.
Recover the same brain identity
For a compatible local operational archive, an explicit recovery mode preserves the brain ID while still rotating the serving epoch/key, revoking archived credentials and memberships, detaching owners, and disabling publication:
gbrain backup restore /absolute/private/brain.gbrain-backup \
--into /absolute/recovered-brain --mode recovery \
--confirm-quiesced --confirm-backup-compatible --confirm-authority-reviewed \
--json
All three confirmations are required. They record operator attestations, not proof that the old service stopped or that the archive contains later revocations and withdrawals. Exclude the old service externally, validate the archive against current authority and withdrawal records, review the recovery receipt, and reissue access before serving. Missing compatible authority metadata or unresolved file recovery still refuses recovery; flags cannot bless an incomplete archive.
External PostgreSQL dump restoration remains an operator-managed procedure with the same offline validation, old-service exclusion, and authority reissue requirements. A stale backup cannot tell you which newer withdrawals or revocations it lacks.
Concurrent publication and engine choice
PGLite's single backing connection serves both reads and atomic bundle publication. Frequent publications can delay shared-skill body and asset reads, especially as the generated pack inventory grows. PostgreSQL is the preferred engine for write-heavy shared catalogs. This is a latency consideration, not permission to return partially published files or stale authorization.
The reproducible lifecycle workload reports correctness, read latency and publication costs separately. A successful delivery test or memory-search latency gate is not a passing shared-asset latency result, and no benchmark proves native harness activation.
Acceptance checklist
- Protocol: discover only granted sources; fetch an exact revision and its approved dependency manifest; verify a committed edit reaches both a second principal and the parent. Check forbidden-source and revoked access fail.
- Files: check ownership receipts, hashes, pending/retained files, and the recorded absolute launcher or named MCP connection. An edited native shadow copy is unresolved until safely excluded with the user's authorization.
- Native new conversation: record the exact harness/version and observe it choose the relevant skill without being told its name, then use the new revision after refresh/restart. Missing platform access stays unverified.
Keep these evidence levels separate. See harness validation for the release checklist; this guide is not a claim that those tests ran on your installation.