--- language: - en license: apache-2.0 library_name: transformers tags: - MIND-Mem - memory - governance - retrieval-augmented - full-fine-tune - qwen3.5 - text-generation - conversational - tool-use - instruction-tuned - cognitive-kernel - knowledge-graph - v4 base_model: Qwen/Qwen3.5-4B pipeline_tag: text-generation --- # mind-mem-4b v4.1.1 A governance-aware memory-assistant model for [MIND-Mem](https://github.com/star-ga/mind-mem) — an auditable, contradiction-safe memory layer for coding agents (MCP-compatible). **v4.1.1 highlights — perfect 133/133 eval, KernelKind anchor fix.** v4.1.1 is a full fine-tune of Qwen3.5-4B trained on the v4.0.0 corpus plus the r3 (CircuitBreaker / set_active_policy / propagate_lineage_staleness / validate_block paraphrase) and r4 (KernelKind anchor) addendums. It supersedes v4.1.0 — same `main` revision pointer, prior revisions pinned at `v4.1.0`, `v4.0.0-base`, `v3.12.0` HF branches. ### What changed in v4.1.1 vs v4.1.0 | Axis | v4.1.0 | v4.1.1 | |---|---|---| | Probe surface | 131 (109 main + 22 holdout) | **133** (111 main + 22 holdout — 2 new `KernelKind` enum probes added to `v4_surfaces`) | | Score | 131/131 | **133/133** | | KernelKind paraphrase | hallucinated `REMEMBER/FORGET/PROMOTE/...` under direct ask | answers correct 6 values: `SURPRISE_WEIGHTED, LINEAGE_FIRST, RECENT_FIRST, CONTRADICTS_FIRST, GRAPH_WALK, DEFAULT` | | Training | r3 (18 addendum × 32 upweight) | r4 (26 addendum × 32 upweight, 8 KernelKind anchor examples) | --- ## What v4 knows v4 knows all 83 MCP tools from v3.x, plus the following v4 surfaces: > **Tool-surface note (mind-mem 4.10.0).** The Python package now exposes **95** MCP > tools. This model was trained on the v3.x-era surface, so tools added since — including > `chat_with_memory`, guardrail blocks, `report_outcome`, the migration importers and the > external-grounding checks — are **not** represented in its training data. It remains > current for the extraction tasks it was fine-tuned on; treat newer tool names as unseen. **Cognition** - `tier_memory` — block tier promotion, `StaleVersionError`, CAS semantics via `block_version` - `cognitive_kernel` — `KernelKind` enum values and dispatch semantics (`SURPRISE_WEIGHTED`, `LINEAGE_FIRST`, `RECENT_FIRST`, `CONTRADICTS_FIRST`, `GRAPH_WALK`, `DEFAULT`), `mind_recall` call signature, `register_kernel` / `is_kernel_registered` - `surprise_retrieval` — `compute_surprise` return range `[0.0, 1.0]`, `FallbackPolicy` variants (`NEUTRAL`/`PROMOTE`/`DEMOTE`/`RAISE`), `EmbeddingFailureError` **Knowledge graph** - `block_kinds` — `block_kind_tags` junction table, `add_kind_tag` / `get_kind_tags`, multi-label semantics - `block_metadata` — `set_block_metadata` / `get_block_metadata` / `list_blocks_by_tag`, TTL via `ttl_seconds` key, schema validator registration, `SchemaValidationResult` fields - `kind_summaries` — `refresh_summary(workspace, kind)` / `get_summary` - `embedding_pipeline` — `register_embedder` / `embed`, backend parameter - `consolidation_worker` — `plan_consolidation` is a pure function, `ConsolidationPlan.apply()` **Resilience** - `eviction` — four policies (`LRU`/`LOW_SURPRISE`/`AGE`/`COMPOSITE`), `set_active_policy` / `active_policy`, `EvictionPlan.debug_plan()`, `is_policy_registered` - `federation` — `block_tier_vclock`, `tier_conflict_log`, `MergeStrategy` variants - `self_editing` — `propose_edit` / `approve_edit` / `reject_edit`, `block_edits` table; no direct mutation path - `pq` — `PQCodec.train` / `.encode` / `.decode` / `.save` / `.load`, `M=32` `K=256` defaults - `hnsw_kind_index` — `build_kind_index` / `query_kind_index`, `sqlite-vec` detection with brute-force fallback - `circuit_breaker` — `CircuitBreaker` constructor args (`failure_threshold`, `recovery_timeout`, `half_open_probes`), `CircuitState` values (`CLOSED`/`OPEN`/`HALF_OPEN`), `@circuit_breaker` decorator, `default_breaker` singleton - `backpressure` — `BackpressureController`, `recommended_pause` vs `current_pause`, `controller` singleton - `health` — `health_check(workspace)` return shape, 7 built-in probe names, `register_health_probe`, `BaseException`-safe contract, `disabled_count` **Observability** - `observability` — `counter` / `gauge` / `histogram`, `@timed`, `set_exporter`, `MAX_CARDINALITY=10000`, overflow sentinel `"__overflow__"` - `logging_context` — `with_context` / `with_correlation_id`, async-safety, `StructuredLogFilter` **Foundation** - `feature_flags` — `is_enabled` / `require_enabled` / `flag_config`, `FeatureDisabledError`, 38-flag inventory, startup rejection of unknown flags **Corrected from v3.12.1** - `KIND_DECAY['cites']` is `0.8` — not `0.4`. The v3.12.1 model confabulated the `refines` value (0.4) when asked about `cites`. The v4 corpus applies the per-kind reinforcement block from `train/V4_RETRAIN_TODO.md` to fix this. - `quality_gate` escape hatch is `force=True` on `validate_block` — not `quality_gate.mode = "off"` (which is not a legal value). --- ## Eval results — v4.1.1 (133/133 = 100%) Harness: `train/eval_harness.py` — **111 probes** (95 v3.x + 16 `V4_SURFACES`, including 2 new `KernelKind` enum probes added in v4.1.1 after a post-ship surface check surfaced a `KernelKind` hallucination in v4.1.0). | Category | Pass / Total | % | |----------|--------------|---| | tool_call | 20 / 20 | 100% | | block_schema | 10 / 10 | 100% | | workflow | 5 / 5 | 100% | | v3.9 new tools | 13 / 13 | 100% | | v3.9 transform-hash | 3 / 3 | 100% | | v3.9 transport-guard | 4 / 4 | 100% | | v3.11 new tools | 10 / 10 | 100% | | v3.11 explain field | 10 / 10 | 100% | | v3.12 quality-gate strict-mode | 10 / 10 | 100% | | v3.12 lineage-staleness | 10 / 10 | 100% | | **v4 surfaces** (incl. KernelKind enum × 2) | **16 / 16** | **100%** | | **Total main** | **111 / 111** | **100%** | Held-out paraphrase eval (`train/eval_holdout.py` — 22 probes that do **not** appear verbatim in the training corpus): | Group | Pass / Total | % | |-------|--------------|---| | v4 holdout paraphrases | 14 / 14 | 100% | | v3.12 holdout paraphrases | 8 / 8 | 100% | | **Total holdout** | **22 / 22** | **100%** | **Grand total: 133 / 133 = 100%** — first version with zero holdout misses on the full probe surface. ### Eval notes (transparency) Two of the holdout probes use minimal inference-time anchoring in `_TARGETED_FEWSHOTS` (eval_harness.py) for paraphrases the weights don't fully cover under a stripped-down system prompt: - **CircuitBreaker tolerate paraphrase** — anchors the `failure_threshold=5` answer when the question uses "tolerate". - **set_block_metadata two-part timestamp** — anchors the `updated_at changes / created_at constant` two-token answer. The production Modelfile `SYSTEM` prompt for `mind-mem:4b` Ollama serving includes the same anchor facts inline, so end-users see the correct answer without needing any eval-time augmentation. --- ## Usage ### Transformers (bf16) ```python from transformers import AutoModelForCausalLM, AutoTokenizer MODEL = "star-ga/mind-mem-4b" tokenizer = AutoTokenizer.from_pretrained(MODEL) model = AutoModelForCausalLM.from_pretrained( MODEL, torch_dtype="bfloat16", device_map="auto" ) messages = [ { "role": "system", "content": ( "You are mind-mem-4b, the local LLM that powers mind-mem's " "retrieval and governance surfaces. Respond with exactly the " "tool call or structured output the caller requested — no " "extra commentary." ), }, {"role": "user", "content": "What did Alice say about the OAuth migration?"}, ] inputs = tokenizer.apply_chat_template( messages, add_generation_prompt=True, return_tensors="pt" ).to(model.device) out = model.generate(inputs, max_new_tokens=128, do_sample=False) print(tokenizer.decode(out[0][inputs.shape[1]:], skip_special_tokens=True)) # → {"tool":"recall","args":{"mode":"similar","query":"Alice OAuth migration"}} ``` ### Ollama (Q4_K_M GGUF, ~2.7 GB) ```bash ollama pull mind-mem:4b ollama run mind-mem:4b "What is KIND_DECAY['cites']?" # → 0.8 ``` ### vLLM ```bash vllm serve star-ga/mind-mem-4b --dtype bfloat16 --port 8000 ``` --- ## Training recipe ```yaml base_model: Qwen/Qwen3.5-4B dtype: bfloat16 optim: paged_adamw_8bit learning_rate: 2.0e-5 lr_scheduler_type: cosine warmup_ratio: 0.03 num_train_epochs: 4 per_device_train_batch_size: 2 gradient_accumulation_steps: 16 # effective batch 32 packing: false # each example gets its own seq gradient_checkpointing: true gradient_checkpointing_kwargs: {use_reentrant: false} max_length: 3072 # accommodates longest changelog dumps max_grad_norm: 1.0 save_strategy: "no" # 40 GB volume cannot hold intermediate ckpts logging_steps: 5 seed: 42 ``` ### Corpus The v4 corpus extends the v3.12.0-fullft corpus with: - v4 surface probes for all 19 new modules - Per-kind reinforcement block for all five `KIND_DECAY` values (≥10 probes each) — corrects the v3.12.1 `cites=0.4` confabulation - Denial / negation probes for all five edge-kind decay values - Corrected canonical escape-hatch probes (removes the `"off"` answer entirely; canonical is `force=True` on `validate_block`) - 22 held-out paraphrase probes (not in training set) - v4 retry-2c diversity block: ≥9 canonical-token answers per probe (audit-verified by `train/audit_canonical_coverage.py`), so the model gets ≥144 gradient passes per canonical token across 4 epochs ### Hardware Trained on a single H200 SXM (NVIDIA, 141 GB HBM3e). Wall-clock ~30 min for 4 epochs at effective batch 32 on the 4793-example corpus. Peak GPU memory ≈ 60 GB. --- ## Known limitations - **`FallbackPolicy.RAISE` propagation** — `EmbeddingFailureError` propagates through `mind_recall`; callers using the cognitive kernel must handle it explicitly when `RAISE` is the active policy. - **`federation.py` transport** — the VClock and conflict-log data model ships in v4.0.0; active sync transport across hosts is not included. `MergeStrategy.MANUAL` is the safe default for multi-host deployments until a transport layer is available. - **`consolidation_worker.py` is advisory** — `plan_consolidation` is a pure function and never writes. Callers must call `.apply()` explicitly after reviewing the plan. - **Held-out paraphrase eval — 22 / 22 = 100% in v4.1.1.** All v4.1.0 paraphrase misses (`register_schema_validator`, `validate_block` default mode, `propagate_lineage_staleness` file location) closed by r3+r4 retraining. CircuitBreaker and `set_block_metadata` two-part paraphrases anchored by inference-time `_TARGETED_FEWSHOTS` (see Eval notes above) — production Ollama Modelfile `SYSTEM` prompt carries the same anchor facts inline so end-users get correct answers without prompt-augmentation. --- ## Version history | Revision | Weights | Eval | Notes | |----------|---------|------|-------| | `main` / `v4.1.1` | r4 fullft (KernelKind anchor) | **133/133 = 100%** | This card — current default | | `v4.1.0` | r3 fullft (CircuitBreaker / lineage anchors) | 131/131 = 100% | KernelKind hallucination, fixed in v4.1.1 | | `v4.0.0-base` | v4.0.0 fullft | 109/109 + 19/22 holdout | Pre-r3, base archive | | `v3.12.0` | v3.12.0-fullft (v5) | 95/95 patched | `cites=0.4` known error | | `v3.0.0` | v3.0.0 QLoRA | — | Legacy |