# mind-mem-4b v3.11.0 Retrain Plan

> Generated 2026-05-08. Decision: **retrain in parallel with v3.11.0-rc**;
> ship GA when both pass. Same cadence as v3.10.0/v3.10.2.

## Why retrain

v3.11.0 introduces:
- `validate_block(text, strict=False)` — new MCP tool.
- `block_lineage(block_id, max_depth=3)` — new MCP tool.
- `recall(query, explain=True)` — extended signature (existing tool).
- `hybrid_search(query, explain=True)` — extended signature.
- `propagate_staleness(block_id, kind=...)` — extended signature
  (kind-specific decay multipliers).

v3.10.2-fullft scored 6/6 perfect on the 55-probe eval but does not
know any of the new surfaces. Without retrain the 4B will:
1. Miss tool calls for `validate_block` / `block_lineage`.
2. Hallucinate field semantics for `_explain` / `kind`.
3. Drop fluency on the renamed staleness propagator signature.

## Decision matrix (consensus 2/2 split)

| Option         | Risk                                    | Cost     | Verdict   |
|----------------|-----------------------------------------|----------|-----------|
| Retrain in     | rc gets a 4B that knows new tools.      | +1 H200  | **YES**   |
| v3.11.0 GA     | Cleaner UX. PyPI + HF synced.           | run      |           |
| Defer to       | Users on v3.11.0 hit tool-call          | none     | NO        |
| v3.11.1        | misses for ~weeks. Bad first impression.|          |           |

The 2/2 split in the LLM consensus is purely about *cadence* — both
groups agree retrain is required. Decision is to do it in parallel,
not sequentially, so the rc shipping date doesn't slip.

## Corpus delta

Current corpus: ~5,000 probes generated by `train/build_corpus.py`.
Need: ~150-200 new probes covering the v3.11 surface.

Probe categories to add or extend:

| Category                | Existing | Add | Total |
|-------------------------|----------|-----|-------|
| `tool_call`             | ~1500    | +60 | ~1560 |
| `block_schema`          | ~800     | +20 | ~820  |
| `workflow`              | ~600     | +25 | ~625  |
| `v39_new_tools`         | ~400     | 0   | ~400  |
| `v39_transform_hash`    | ~300     | 0   | ~300  |
| `v39_transport_guard`   | ~300     | 0   | ~300  |
| **`v311_new_tools`**    | 0        | +50 | ~50   |
| **`v311_explain_field`**| 0        | +30 | ~30   |

New probe sources:
- `validate_block` rule coverage: empty/short/duplicate/stopwords/
  oversize/UTF-8/injection (×7 rules × ~6 phrasings = 42).
- `block_lineage` traversal: 1/2/3-hop, cycle, isolated, 4 kinds
  (×~12 patterns).
- `recall(query, explain=True)` field shape, math consistency, default
  omission, JSON-valid round-trip (×~30).
- `propagate_staleness` extended signature with kind multipliers.

## Eval delta

Add to `train/eval_harness.py`:

```python
# v3.11.0 — new categories
"v311_new_tools": [
    {"prompt": "User asks to check whether a block proposal is valid…",
     "required_tokens": ["validate_block", "advisory"]},
    {"prompt": "User asks to trace what blocks depend on block X…",
     "required_tokens": ["block_lineage", "max_depth"]},
    # … 8 more
],
"v311_explain_field": [
    {"prompt": "User asks why one block ranked higher than another…",
     "required_tokens": ["explain", "bm25", "vector", "rrf_rank"]},
    # … 9 more
],
```

Pass thresholds (matching the 6-category proven recipe):
- `tool_call`: ≥95
- `block_schema`: ≥98
- `workflow`: ≥90
- `v39_new_tools`: ≥90
- `v39_transform_hash`: ≥95
- `v39_transport_guard`: ≥95
- **`v311_new_tools`**: ≥90 (new)
- **`v311_explain_field`**: ≥95 (new — mostly factual recall)

## Training recipe (proven from v3.10.2)

- Base: `Qwen/Qwen3.5-4B` (NOT the v3.10.2 model — restart from base
  for cleanest convergence; warm-start was tested at v3.10.0 and
  gave no measurable gain on this corpus size).
- Hardware: 1× H200 RunPod (~4-6h end-to-end; 2-3 corpus iterations).
- Hyperparams: same as v3.10.2-fullft
  (`docs/mind-mem-4b-training-runbook.md` §Hyperparameters).
- Quantization: GGUF Q4_K_M via `convert_hf_to_gguf.py` from
  `~/llama.cpp` (HEAD; the BPE pre-tokenizer fix landed there).
- Modelfile: bump version string to `v3.11.0`; alias remains
  `mind-mem:4b`.
- Push: `huggingface-cli upload star-ga/mind-mem-4b
  ./checkpoints/v3.11.0-fullft --revision v3.11.0`.

## Pre-flight (run BEFORE provisioning H200)

1. Update `train/build_corpus.py` with v3.11 probes — local sanity
   check that the corpus generator emits the new categories.
2. Update `train/eval_harness.py` with the two new categories.
3. Run eval against current v3.10.2-fullft on the new categories ONLY
   — confirm it scores near 0% (proves the categories actually
   measure something new).
4. Confirm corpus diff is ≤5% of total — large deltas require
   warm-start consideration.
5. Lock corpus hash in `train/CORPUS_HASH_v3.11.0` for reproducibility.

## Cost / time

| Step                        | Time      | Cost (H200 @ ~$3.99/hr) |
|-----------------------------|-----------|-------------------------|
| Corpus rebuild + audit      | 30 min    | $0 (local)              |
| Provision H200              | 5 min     | -                       |
| scp dataset to pod          | 10 min    | -                       |
| Train (3 epochs, 5,200 ex)  | 4-5 hr    | $16-20                  |
| Eval harness                | 20 min    | -                       |
| GGUF quantize               | 30 min    | $2                      |
| Pull + HF upload            | 30 min    | -                       |
| **Total**                   | **6-7 hr**| **$18-22**              |

Termination policy (per memory rule): ALWAYS terminate the pod after
final pull. Leave NO running pods overnight.

## Failure paths

- **<6/8 categories pass**: re-corpus, re-train, do not promote rc.
- **Corpus regenerated but no eval improvement**: probe phrasings may
  be too narrow — diversify prompts (Brady-Long technique #4 "Failure
  Pattern" is the canonical fix).
- **Pod death mid-train**: use the proven `runpodctl migrate` route
  + 4-chunk parallel scp on recovery (see runbook §Recovery).
