mind-mem-4b

mind-mem-4b v4.1.1

A governance-aware memory-assistant model for 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

---

What v4 knows

Runtime and checkpoint scope (2026-09-15). Published package mind-mem 5.0.3 exposes 107 registered MCP tools. These weights were trained against 83 tools at revision v4.1.1. Runtime registration does not extend the model's training coverage.

The runtime count is measured by scripts/count_mcp_tools.py; the trained count uses the same AST rule against the frozen training revision. The older count of 84 double-counted the recall registration. Changing this card does not retrain the weights or establish performance on the newer tool surface.

The historical 133/133 result below is the reported checkpoint evaluation, not a new independent evaluation of all current runtime tools. New training requires a frozen implementation and corpus, a held-out evaluation and a separately documented training run. Check model advice against current runtime documentation and the live tool list.

Package: https://pypi.org/project/mind-mem/5.0.3/ Source: 3226e4c7dcdfe2b9d0aaacc701b159bcc8c0fc78.

v4 knows all 83 MCP tools from v3.x, plus the following v4 surfaces:

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 — register_block_embedding / knn_by_kind / ensure_hnsw_schema / backend_status; brute-force cosine over the kind partition is the only backend (backend_status reports sqlite_vec_available as readiness, never as the serving path)
• 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. (This card said 35 through four releases; like the two-numbers-for-one-fact tool count above it, that figure was asserted, never measured. ALL_V4_FLAGS at the trained revision v4.1.1 holds 38 entries, and the live tree now holds 52 — so the weights do not know the newest 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).

Held-out paraphrase eval (train/eval_holdout.py — 22 probes that do not appear verbatim in the training corpus):

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)

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)

ollama pull mind-mem:4b
ollama run mind-mem:4b "What is KIND_DECAY['cites']?"
# → 0.8

vLLM

vllm serve star-ga/mind-mem-4b --dtype bfloat16 --port 8000

---

Training recipe

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

<!-- CORPUS_STATS -->

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