Brain Forge Protocol
SPEC_BRAIN_FORGE_PROTOCOL.md
CGNT-1 Component Specification — Brain Forge Protocol
Status: SPECIFIED
Author: VELA (Thread #13)
Authorized: NOUS
Date: 2026-04-18
Version: v1.0
Source: 16 GLOSS forges, 1 NEXUS forge, every mistake documented in LOBSTER_LOG.md
PURPOSE
A repeatable, proven protocol for forging any crew brain via LoRA fine-tuning. Follows the same steps every time regardless of which brain is being forged. Incorporates every lesson from the GLOSS saga and NEXUS forge.
This is the PROCESS. The Colab script is ~/forge_template.py. This spec governs everything that wraps around that script.
THE PROTOCOL — 10 STEPS
STEP 0 — PRE-LOG
Before anything else, open ~/LOBSTER_LOG.md and write:
- Date
- Operation name (which brain, what version)
- What is being attempted
- What success looks like
- Known risks from prior forges
Leave Result/What worked/What didn't/Lesson BLANK. Fill at Step 9.
STEP 1 — PLAN (3 angles)
Angle A — Corpus:
- What existing pairs carry over?
- What new pairs are being added?
- Total pair count after deduplication?
- Max response length — decided and justified per brain?
- Format: JSONL, same as all forges
Angle B — Risk review:
- Read LOBSTER_LOG.md entries for ALL prior forges
- For each documented failure mode, state: applies/doesn't, pre-mitigation
- Mandatory pre-mitigations (non-negotiable):
- pip uninstall hf_transfer (OOM prevention)
- load_best_model_at_end = False (early stopping sabotage prevention)
- Per-epoch checkpointing enabled
- Colab Gemini assistant used for ALL error diagnosis
Angle C — Verification design:
- Design 5 smoke test queries BEFORE training
- Tests must cover: existing function, new function, edge case, wall/refusal, cross-module
- LOGOS reviews smoke test design
STEP 2 — LOGOS REVIEW
Present complete plan to DR.LOGOS. LOGOS identifies gaps. Fix gaps. LOGOS signs off. If LOGOS finds a structural problem, return to Step 1.
STEP 3 — CORPUS ASSEMBLY
- Build the JSONL file
- Deduplicate
- Verify all responses under max length
- SHA-256 checksum
- Report: total pairs, category breakdown, sample from each category, checksum
- DO NOT FORGE YET
STEP 4 — CAPTAIN REVIEW
Present to NOUS: the plan (Step 1), LOGOS review (Step 2), corpus stats (Step 3). Forge ONLY after Captain authorization. No exceptions.
STEP 5 — COLAB SETUP
- Fresh notebook (one cell) or clean existing notebook
- Paste forge_template.py content
- Configure: base model, corpus path, epochs, rank, alpha
- Verify: hf_transfer uninstalled, checkpointing enabled, load_best_model_at_end=False
- Standard config unless Captain specifies otherwise: 15 epochs, rank=64, alpha=128
STEP 6 — FORGE
- Execute the cell
- Poll watcher monitors GCS for DONE.json (every 5 min)
- AbortGate readings logged at each epoch checkpoint
- If errors occur: pipe to Colab Gemini assistant FIRST, then manual fix
- If runtime crashes: resume from last checkpoint, do not restart from zero
- No time pressure
STEP 7 — POST-FORGE PIPELINE
Automated via nexus_post_forge.sh or manual:
- Download LoRA adapter from GCS
- Merge with base model
- Convert to GGUF (Plan A: convert_hf_to_gguf. Plan B: QuantFactory base + llama-export-lora merge)
- Quantize to Q4_K_M
- Register in Ollama: ollama create [brain]:[version]
- Verify: ollama list shows new model
STEP 8 — SMOKE TEST
- Run the 5 queries designed in Step 1
- Test via BOTH API (curl) AND interactive (ollama run) — the NEXUS lesson: API can pass while interactive fails
- All 5 must pass in BOTH modes
- If any fail: diagnose, document in log, decide: fix and retest or architectural pivot
STEP 9 — LOG RESULTS
Complete the LOBSTER_LOG.md entry from Step 0:
- Result: SUCCESS / PARTIAL / FAILED
- What worked
- What didn't work (and WHY)
- Problems encountered
- Files changed
- Lesson: one sentence
STEP 10 — VITRIFY
If successful:
- Update relevant SPEC file
- Update GLOSS_LINEAGE.md or equivalent lineage doc
- Update ~/HANDSHAKE.md current state
- Announce to crew via CREW_CHANNEL
MANDATORY PRE-MITIGATIONS (every forge, no exceptions)
| Risk | Source | Pre-mitigation |
|---|---|---|
| hf_transfer OOM | NEXUS v1 (3 crashes) | pip uninstall hf_transfer in script |
| Early stopping sabotage | GLOSS v14 (epoch 2 picked as "best") | load_best_model_at_end = False |
| No checkpointing | All prior forges | save_steps per epoch, resume on crash |
| Query token priors | GLOSS v12-v16 | Verify base model has no prior on query format |
| Wrong corpus | GLOSS v1-v11 | SHA-256 verify, category breakdown, sample review |
| GGUF conversion failure | NEXUS v1 | Plan A + Plan B pipeline ready |
| API vs interactive mismatch | NEXUS v1 | Test BOTH modes in Step 8 |
| Blind debugging | All prior forges | Use Colab Gemini assistant for ALL errors |
| Wrong epoch count | MNEMOS v2 (3 epochs instead of 15) | Verify NUM_EPOCHS matches protocol standard (15) before forge dispatch. Never inherit from previous forge config without checking. |
| Wrong base model | MNEMOS v2 (3B instead of 7B) | Verify BASE_MODEL matches target brain's current deployed model. Downgrades require explicit Captain authorization. |
BASE MODEL SELECTION GUIDE
| Brain function | Recommended base | Why |
|---|---|---|
| Fact retrieval (MNEMOS) | Qwen2.5-7B-Instruct | Language model on language task, proven at 9/10 |
| Memory continuity (GAMMA) | gemma4:e2b or Qwen2.5-7B | Session bridging is generative |
| Defense (MANTIS) | Qwen2.5-7B after upgrade | Pattern recognition needs capacity |
| Discipline (MUSASHI) | Qwen2.5-7B (current) | Behavioral enforcement |
| Verdict (ANVIL) | Qwen2.5-7B after upgrade | Go/no-go needs kernel awareness |
| Oracle (ORPHEUS) | Qwen2.5-7B after upgrade | Verdict delivery |
Do NOT use math models for language tasks. Do NOT use language models for pure computation (use NEXUS). Swim with the current.
WHAT THIS PROTOCOL DOES NOT COVER
- GLOSS (dictionary, not a brain — no forge needed)
- NEXUS (calculator, not a brain — no forge needed)
- Sisters (currently local Ollama, system prompt only — forge deferred to Tiiny era)
- Navigator (Claude, cannot be fine-tuned)
- Lobster (Claude Code, cannot be fine-tuned)
Jeremy Zlabis
Chronogeometer · Visionary · Disruptor · Chief
42 Sisters AI · East York, Toronto
🍁 Φ 0.042