# MIND-Mem v3.2.0 — Production Deployment Release

**Status:** release candidate. Tag-gated by LoCoMo v3.x refresh +
a final cross-model audit.
**Shipping:** ~50 commits across 21 tracked tasks.

This is the largest release in the v3 line. It turns MIND-Mem from a
single-host Markdown-on-disk memory into a production-ready memory
system with Postgres, Docker, REST, multi-language SDKs, Prometheus +
Grafana observability, and a publishable security posture.

---

## Headline features

### 1. Postgres storage backend (opt-in)

Full ``BlockStore`` protocol implementation against PostgreSQL 14+.
Opt in via:

```jsonc
{
    "block_store": {
        "backend": "postgres",
        "dsn": "postgresql://user:pw@host:5432/db"
    }
}
```

Multi-region read replicas:

```jsonc
{
    "block_store": {
        "backend": "postgres",
        "dsn": "postgresql://primary/db",
        "replicas": [
            "postgresql://replica-a/db",
            "postgresql://replica-b/db"
        ]
    }
}
```

Reads round-robin across replicas with a 3-failure / 30-second
cool-down circuit breaker. Writes always hit primary.

Migration guide: [docs/storage-migration.md](storage-migration.md).

### 2. REST API + OIDC/SSO auth

FastAPI layer at `src/mind_mem/api/rest.py` mirroring the MCP tool
surface. Run with `mm serve --port 8080`. Auth modes:

- Bearer token (legacy + tests)
- OIDC/JWT via Okta / Auth0 / Google Workspace / Azure AD
- Per-agent API keys (`mmk_live_*`) with SQLite-backed rotation
- Audit records now carry ``agent_id`` attribution

Endpoints: `/v1/recall`, `/v1/block/{id}`, `/v1/propose_update`,
`/v1/approve_apply`, `/v1/rollback_proposal`, `/v1/scan`,
`/v1/contradictions`, `/v1/health`, `/v1/metrics`,
`/v1/admin/api_keys`.

### 3. SDKs

- **Python** — the original; unchanged.
- **JS/TS** — `sdk/js/`, publishable as `@mind-mem/sdk`, strict
  TypeScript, stdlib-fetch. Covers the read-only surface.
- **Go** — `sdk/go/`, stdlib-only, publishable as
  `github.com/star-ga/mind-mem/sdk/go`.

### 4. Docker + Compose

`deploy/` ships a multi-stage `python:3.12-slim` Dockerfile (142 MB
final image), a compose file bringing up MIND-Mem + pgvector +
Ollama together, and a Makefile (`make up` / `down` / `logs` /
`shell`). See [docs/docker-deployment.md](docker-deployment.md).

### 5. OpenTelemetry + Prometheus + Grafana

Optional `[project.optional-dependencies.otel]`. `mm serve` runs
with OTLP tracing + `/v1/metrics` Prometheus exposition.
`deploy/grafana/mind-mem-dashboard.json` is the 4-panel starter
dashboard (recall p50/p95/p99, recall qps, propose_update rate,
apply-rollback rate).

### 6. Distributed recall cache

`mind_mem/recall_cache.py` ships a two-tier cache (in-process LRU +
optional Redis L2). Configure via `cache.redis_url`; fails open
(Redis outage falls through to primary recall). Invalidated on
propose_update / apply / rollback.

### 7. CLI debug commands

- `mm inspect <block_id>` — full block + provenance tree.
- `mm explain <query>` — retrieval trace (BM25 → vector → RRF →
  rerank per candidate).
- `mm trace --live` — stream MCP tool calls with OTel span data.

### 8. Security posture upgrade

- **SECURITY_AUDIT_2026-04.md** — internal 3-finding audit report.
- **docs/security-audit-sow.md** — RFP-shape SoW for external
  tier-1 audit (Trail of Bits / Doyensec / NCC / Latacora / X41 /
  Include Security / GDS).
- **SECURITY.md** — supported versions, 90-day disclosure timeline,
  threat model, in-scope definition.
- **Supply-chain CI** — `.github/workflows/security.yml` runs
  CodeQL, bandit, pip-audit, gitleaks, trivy, and generates a
  CycloneDX SBOM attached to every tagged release.
- **sigstore** signing of wheels + tarballs on release.
- **Pre-commit hooks** — ruff + bandit + detect-secrets.
- **Token hardening** — `_MAX_TOKEN_LEN = 4096` + startup warning
  on short tokens.
