gbrain-maintain

Detects and fixes orphan pages, stale content, contradictions, and embedding failures in gbrain knowledge bases.

1|Updated Jun 21, 2026
One-click install
npx skills add https://github.com/tapway/shogun-os --skill gbrain-maintain-tapway
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: gbrain-maintain
Source: https://github.com/tapway/shogun-os/tree/main/skills/gbrain/maintain
Command: npx skills add https://github.com/tapway/shogun-os --skill gbrain-maintain-tapway

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Knowledge bases degrade over time: pages lose inbound links, content goes stale, embeddings fail silently due to credential issues, and contradictions accumulate. This Skill provides structured health checks and repair workflows to keep a gbrain knowledge base structurally sound. ## Core Features & Use Cases - Health Dashboard: Run mcp_gbrain_get_health() and mcp_gbrain_run_doctor() to get overall metrics and diagnostics with auto-fix suggestions. - Orphan & Stale Page Repair: Find pages with no inbound wikilinks and review content older than 180 days, adding back-links or review notes as needed. - Embedding Failure Troubleshooting: Diagnose OPENAI_API_KEY credential flow issues through the gbrain wrapper script, auth.json credential pool, and environment files, with a symptom-to-fix table. - Use Case: Run a daily quick check alerting when orphan_count > 50 or embed coverage < 90%, then execute the monthly maintenance checklist to fix orphans, resolve high-severity contradictions, and sync the brain repo. ## Quick Start Run a full brain health check and fix any orphan pages, stale content, and embedding failures you find.

Frequently Asked Questions about gbrain-maintain

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check the health of a gbrain knowledge base?

Run mcp_gbrain_get_health() for an overall dashboard and mcp_gbrain_run_doctor() for deep diagnostics with auto-fix suggestions. Alert thresholds are orphan_count over 50, stale_count over 100, or embedding coverage below 90%.

How do I find and fix orphan pages in gbrain?

Use mcp_gbrain_find_orphans() to list pages with no inbound wikilinks. For each orphan, decide if it should have inbound links; if yes, add back-links from referencing pages, otherwise leave standalone reference pages alone.

Why does gbrain embedding fail with OPENAI_API_KEY errors?

The error occurs when the gbrain wrapper script fails to resolve the API key before calling the TypeScript CLI. Check that the wrapper sets OPENAI_BASE_URL, that OPENROUTER_API_KEY exists in your environment, ~/.hermes/.env, or the auth.json credential pool, then re-run gbrain embed --stale.

When should I run embedding sync jobs in gbrain?

Only run gbrain embed --stale when embedding coverage drops below 95% or after fixing a credential failure. Running embed jobs when coverage is already high is wasteful and unnecessary.

Should I delete orphan pages that have no inbound links?

No. Many orphan pages are legitimate standalone references that simply need back-links added from related pages. Only pages that genuinely should not exist are deletion candidates; deleting useful orphans loses knowledge.