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.
All three are documented behaviour, and easy to miss until one of them costs you something.
| What | Default | What it means for you |
|---|---|---|
| Session transcripts | Deleted after 30 days, checked at every startup | A 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 contents | Plaintext, including anything a tool read | A 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.
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.
| What | Where it lives | What goes in it |
|---|---|---|
| Who I am and how I work | My Claude account memory | Role, company, preferences. Stable for months |
| Where each project stands | projects/<name>/STATE.md, one per project | Current status, next steps, open questions. Rewritten, never appended. Under 60 lines |
| What happened in a session | projects/<name>/log/, one short file per session | Done, decided, left off, next |
| What's waiting, across everything | NOW.md at the root | One line per item: waiting on me, in flight with someone else, to confirm |
| Decisions that would be expensive to reverse | decisions/, one file each | What was decided, why, what else we considered, and what would make it worth reopening |
| Claude Code's notes to itself | memory/ | Whatever Claude Code learns as it works, now versioned with everything else |
| Searchable history of past sessions | A memory plugin, on the laptop | A 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.
Three Claude Code hooks keep the repo current.
| When | What runs |
|---|---|
| A session starts | It 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 reply | At most every 30 minutes, in the background: commit, rebase onto GitHub, push |
| A session ends | The 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).
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.
These are the parts I would have wanted to read first.
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.
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.
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.
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.
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 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.
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.
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.
The kit is a GitHub template. The quickest route is to let Claude Code do it with the prompts in PROMPTS.md:
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.
/wrap, not the background sync.
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.