- **Query-length cap** — recall rejects queries > 8192 chars to
  prevent regex-DoS.
- **docker-compose.yml** — all credentials replaced with
  `${VAR:?}` required env vars (CWE-798 fix).

### 9. Architecture cleanup (audit §1.2 / §1.4 / §2.2)

- ``mcp_server.py`` decomposed: 4,578 → 245 LOC (94.6% reduction).
  14 tool modules + 7 infra modules + resources module + server.py
  + public.py (v3.2.0 consolidated dispatchers).
- **Atomicity §2.2** — `maintenance/` split into `tracked/` +
  `append-only/`; orphan-cleanup walk honors exclusions; repro test
  pins the contract.
- **BlockStore routing §1.4** — 7-PR series: rename, write/delete,
  snapshot/restore/diff, lock, Postgres adapter, backend selection,
  migration guide.

### 10. MCP tool-surface reduction (additive)

7 new consolidated dispatchers (`recall`, `staged_change`,
`memory_verify`, `graph`, `core`, `kernels`, `compiled_truth`)
route to the existing 57 implementations via `mode` / `phase` /
`action` arguments. Backward-compat: every v3.1.x tool name still
resolves.

### 11. Obsidian wikilink export

`vault_sync` now emits `[[wikilinks]]` for every KG edge
(authored_by, depends_on, contradicts, supersedes, part_of,
mentioned_in, related_to) so Obsidian's graph view visualizes
MIND-Mem's knowledge-graph relationships.

### 12. Hot/cold tier-aware retrieval

`src/mind_mem/tier_recall.py` multiplies recall scores by the
block's tier boost (WORKING 0.7x / SHARED 1.0x / LONG_TERM 1.5x /
VERIFIED 2.0x). Opt-in via `retrieval.tier_boost: true`.

### 13. One-command installer

`install-bootstrap.sh` — `curl -sSL https://install.mind-mem.sh |
bash` ready. Venv support, workspace init, MCP client hook wiring.

---

## Breaking changes

**None.** v3.2.0 is strictly backward-compatible with v3.1.x:

- `mind-mem.json` from v3.1.x still loads (new keys default).
- All 57 MCP tools still resolve by their v3.1.x names.
- `BlockStore.list_files()` deprecation-warns but still works;
  removed in v4.0.
- `validate.sh` warns that it's a Python forwarder.
- `maintenance/` top-level layout auto-migrates on first v3.2.0
  apply.

---

## Upgrade path

```bash
pip install --upgrade mind-mem
mm status             # verifies everything parses
```

First apply on a v3.1.x workspace triggers the auto-migration of
`maintenance/*` into `maintenance/{tracked,append-only}/`. No
manual intervention required.

---

## Known gaps — not in v3.2.0

- **External tier-1 security audit** — SoW published; firm
  engagement is a v3.2.1+ milestone.
- **LoCoMo v3.x benchmark refresh** — still citing v1.9.0 numbers
  (77.9 / 82.3 / 88.5). Re-run gated on v3.2.0 release freeze.
- **Redis cache wired into recall dispatcher** — the cache module
  is shipped and tested; the call-site wiring (`cached_recall`
  wrapping `_recall_impl`) lands as a one-line change in v3.2.1.

---

## Metrics

- **Tests:** 3600+ passing (v3.1.9 was 3617; v3.2.0 adds ~150
  tests across 13 new test files).
- **LOC:** `src/mind_mem/` up ~2,200 LOC net (new files:
  `block_store_postgres.py`, `block_store_postgres_replica.py`,
  `api/rest.py`, `api/auth.py`, `api/api_keys.py`, `telemetry.py`,
  `recall_cache.py`, `tier_recall.py`, `storage/__init__.py`,
  `mcp/tools/public.py`). Multiple large decompositions net ~-700
  LOC.
- **MCP tools:** 57 legacy + 7 consolidated dispatchers = 64 unique
  registrations.
- **Security findings:** 3 (2 HIGH + 1 MEDIUM) — all fixed in
  release commits before tag.

---

## Credits

STARGA, Inc. All code Apache-2.0.

Mind the gap between "feature complete" and "audited clean" — the
former ships in v3.2.0; the latter gates v3.2.1.
