Give Claude Code headroom and a searchable memory synced on all devices.
Three small tools, layered in one easy order. Headroom compresses tokens before they reach the model, claude-mem remembers your work across sessions, and claude-mem-sync carries that memory between machines. Light, independent layers — one clean install.
Headroom wraps the Claude Code CLI and acts as a compression proxy between you and the model. Before an oversized payload — a 4,000-line test log, a giant file read, a noisy tool dump, a sprawling diff — ever reaches Claude, Headroom rewrites it into a dense, meaning-preserving summary. You keep the signal, drop the boilerplate, and win back context window that would otherwise be spent on noise.
Compresses logs, tool output, diffs, and large file reads inline, as they stream in
Installs as a wrapper — headroom wrap claude — with no changes to your code
Completely independent of memory; confirm it's live any time with headroom doctor
Memory layer
claude-mem
claude-mem gives Claude Code a persistent, searchable long-term memory. As you work it quietly captures observations — decisions made, files changed, bugs fixed — into a local database. Open a new session and the relevant memories are injected automatically, so Claude already knows what you did last week without being re-briefed. You can also query that history directly and get answers pulled from real past sessions.
Auto-captures decisions, edits, and fixes into a local store as you go
Injects the relevant context into every new session — no re-explaining
Fully searchable: ask "how did we fix the webhook retry?" and get a real answer
Installs its own hooks + a background worker via npx claude-mem install
Sync layer
claude-mem-sync
claude-mem-sync keeps that memory identical everywhere you work. It syncs the claude-mem database and configuration between machines through a git-backed repo, so the context you built on your desktop is already waiting on your laptop the next morning. Nothing about your workflow changes — Claude Code stays the only environment, and sync sits as a thin layer on top of an already-working claude-mem.
Syncs the claude-mem database + config across every device
Git-backed — git pull on any machine and the memory is current
Optional team memory: a whole team can share one brain for a repo
Install it last, once local memory is proven to work
// They work together because they operate at different layers — never the same one.
03
How to get started
Prerequisites
Get these in place before you install anything. This guide is only for Claude Code.
Claude Code
Node.js 20 or newer
Python 3.13 — with uv preferred
Git
Install Headroom
First, because it's independent of memory and easy to verify on its own.
recommended · uv
# install the CLI (not the npm SDK)
uv tool install --python 3.13 "headroom-ai[all]"headroom wrap claude
headroom doctor
No uv? Use pip instead
alternative · pip
pip install "headroom-ai[all]"headroom wrap claude
headroom doctor
Don't use npm install headroom-ai for Claude Code CLI setup — that npm package is the TypeScript SDK only and does not provide the headroom command.
Install claude-mem
Second. Adds persistent memory across Claude Code sessions. Use the installer, not a bare npm install.
Then restart Claude Code. Hooks and the worker service register on install and need a fresh start.
Don't use npm install -g claude-mem as the main path — it installs the SDK only and won't set up hooks or the worker service.
Verify claude-mem works
Prove the memory layer locally before layering sync on top.
Open a new Claude Code session
Confirm memory appears automatically from earlier work
Settings live here
config path
# open to inspect / tweak
~/.claude-mem/settings.json
Install claude-mem-sync
Third — and only after claude-mem is already working. This is the sync layer for the memory database and config.
Purpose: sync your claude-mem state across machines while keeping Claude Code as the only target environment. Follow the repository's own instructions for the install itself.
get the repo
git clone https://github.com/lajlev/claude-mem-sync
# then follow the repo's README to configure sync
Order of operations
The whole point of the setup is that it's predictable. Do it in this exact order.
1 Install Headroom→2 Install claude-mem→3 Confirm memory locally→4 Install claude-mem-sync→5 Restart Claude Code→6 Test a new session
04
How to use it — a real example
Two days in a project called acme-api. After install you never invoke the tools by hand — Headroom, claude-mem and claude-mem-sync all run in the background. Here's exactly what you'd see.
Mon 09:14 You do the work — claude-mem quietly records it
~/code/acme-api
$ claude
you › extract the Stripe webhook handler into its own module
claude › Done — moved it to webhooks/stripe.ts and put the
signature check in verifyStripeSig().
✔ claude-mem · saved 2 memories, session ended
↓ two days later, same machine ↓
Wed 15:40 New session — the memory is already there
new session · same project
$ claude
✔ claude-mem recalled from acme-api · Mon — Stripe webhook moved to webhooks/stripe.ts · Mon — signature check lives in verifyStripeSig()you › where did we put the signature check again?
claude › In webhooks/stripe.ts — verifyStripeSig(), from Monday.
Wed 15:52 A heavy task — Headroom keeps the context light
large tool output
you › run the integration tests and fix whatever breaks
↳ headroom · compressed test log 4,218 lines → ~360 tokensclaude › The failing assert is stripe.test.ts:88 — signature
mismatch. Patched verifyStripeSig() to trim the header.
↓ next morning, on your laptop ↓
Thu 08:05 Second device — sync carries it all over
laptop · not the desktop
$ cd claude-mem-sync && git pull
✔ claude-mem-sync · memory + config up to date$ claude
✔ claude-mem recalled from acme-api (synced from desktop) · everything from Mon–Wed is already here
Level up your workflow
The three-layer stack gives Claude Code memory and headroom. These two go further — turning a single session into a parallel, multi-worktree command center.
cmux is a native macOS terminal, built on Ghostty, made for running AI coding agents in parallel. Launch several Claude Code sessions at once — one per task, each a vertical tab — and when an agent spawns subagents or teammates, cmux turns them into visible native panes and splits instead of hidden background processes. A whole multi-agent run stays in one window, watchable and controllable.
Run Claude Code (plus Codex, Gemini, Aider, Cursor…) side by side, one task per tab
Subagents become real panes — every agent in a run stays visible, not buried in the background
Vertical tabs, desktop notifications, an embedded browser, and a scriptable socket API — all built in
Free & open source · a native macOS app — download from cmux.com
cwt — the cmux Worktree Tool — turns one command into a fully-loaded, isolated workspace. cwt spawn <name> creates a git worktree branched off your base, then opens a cmux workspace with its own Claude Code agent, a git TUI, and an editor. It can even pull a Linear / GitHub / Jira ticket and seed the agent with that context — so every parallel branch of work gets its own tidy, context-aware environment.
I wrote this guide and built claude-mem-sync — the sync layer that keeps your Claude Code memory in step across every device. If it's useful, or if something breaks, come say hi.
