How to keep your Claude Code memory in GitHub: a private repo, three hooks and a kit that sets it up for you
How to keep your Claude Code memory in GitHub: a private repo, three hooks and a kit that sets it up for you
Technology
November 19, 2026
11 minutes

How to Keep Your Claude Code Context and Memory in GitHub

Everything my AI agents knew about my work lived in one hidden folder on one laptop, and no Claude client could see what the others knew. Here is how we moved context and memory into a private GitHub repo that every client reads and that syncs itself, what went wrong, and a kit that sets it up for you.

By Aram Melkoumov, CEO of Crowdlinker

Updated November 19, 2026: how cloud sessions actually pick up the repo, what happened when two sessions wrote the same STATE file, and a memory plugin that wanted to be the source of truth. The kit has the same fixes.

I work with Claude in four places: desktop chats organised into Projects, Claude Code in the desktop app, Claude Code sessions in the terminal that I keep running in Herdr, and cloud sessions. Each one keeps its own picture of my work. Desktop chats remember things through my Claude account and each Project. Claude Code keeps its notes in a hidden folder on my laptop. Cloud sessions start with whatever is in the repo they open. None of them reads what the others know. A chat in the morning had no idea what a terminal session decided the night before, so I kept re-explaining the same things.

When I worked through the problem with Claude, the recommendation was one private GitHub repo that every client reads from and writes back to. Claude Code's memory moves into it, each project gets a short page saying where it stands, and every client pulls from that repo before it starts work. That repo is now the one place our context lives.

The second reason was less comfortable. When I went looking for where all that context actually lived, the answer was one hidden folder on one laptop, with no Time Machine and no cloud backup. Lose the laptop and you lose everything your agents know about your work. Two of my sessions from early October were already gone. So the repo doesn't wait for me to remember to save: changes are pushed every half hour while a session is running, and again when it ends.

This post covers what we built, what went wrong while building it, and how to set it up yourself. The scripts and the setup prompts are open source: claude-context-kit on GitHub.

‍

Three defaults worth knowing

All three are documented behaviour, and easy to miss until one of them costs you something.

