fix: conflict-free .ai-memory merges for multi-developer teams (v1.2.0)

[elViRafa]

Summary

Reported from a multi-developer project: every branch integration conflicted in .ai-memory/ — failures.md, index.md, and the episodic day file both developers had journaled into.

Reproduced that exact conflict set first, then found three separate causes, not one:

1. The merge driver was only half-installed. .gitattributes is committed and shared, but the driver command lives in per-clone git config — git's own design, since a repo can't ship executable merge commands. Whoever ran init --merge-driver was fine; everyone who just cloned got plain textual merges with nothing explaining why.
2. Generated views conflicted deterministically. Root maps (generated: true) and the two discovery indexes are rebuilt from memory-store/ on every Dream, but are regenerated wholesale rather than appended to, so they could never satisfy the driver's pure-append test. Worse, the old code's claim that a conflicted map is "self-healing" was wrong: regenerate_maps compares the body against the recorded body_hash, and a merged or conflict-markered body fails that check — so the next Dream would fold the mess into memory-store/ as a permanent memory.
3. The driver only understood pure appends. Two agents journaling the same day produce separate ## entries plus edits to older ones, which is not a shared prefix.

Two further bugs were found by CI while this branch was in review — see Found in review below. One of them (mcp 2.0.0) is unrelated to this work and affects released versions.

Related issue

No tracked issue — reported directly.

Changes

• Generated views union-merge and never conflict. The merged file is re-stamped (body_hash recomputed, store_fingerprint blanked) so the next regenerate_maps rebuilds it from the store instead of mistaking the merge for a hand edit and folding the union into memory-store/. Union merging delegates to git merge-file --union for correct anchoring, with a pure-Python fallback.
• Store entries merge block by block (##-delimited), replacing the pure-prefix-append requirement. Block text is compared with trailing blank lines stripped, so an untouched block doesn't look edited on the branch that appended after it. Only a single block rewritten on both sides — a real disagreement — still defers to git's textual merge.
• New ai-memory resolve-conflicts — resolves the conflicted .ai-memory files of an in-progress merge and stages them, reading the three sides from the index stages git already recorded (:1:/:2:/:3:), so the merge doesn't have to be redone. Files needing a human are left untouched, reported, and make the command exit non-zero.
• ai-memory doctor warns when the driver is half-installed, in both directions (declared but not registered; registered but not declared).
• Any ai-memory init registers the driver in a clone that already declares it, closing the teammate gap from the other side.
• The driver is registered with git's %P placeholder so it knows the real pathname being merged. Clones registered before this keep working — index.md is also recognized from its frontmatter.
• Committed .gitattributes so this repo dogfoods the driver.
• Release v1.2.0: minor rather than patch (new command, new doctor check, changed merge behavior).

Verified end-to-end on real clones: without the driver the merge conflicts and resolve-conflicts clears it; with the driver registered the same merge succeeds outright with zero conflicts; a fresh clone gets the doctor warning, and a plain init in that clone repairs it.

Found in review

Windows line endings (mine). The first CI run failed on exactly 4 of 12 test jobs — the Windows matrix. Path.write_text translates \n to \r\n there, so the temp files handed to git merge-file were CRLF, git returned CRLF, and the merged body was hashed in that form — while parse_frontmatter normalizes line endings on read. Every merged map on Windows therefore carried a body_hash that could not match its own body: precisely the state that makes regenerate_maps fold the merge into the store. The re-stamp was silently useless on that platform. Fixed by writing the temp files as bytes and normalizing git's output to LF; the regression test reproduces it off Windows by making git's stdout CRLF directly.

mcp 2.0.0 removed mcp.server.fastmcp (not mine, and not new here). The rest of CI was red on every job including mypy. Re-running CI on an unchanged, previously-green main commit reproduced it identically, which ruled this branch out. The MCP SDK released 2.0.0, which drops mcp.server.fastmcp — what server.py is built on. The dependency was an open mcp>=1.0.0, so every fresh install resolves to the new major, FastMCP falls back to None, and memory-fabric[mcp] ships an MCP server that cannot start. This affects users on released versions, not just CI. Pinned to mcp>=1.0.0,<2 as a stopgap; porting to the 2.0 API is separate work worth its own issue.

Testing

• pytest passes (coverage stays at or above the gate)
• ruff check . and ruff format --check . are clean
• mypy src/memory_fabric is clean
• Added or updated tests for the changed behavior

Merge-driver tests 11 → 27, covering block merges, generated-view union merges, the re-stamp that prevents the fold, the CRLF regression, resolve-conflicts (resolved / deferred / no-op), driver registration status, and the doctor warning.

Locally with mcp installed and pinned: 383 passed, mypy clean.

Checklist

• Updated CHANGELOG.md (entry closed out as [1.2.0])
• Updated docs affected by this change (README: merge-driver section, resolution table, CLI reference)
• If the version was bumped, README / ROADMAP / server.json all agree (tests/test_version_truth.py)
• No telemetry, no network calls added to core read/write paths