Home / A structured installation

Wiring file based memory to git

A memory folder versioned by git, with a private remote and a merge rule that keeps both contents rather than forcing one over the other, remains a technique to build yourself, distinct from the native automatic memory, which never leaves the local machine.

A memory folder stays a pile of text files as long as it lives alone on one machine: it disappears with the machine, and nothing lets you know who wrote what or when. Turning it into a git repository changes its nature. Add a private remote, and this folder becomes a vault synchronisable across several machines, with the history, the diff and the ability to go back to an earlier version that git already brings.

The protocol in four gestures

The protocol fits in a few words. At the start of a session, pull the remote notes before reading anything else. Then write during the session, like an ordinary notebook. At the end of the session, commit the day's notes, then push to the remote. On a merge conflict, the rule is never to force one version over the other: it is to keep both contents and merge them by reading, by hand, a little later. A throwaway repository illustrates the basic mechanics without touching any real folder.

mkdir demo-memoire && cd demo-memoire
git init -q
echo "note du jour" > carnet.md
git add carnet.md
git commit -q -m "premiere note"
git log --oneline

On a real vault, this sequence repeats at every session, with a pull added before writing and a push after the commit. A folder run through grep to spot a secret before the very first push prevents a forgotten credential from reaching the remote and then staying in the history, even after the file is later deleted.

What the native automatic memory does not replace

Claude Code now ships with an automatic memory mechanism, distinct from CLAUDE.md, that accumulates session notes on its own in a local folder. This mechanism deliberately stays local to the machine: worktrees and subfolders of the same git repository share a single automatic memory folder, but nothing is shared between several machines or cloud environments. The git protocol described here therefore keeps its reason for being precisely where automatic memory stops, as soon as a second machine or a shared remote comes into play. The two mechanisms answer two different needs and can coexist without getting in each other's way.

This protocol takes on its full meaning once connected to the session lifecycle events, in hooks and heartbeat, where the pull and the push stop being a manual gesture and become automatic.