WhatDefaultWhat it means for you
Session transcriptsDeleted after 30 days, checked at every startupA long-running piece of work you paused for a month loses its history
Auto memory (Claude's notes to itself)Machine-local, in ~/.claude/projects/<project>/memory/Not shared across machines or with cloud sessions, and gone if the laptop is
Transcript contentsPlaintext, including anything a tool readA key from a .env file can end up in a transcript, so transcripts should not go to GitHub

The 30-day cleanup has caught a lot of people. The Register reported on users finding their history gone, and the setting that controls it, cleanupPeriodDays, is a single line in ~/.claude/settings.json. Mine had never been set. That is how the two October sessions disappeared.

‍

What goes where

The fix was to separate the kinds of context and give each a home. Everything except the first and last rows lives in the repo.

WhatWhere it livesWhat goes in it
Who I am and how I workMy Claude account memoryRole, company, preferences. Stable for months
Where each project standsprojects/<name>/STATE.md, one per projectCurrent status, next steps, open questions. Rewritten, never appended. Under 60 lines
What happened in a sessionprojects/<name>/log/, one short file per sessionDone, decided, left off, next
What's waiting, across everythingNOW.md at the rootOne line per item: waiting on me, in flight with someone else, to confirm
Decisions that would be expensive to reversedecisions/, one file eachWhat was decided, why, what else we considered, and what would make it worth reopening
Claude Code's notes to itselfmemory/Whatever Claude Code learns as it works, now versioned with everything else
Searchable history of past sessionsA memory plugin, on the laptopA backup for finding old conversations. Never the source of truth: what it returns gets checked against STATE or the code

The split matters because each file has one job. STATE answers "where does this project stand" in a page. NOW answers "what's on my plate" without opening 25 files. Logs keep history out of STATE so STATE stays short. Decisions keep the reasoning, so a session six months from now doesn't quietly undo something we settled on purpose.

Moving Claude Code's memory took one setting: autoMemoryDirectory points it at a folder of your choice, and we pointed it at memory/ inside the repo. The install copies the old folder rather than moving it, so the original stays as a backup.

Transcripts stay on the laptop. Instead of 30 days they are now kept for ten years. Once a week, a scheduled task will read a redacted summary of the week's sessions alongside our team checkpoints and update the STATE files; its first run is next week.

We seeded the repo from what already existed: Claude Code's memory, the titles of recent sessions, our weekly team checkpoints in Notion, Linear and Slack. It ended up with 25 projects, each with a one-page STATE.

‍

How it stays current without me

Three Claude Code hooks keep the repo current.

WhenWhat runs
A session startsIt works out which project the folder belongs to and loads that STATE and the last three logs. From my home folder, it loads the list of everything waiting on me
Claude finishes a replyAt most every 30 minutes, in the background: commit, rebase onto GitHub, push
A session endsThe same sync, detached so it can't be cut off

Two commands cover the rest: /catchup gives a short brief at the start, and /wrap at the end rewrites the STATE, writes the log, updates NOW and records any decision worth keeping. A desktop chat reads the same files: each Project's instructions point it at the repo, so the morning chat knows what the terminal decided at night. On Projects I share with the team, the block applies only to chats I start myself, so teammates' chats and scheduled tasks leave the private repo alone. The kit has both versions (Desktop chats).

Cloud sessions need one more step

The first version of this post said cloud sessions read the repo. That was too simple. A Claude Code session on claude.ai/code runs on a fresh machine and doesn't get your ~/.claude/CLAUDE.md, your hooks or your local skills (docs). You can attach the context repo as a second repository, but nothing tells Claude to read it, and a session with more than one repository doesn't run the repos' hooks (docs). Skills you enable on claude.ai do load, so /catchup and /wrap are there.

The fix is a few lines in the cloud environment's setup script. They add a short section to the cloud machine's CLAUDE.md: if the context repo is attached, read its STATE at the start, then pull, update and push at the end. The script only appends, and the section tells Claude to ignore it when the repo isn't attached, so it is safe on an environment the team shares (teammates can see the repo's name). You still attach the context repo to each session. The script and the steps are in the kit's Cloud sessions section. This part is newer than the rest, so check it in your first cloud session.

The day after setup, a memory note Claude Code had updated during one of my sessions showed up on GitHub in a commit made by the sync. Nobody ran anything.

‍

What we got wrong

These are the parts I would have wanted to read first.

The first version had five defects a reviewer caught

I switched to a different model and asked it to review the whole setup, with no stake in how it was built. It found real problems. The session-start hook ran git before checking whether the session belonged to a project, so it fired for background helper sessions too. The end-of-session sync pushed without pulling first. The hook never fired for sessions started from my home folder, which is most of them. Our notes would have been committed into the shared CLAUDE.md of client repos, where the client's team would see them. And one engineering STATE had picked up notes that had no business being there.

The client repos now use CLAUDE.local.md and git's local exclude file, so nothing shows up in their git status. I also had to admit I had marked a "verify" step done after only running a search for secrets. The second pass was a real check.

Two sessions wrote the same STATE file

The rule is one writer per project. On day two, two Claude Code tabs updated the same STATE within ten minutes of each other. Git merged it cleanly, but /wrap rewrote STATE from the copy the session had read earlier, so a session working from an old copy could have undone the other one's changes. /wrap now pulls first, re-reads the file from disk and changes only the lines its own work touched. The desktop version already re-read the file before writing.

The safety check blocked the wrong file, and missed the right one

Every sync scans changed files for anything that looks like an API key and refuses to push it. Testing on a copy of our sales and marketing folder showed two failures before they happened for real. A lead export blocked the whole backup because a LinkedIn URL contained the letters sk- followed by a long string, the shape of an OpenAI key. And an environment file I had deliberately chosen to keep in that private repo was not being included at all, because a .gitignore in a subfolder overrode the rule at the top. Both are fixed, and I now test changes like this on a copy of the real folder before trusting them.

Backing up more than code

The same sync now covers folders that are not code repos. Our sales and marketing folder went into its own private repo: 6,987 files, 66 MB. One 122 MB file was skipped, because GitHub refuses files over 100 MB and a single one would block every later push. The script reports what it skips instead of failing quietly.

