# MIND-Mem v3.3.0 release notes

**Platform-scale release.** Ships 12 v3.3.0 retrieval features, 8 v4.0
preview modules, a protection layer for shipped wheels, 7 new `.mind`
tuning kernels, and mind-mem-4b v2 (full fine-tune on H200 NVL
replacing v1's QLoRA checkpoint). No breaking changes — v3.2.1
deployments upgrade cleanly.

## Highlights

### v3.3.0 retrieval features (12)

Every feature ships a declarative `.mind` kernel so operators can
tune bounds without patching code:

| Module | Kernel | One-liner |
|---|---|---|
| `query_planner` | `mind/query_plan.mind` | Regex + LLM decomposition, SSRF-guarded |
| `graph_recall` | `mind/graph.mind` | BFS ±1-3 hops with per-hop decay |
| `entity_prefetch` | `mind/prefetch.mind` | PER/PRJ/TOOL/INC prefix matching + symlink guard |
| `session_boost` | `mind/session.mind` | Same-session score multiplier |
| `evidence_bundle` | `mind/evidence.mind` | Structured facts/relations/timeline/entities JSON |
| `rerank_ensemble` | `mind/ensemble.mind` | Borda fusion: CE + BGE-reranker-v2-m3 |
| `truth_score` | `mind/truth.mind` | Bayesian: prior × age_decay − contradictions |
| `answer_quality` | `mind/answer.mind` | self-consistency + regex verification |
| `streaming` | — | Token-bucket back-pressure queue |
| `consensus_vote` | — | Quorum with trust_weight fallback |
| `retrieval_trace` | — | ContextVar zero-cost tracing |
| `feature_gate` | — | Declarative FieldSpec + FeatureGate pattern |

### v4.0 preview modules (8)

- `event_fanout` — pluggable publishers (logging + Redis streams)
- `tenant_audit` — per-tenant HMAC-separated chains
- `tenant_kms` — AES-256-GCM envelope DEK encryption
- `governance_raft` — Raft-style consensus wrapper
- `api.grpc_server` — typed request/response dataclasses
- `storage.sharded_pg` — consistent-hash ring with virtual nodes
- `deploy/edge/pyoxidizer.bzl` — single-binary edge
- `web/` — Next.js console

### Protection layer

SHA-256 integrity manifest verified at import time. Set
`MIND_MEM_INTEGRITY=strict` to turn tamper detection into a hard
fault. 15-layer defence-in-depth documented in
[`docs/protection.md`](protection.md).

### mind-mem-4b v2

Full fine-tune of `star-ga/mind-mem-4b` on H200 NVL (v1 was QLoRA on
RTX 3080). 16,450 training examples, bf16, AdamW fused, cosine
schedule at LR 5e-6. Final loss 0.08 (converged). Published to
HuggingFace (replaces v1 on main branch) + Ollama local
(`mind-mem:4b`, Q4_K_M 2.7GB, v1 preserved as `mind-mem:4b-v1`).

## LoCoMo results

| | conv-0 | Notes |
|---|---|---|
| v1.1.0 | 70.54 | Original baseline |
| v3.2.1 (BM25) | 76.7 | Previous release |
| **v3.3.0 (BM25)** | **77.06** | 199 QAs, +0.36 over v3.2.1 |

Per-category conv-0: adversarial=92.98, temporal=98.12,
open-domain=74.87, single-hop=70.12, multi-hop=64.35.

### Known limitation

v3.3.0 feature experiment (query decomposition + rerank ensemble +
self-consistency) regressed full-bench to 70.05 — sub-query RRF-fuse
attenuates joint-reasoning bridges. Path to 85-90 documented in
[`docs/v3.4.0-roadmap-llm-consensus.md`](v3.4.0-roadmap-llm-consensus.md)
based on cross-model consensus:

1. **Hybrid BM25+BGE with RRF** (★★★★★ unanimous)
2. **UNION (not RRF) of original + decomposed sub-queries** (★★★★)
3. **Iterative retrieval** — the answerer generates 2nd-hop queries from
   1st-hop evidence (★★★★, raised unprompted by a majority of reviewers)
4. Graph expansion (already shipped but not wired into bench)
5. Chain-of-note evidence packing
6. Temporal metadata injection

## Install

```bash
pip install -U mind-mem==3.3.0
```

Existing v3.2.1 config is forward-compatible — no migration needed.

## Upgrading

```bash
mm install-all --force    # re-wires 16 AI clients with v3.3.0 tools
```

## Rollback

Pin the older version: `pip install 'mind-mem==3.2.1'` — all v3.3.0
features are opt-in via config (default auto-detection conservative).

## Tests

4035 selected / 4290 total. 16-job CI matrix: Ubuntu/macOS/Windows ×
Python 3.10/3.12/3.13/3.14.

## Release artifacts

- PyPI: https://pypi.org/project/mind-mem/3.3.0/
- HuggingFace model: https://huggingface.co/star-ga/mind-mem-4b
- GitHub release: https://github.com/star-ga/mind-mem/releases/tag/v3.3.0
- SBOM: attached to GitHub release (CycloneDX JSON)
- Signatures: Sigstore PEP-740 attestations on PyPI + GitHub release

## Credits

STARGA Inc. sole author. Cross-model review informed the v3.4.0
direction (recent research synthesized into the roadmap).
