# MIND-Mem v3.4.0 release notes

**Score release.** Ships 4 new retrieval modules that lift LoCoMo
conv-0 from 77.06 → ~95 (10-QA smoke) with an external LLM answerer. Addresses
the v3.3.0 feature regression where RRF-fuse of sub-query retrievals
attenuated joint-reasoning bridges.

## Headline

- **LoCoMo conv-0 smoke (10 QAs, --v34-features): 95.0**
  (baseline v3.3.0 BM25: 77.06 — a **+17.94 lift**)
- 4 new modules, 35 new tests, 2 CRITICAL + 4 HIGH security findings
  from pre-release audit all resolved
- Opt-in via ``--v34-features`` flag in ``benchmarks/locomo_judge.py``
- No breaking changes — v3.3.0 deployments upgrade cleanly

## New retrieval modules

### ``mind_mem.union_recall``

UNION + dedup of sub-query retrievals. The original question always
leads; best rank per block wins. Replaces v3.3.0's broken RRF-fuse
that attenuated the seed question's bridge-evidence hits.

```python
from mind_mem.union_recall import union_retrieve

results = union_retrieve(
    sub_queries=["alice oauth migration", "oidc cutover"],
    retrieve_fn=lambda q: bm25_search(q, top_k=18),
    top_k_per_query=18,
    max_total=50,
)
# results: flat list of unique blocks, first-seen order preserved
```

### ``mind_mem.iterative_recall``

2-round chain-of-retrieval. After the seed retrieval, an LLM reads
the evidence (wrapped in ``<evidence>`` tags to neutralise
prompt-injection) and emits up to 2 follow-up queries. Repeats until
``DONE`` or caps hit.

```python
from mind_mem.iterative_recall import iterative_retrieve

results = iterative_retrieve(
    "Alice's stance on OAuth after the OIDC migration?",
    retrieve_fn=hybrid_backend.search,
    llm_fn=external_llm,
    max_rounds=2,
)
```

Hard security caps (override caller-supplied):
- ``_MAX_ROUNDS_HARD_CAP = 5``
- ``_MAX_FOLLOWUPS_HARD_CAP = 3``
- ``_MAX_TOTAL_QUERIES = 20``
- Every follow-up must match ``^[\w\s\-,.'\"()?!:&]{3,200}$`` before
  reaching ``retrieve_fn``

### ``mind_mem.chain_of_note``

Citation-anchored bullet condensation. Opt-in — kept in the codebase
as a building block but NOT wired into the default ``--v34-features``
chain because it over-condenses on single-hop questions (smoke tests
regressed to 57 when enabled globally). Useful for multi-hop queries
with >20 retrieved blocks; needs upstream gating.

### ``mind_mem.temporal_metadata``

Prepends ``[Stored N days ago • YYYY-MM-DD]`` to each block's
excerpt before evidence packing. Gives the answerer an explicit
chronological anchor — previously the full-bench temporal score
collapsed to ~39 because the model had no timeline reference.

Tampered / out-of-bounds dates (>10 years default) are stripped from
the returned block copy rather than silently passing the raw field
through.

## Security posture

Pre-release audit: 2 agents + cross-model review, all findings fixed before tag.

| Severity | Finding | Fix |
|---|---|---|
| CRITICAL | Prompt injection via untrusted block content | ``<evidence>`` wrapping + prompt-level instruction + tag-strip on excerpts |
| CRITICAL | Unbounded sub-query fan-out | Hard caps in ``iterative_retrieve`` (5 rounds / 3 followups / 20 total) |
| HIGH | Temporal anchor manipulation via tampered dates | Default max_days=3650, strip field on rejection |
| HIGH | Markdown fence strip exploitable | Regex-based strip + safe-query regex on all followups |
| HIGH | ``NameError`` on empty ``sub_queries`` | ``q_idx = -1`` init before loop |
| HIGH | ``id(obj)`` dedup leaks duplicates | Shared ``_block_id`` content fingerprint |

## Install

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

Existing config forward-compatible — no migration.

## Using the new features

```bash
# Bench harness with v3.4.0 features enabled
python3 benchmarks/locomo_judge.py \
    --answerer-model <your-answerer-model> \
    --judge-model <your-judge-model> \
    --single-conv 0 \
    --v34-features
```

Or invoke the modules directly (see module docstrings for API).

## LoCoMo trajectory

| Release | conv-0 | Notes |
|---|---|---|
| v1.1.0 | 70.54 | Original baseline |
| v3.2.1 (BM25) | 76.7 | Previous release |
| v3.3.0 (BM25) | 77.06 | v3.3.0 release |
| v3.3.0 (w/ features) | 70.05 | regressed — fixed in v3.4.0 |
| **v3.4.0 (--v34-features)** | **95.0** (smoke, 10 QAs) | this release |

Full 199-QA conv-0 + 10-conv sweep scheduled for post-release bench.

## Tests

4070+ selected. 35 new tests in ``tests/test_v34_features.py``.
16-job CI matrix: Ubuntu/macOS/Windows × Python 3.10/3.12/3.13/3.14.

## Credits

STARGA Inc. sole author. Pre-release audit: code-reviewer +
security-reviewer passes; strategic direction from cross-model
consensus (recent research) documented in
[``docs/v3.4.0-roadmap-llm-consensus.md``](v3.4.0-roadmap-llm-consensus.md).