Moving a folder hides its history

Claude Code files each session under a name built from the folder's path. When I moved a working folder into ~/Code, claude --resume in the new location would have found nothing. The history was still on disk, under the old name. A small script now copies it across and leaves the original where it was. The move broke notes too: 27 paths in Claude Code's memory still pointed at the old folder, including the page-building standard Claude is told to follow. A find-and-replace fixed them, with a check that every new path exists.

A plugin update broke every session start

A memory plugin we use printed two JSON answers from one hook, and Claude Code showed a red "SessionStart hook failed" on every new session. Finding which of eight hooks was responsible took a script that runs each one the way Claude Code does. Updating the plugin then broke it differently: on our version of macOS its new launcher needed a newer Bun runtime. The checker is in the kit, because plugins will keep changing under you.

The same update had a quieter problem. The plugin now told Claude to keep its to-do lists and notes in the plugin rather than in Claude's built-in to-do tool, and it added its own search results to commands. That competes with the repo. I switched its instructions, to-do lists and per-command search results off, and kept it for what it does well: searching old sessions. The rule that the repo wins is now written in the global CLAUDE.md and in the repo's AGENTS.md.

GitHub is not a backup

The repo protects notes, memory and the folders it covers. It does not protect transcripts, ~/.claude, or anything you haven't committed. While checking, I found a code repo whose last commit was two months old, with a pile of uncommitted changes on top. Get a real backup of the machine as well, whether that is an external drive or a cloud service.

‍

The obvious objection

Notes go stale, and a stale note is worse than none, because the agent believes it. That criticism of CLAUDE.md files is fair, and research on repository context files points the same way: keep them minimal and current. Three rules in the repo deal with it. STATE is rewritten at every wrap and kept under 60 lines, so old lines get deleted rather than buried. When the code and the notes disagree, sessions trust the code and say so. And only one session should write a project's STATE at a time; when two do anyway, /wrap pulls and re-reads the file before it writes.

There are good tools that sync ~/.claude between machines, and if that's all you need, use one. We wanted project state that every client reads, kept short and current, with transcripts deliberately left out.

‍

How to set it up

The kit is a GitHub template. The quickest route is to let Claude Code do it with the prompts in PROMPTS.md:

  1. Install. Creates your own private copy, reads the scripts, shows you what will change, and installs after you agree. It stops if the repo is public.
  2. Fill it. Proposes your project list from your memory, recent session titles and code folders, then writes a STATE for each. It never copies transcript text into the repo.
  3. Back up a folder that isn't code. Lists anything over 95 MB and anything that looks like a secret, and asks about each.
  4. After you move a folder. Copies the session history to where Claude Code will look.
  5. Health check. Runs every session-start hook and reports anything broken.

If you'd rather do it by hand, it is three commands: create the repo from the template, clone it, run ./install.sh. Then start a new session and ask Claude which folder its memory is in. It should name the folder inside your repo.

Cloud sessions and desktop Projects each need one more step after the install. The README's Cloud sessions and Desktop chats sections cover them.

‍

What this does not cover

  • It is built and tested on macOS with zsh, on Claude Code 2.1.327 and 2.1.328. The sync scripts were also tested on Linux.
  • It doesn't merge two people editing the same project's notes at once. One writer per project.
  • Cloud sessions don't run the hooks. They read the repo only when it's attached and the setup script is in place, and they save through /wrap, not the background sync.
  • It is a companion to herdr-claude-kit, which brings long-running sessions back after a reboot. Together they cover losing a session and losing what it knew.

‍

What it looks like inside an AI-native studio

At Crowdlinker, agents do a large share of the work, on client products and in our own operations. That only holds up if what they know is treated like any other company asset: it lives somewhere shared, it has history, it survives a lost laptop, and someone other than the author checks it. Ours is now a private repo with 25 one-page STATE files, a folder of memory notes and a sync that runs without anyone thinking about it. It took finding two sessions already gone to make it a priority.

‍

→ Talk to Crowdlinker about building your product with senior engineers who ship with AI every day

Read more
Community posts

GET IN TOUCH
GET IN TOUCH

Want to learn more?

Let’s start collaborating on your most complex business problems, today.