How to resolve a git merge/rebase conflict inside
memory/— especiallycontinuity.md, the one file every teammate edits. Read this on demand, when git reports a conflict inmemory/; it is not part of the per-session read path.
memory/ is committed and shared, so concurrent teammates — on any vendor — will sometimes
collide. Session logs almost never conflict (timestamped filenames), Open Threads can't
conflict across threads (one file each under memory/open-threads/, v4.39.0), and archive
files union-merge (.gitattributes); what remains is continuity.md and the rare
same-thread-file clash. The hard rule comes straight from the never-pick-a-winner
invariant:
An AI must never silently choose a winner between two conflicting memory facts.
Free-editing the raw conflict markers to "just resolve it" is that failure — the model quietly drops one side and the loss is invisible. So resolution here is structured, validated, and human-gated, not free-text surgery:
git conflict in memory/
↓ (1) classify each conflicted hunk
↓ (2) resolve by tier
↓ (3) memory-lint — deterministic gate: no markers left, file parses, decay intact
↓ (4) human approves the merge commit
done
Never skip (3) or (4). (You still delete the <<<<<<</=======/>>>>>>> lines — the rule
isn't "don't touch the text," it's "don't silently pick a winner.")
Look at what actually diverged between the two sides:
- Additive — both sides added different facts/bullets to an append-only section
(
## Key Decisions,## Conventions,## What's Been Built). The commonest continuity case. - Scalar — both sides bumped the same single-value field (
last_review,last_invariant_check, thestatusversion token). - Semantic clash — both sides changed the same fact's substance (in continuity, or
a conflict in the same
memory/open-threads/thread-<id>.mdfile); or one checked a thread[ ]→[x]while the other edited it; or a fact was superseded on one side and edited on the other. The rare case — and the only one needing judgment. A thread-file conflict is always this class — the layout has already eliminated the mechanical cases. (Precision, v4.39.1: git raises the conflict when same-thread edits touch adjacent/overlapping lines. Edits separated by unchanged lines merge cleanly with both sides kept — nothing is lost, but the merged thread may now hold two inconsistent statements: give it the write-time contradiction check,DECAY.md§10. Same behavior as when threads lived in continuity — the layout changed where conflicts land, not git's hunk semantics.)
- Additive → UNION. Keep BOTH sides' additions. They are independent facts; dropping
either loses information. Order doesn't matter — the review re-sorts and decays. Each fact
keeps its own
id+ footer. - Scalar → take the LATER value (later date / higher semver).
- Archive files (
memory/archive/*.md) carrymerge=unionin.gitattributes, so concurrent sweeps' appends merge on their own. The one case union gets wrong — a reactivation's removed lines resurrected by the other side — is caught bymemory-lint's[both]/[over-archived]ERRORs; fix by re-removing the resurrected block. - Two session logs with the same filename (same-second persist on parallel branches — an add/add conflict): keep both by renaming either one +1 second; never merge their contents into one file.
No "propose a repair" step — apply the rule.
You may not decide which version is "right." Preserve intent as structured facts instead:
- Both edited the same fact's substance → keep both versions as distinct facts (give
the incoming one a fresh
id) and raise a Contradiction (the same write-time mechanism,DECAY.md§10 /.agent/schema.md):- [ ] Contradiction: <id-A> vs <id-B> — <one line on what diverged>; human to reconcileBoth survive until the human reconciles. - Supersession is the human's call, never yours. Do not judge that one side "genuinely
supersedes" the other — that judgment is exactly where a disguised winner-pick hides (you talk
yourself into your preferred side being the "real" one). A semantic clash is always resolved
as keep-both + a Contradiction thread, unless the human explicitly instructs a supersession —
in which case record it: successor born
tier: workingwithsupersedes: <old>; mark the oldsuperseded+superseded-by: <new>(DECAY.md§9). Absent that explicit instruction, keep both. [ ]→[x]race → this is a mechanical state transition, not a substance clash: keep it checked[x]if either side completed it (completion wins over incomplete; the review later sweeps it). If the bodies also diverged, that's a substance clash — handle as Contradiction above.- Preserve provenance — keep each fact's
origin; don't rewrite footers to erase where a fact came from.
When in doubt, prefer keep-both + a Contradiction thread over choosing. Choosing is the one thing you may not do.
Run memory-lint (any runtime). It deterministically confirms:
- no leftover conflict marker survived (check 7 —
<<<<<<</>>>>>>>/ diff3|||||||); - no
idlives in bothcontinuity.mdand the archive; nothing over-archived; supersession links resolve; the file still parses (footers, version manifest).
Fix every ERROR before proceeding. memory-lint does the counting; you did the meaning.
Conflict resolution is a human-gated act — like supersession and the review's archival. Show the human what you kept, what you unioned, and every Contradiction / supersession you raised, then let them approve the merge commit. Never auto-commit a conflict resolution.
See .agent/schema.md → "Concurrency & merge-friendliness" for the authoring conventions that
keep conflicts rare and mechanical in the first place (one fact per line, append-only sections);
DECAY.md §9–10 for supersession / contradiction; REVIEW.md for the periodic sweep that tidies up
afterward.