Summary

Save paths running in-process (Web UI PATCH /api/config, /memory-dirs/*, MCP mem_config) read cfg.<field> directly and wrote whatever the runtime config held. After load_config_d, that included fragment- and env-merged values. A user PATCHing an unrelated field silently copied config.d/ fragment contents into config.json's REPLACE layer, freezing subsequent fragment edits. Tracked in project_fragment_dragin_gap.md and the feedback_silent_policy_enforcement_gap.md "Known instances" entry (instance 2 — the canonical [] wipe, instance 1, was already resolved by #256 + #257).

Reproduction (Phase 0, 2026-04-19, 5 scenarios + 3 measurements, all PASS): config.d/noise.json defines exclude_patterns; mm config set search.default_top_k 42 via the web flow drags the fragment values into config.json, and a subsequent fragment edit no longer takes effect. Phase 0 validated the Z design end-to-end without touching real code.

Design — delta-only save against a comparand

save_config_overrides now builds a fresh comparand via _build_comparand():

comparand = Mem2MemConfig()   # defaults + env (BaseSettings auto)
load_config_d(comparand, quiet=True)  # + fragments

Mem2MemConfig() construction reads MEMTOMEM_* env and runs default_factory callables, so the comparand inherently reflects defaults + env + fragments + env-dependent factory output. Save persists only fields where cfg.<field> != comparand.<field>.

Three silent-persistence patterns collapse into one mechanism:

1. Default-equal (PR fix(config): drop default-valued fields on save to prevent silent leftover pins #256 drop-default) — the default is simply a comparand case.
2. Env-sourced — env is part of the comparand, so MEMTOMEM_MMR__ENABLED=true no longer drag-pins into config.json.
3. Fragment-sourced — load_config_d merges fragments into the comparand; fragment values stop copying into config.json on unrelated saves.

Same concern, different angle

PR #256 introduced _EXTRA_PERSIST_FIELDS as a defensive exemption for env-dependent factories (documented in feedback_env_dependent_factory_equality.md). This PR addresses the same concern differently — by including factory output in the comparand itself. Machine A saves: factory matches → drops. Machine B loads: factory runs fresh, returns the right local value. No exemption needed; no machine-A-to-B pin either.

The set was renamed to _EXTRA_MUTATION_FIELDS, not deleted, because it retains a distinct role beyond the pre-Z always-persist semantics: marking fields that save_config_overrides persists even though they are absent from MUTABLE_FIELDS (managed by dedicated endpoints /memory-dirs/add|remove — generic mutation would bypass filesystem validation and indexing triggers). The rename reflects the semantic shift; an inline comment preserves the pre-Z history so future readers don't re-litigate.

Secondary changes

• load_config_d(quiet=False) parameter added — suppresses WARNING-level logs only (malformed fragment, unknown section, etc.). Used by _build_comparand to prevent repeated warnings on every save. Errors still raise.
• _field_equals_default deleted — grep confirmed 0 external consumers. Delta comparison is a plain cfg_val != comp_val inline.
• docs/guides/configuration.md — new "Delta-only save semantics" subsection replacing the stale "Web UI dumps every mutable field" narrative (incorrect post-fix(config): drop default-valued fields on save to prevent silent leftover pins #256/fix(config): coerce list[BaseSettings] on mutation path #257), and a "Moving config.json between machines" note for Scenario-5 migration guidance.

Performance

Comparand build: 1.88 ms mean per call (100 iterations, real ~/.memtomem/config.d/ with 3 fragments). Save frequency under interactive use is far below any rate where this overhead matters; UI PATCH is rate-limited by user interaction.

Migration safety

Existing config.json files with pinned values load normally. On the next save:

• Values that now match the local comparand → pruned automatically (ambient cleanup, same mechanism as fix(config): drop default-valued fields on save to prevent silent leftover pins #256 post-merge).
• Values that don't match (e.g. machine-A paths in memory_dirs carried to machine B) → stay pinned until user actively resets. Tested: test_machine_migration_requires_active_reset. Documented with an explicit reset recipe ("remove the indexing section" or mm init --fresh).

Test plan

1699 tests pass (pre-branch 1694 → +5 net: +6 new, −1 deleted).

TestSaveConfigOverrides rewritten. Matrix:

New isolated fixture

Added to support multi-source test setup (config.json + config.d/ fragments + env vars in one place). Without it, _build_comparand reads the developer's real ~/.memtomem/config.d/ and tests pass accidentally — caught during Phase 1 rewrite. Centralizing the patching prevents every new test from repeating the boilerplate.

Test plan checklist

• uv run pytest -m "not ollama" — 1699 passed
• uv run ruff check + ruff format --check — clean
• uv run mypy packages/memtomem/src — 0 issues
• Manual: _field_equals_default grep in entire tree → 0 references (safe deletion)
• Manual: comparand build benchmark → 1.88 ms/call, well under 5 ms
• Manual: Phase 0 script (5 scenarios + 3 measurements) re-run after implementation → all PASS

Refs

• PR config: env wins over config.json + config.d/ fragment layer (fixes #248) #249 — config.d/ precedence + the "config_set intentionally skips load_config_d" design that kept CLI safe from this flavor of drag-in.
• PR fix(config): drop default-valued fields on save to prevent silent leftover pins #256 — drop-default on save; introduced _EXTRA_PERSIST_FIELDS defensive exemption (now superseded by comparand inclusion).
• PR fix(config): coerce list[BaseSettings] on mutation path #257 — nested list[BaseSettings] coerce on mutation path; orthogonal.