| Git history | A chat summary | A Cartographer map | |
|---|---|---|---|
| Records | What changed: commits, diffs, branches | What the agent remembers, in prose | Every move: what you did, what happened, what it meant, the outcome, your response |
| Evidence | The diff itself | None required | Each move lists the timeline items it rests on; saving rejects a move without them |
| Dead ends | Invisible unless committed | Usually left out | Kept, marked, and read for what they cost |
| Your prompts | Not recorded | Paraphrased | Read one by one: the act, the anchor, how it was said, and where a correction marks the previous move as wrong for you |
| Praise | Not applicable | Common | Rejected on save, in the map and in the appraisal |
| The verdict | Whether it merged | Whatever the summary says | Waits for /complete, judged against the goal you declared, because a session cannot judge itself |
| Where it lives | The repo | The chat | ~/.cartographer on your machine, as JSON maps and rendered replays |
The short version
Git is the record of the result. A chat summary is the agent's recollection of the process. A map is the process, read from the record, under rules. Use all three; they do not compete.
If you want to see what the third one looks like on a real build, the demo replay is one. How it works explains the five parts of a move and the yardstick the appraisal reads them against.
Questions
Does Cartographer replace git?
No. Git records what changed and Cartographer records how you got there. They answer different questions about the same work.
Why not just ask the agent to summarise the session?
You can, and it will. A summary is prose with no rules: it can praise, skip the dead ends, and cite nothing. A map has five fixed parts per move, cites the timeline it rests on, and rejects praise words on save. The difference shows up the third time you read one.
Is the map written by a different model?
It is written by the agent that was in the session, following a brief. That is why it knows what you meant. The rules are enforced by Cartographer when the map is saved, not by the model's good intentions.