How the vault merge engine keeps edits calm

Storing your team’s memory in git gives you history, accountability, and ownership. It also raises an obvious question: what happens when two people, or a person and the assistant, edit the same note at the same time?

The honest answer for most git-backed tools is a merge conflict, those blocks of angle brackets that no one outside of engineering should ever have to see. We decided that was unacceptable for a knowledge base. So Octopedia does not merge the way git merges by default.

Line merges are the wrong tool

Git’s default merge works on lines of text. That is the right model for source code, where a line is a meaningful unit. It is the wrong model for a structured note, where the meaningful units are fields.

Consider a person entity. One teammate updates last_contact. At the same moment, the assistant appends a sentence to the body. To git’s line merge these edits look dangerously close together. To a human, they are obviously independent and should both simply apply.

A structured, field-aware merge

Octopedia parses each note into its real structure before merging: the frontmatter becomes a map of fields, the body becomes a sequence of blocks. The merge then happens at that level.

• Disjoint fields combine cleanly. A change to last_contact and a change to status never collide, because they are different keys.
• The body merges by block. An appended paragraph and an edited paragraph elsewhere both land, untouched.
• A true conflict is rare and specific. Only when two edits change the same field to different values does anyone need to decide, and the decision is presented as two plain choices, never as raw markers.

The result is that the overwhelming majority of concurrent edits merge silently and correctly, the way the people making them would expect.

Crash safety, because hardware fails

A merge is only trustworthy if it cannot leave the vault half-written. Octopedia applies every multi-file change through a rename transaction staged in a dedicated directory. The final step is an atomic rename. If the power fails midway, the next start finds either the old state or the new one, never a blend of the two.

The vault should be exactly as consistent after a crash as a single git commit is. Anything less is a data-loss bug waiting for a bad day.

Why this matters for a knowledge base

The point of all this machinery is that nobody using Octopedia should ever think about it. You edit a note. A colleague edits the same note. The assistant files something into it from a chat. All three changes land, the history records each one, and no one is handed a conflict to resolve.

Calm software is mostly the absence of avoidable interruptions. The merge engine is one of the larger interruptions we worked to remove.