claude-sync

A local memory for working with Claude across many sessions and many projects.

Every Claude session starts cold. claude-sync gives each of your projects a living handoff.md (what it is, what's verified, what's next), a cross-project rulebook and lessons file, and tools so any session can pull the full context in one call instead of you re-explaining it. Plus git guards that stop the two mistakes agents make most: committing to the wrong repo, and pushing things nobody approved.

100% local. No accounts, no cloud, nothing leaves your machine unless your push policy says so.

What's in the box

Related MCP server: kb

Setup (the easy way)

Clone it, open the folder in Claude Code (or hand it to any Claude with file access) and say:

Read SETUP-FOR-CLAUDE.md and set this up for me.

Claude interviews you first (OS, how you work, whether your code goes to GitHub, how you like to be talked to) and then installs and tailors it. Don't skip the interview: the conventions are only useful once they fit you.

Setup (by hand)

python rollup.py build                 # index the knowledge base (stdlib only)
bash tools/githooks/install.sh         # wire the git guards
pip install fastmcp flask              # MCP server + web panel (optional)
claude mcp add claude-sync -- python /full/path/to/mcp_server.py   # Claude Code
python server.py                       # bridge on 127.0.0.1:5151; then open dashboard.html

Windows tray monitor (optional): pip install pystray pillow, then powershell -ExecutionPolicy Bypass -File install_tray.ps1.

Before your first commit: this clone's origin points at the template. Your knowledge base is private, so git remote remove origin (or rename it upstream), and pick a push policy (below).

Code on GitHub? The push policy

tools/githooks/push-policy decides what may leave the machine:

• none (default): every push is blocked; ALLOW_PUSH=1 git push for a one-off.

• code: every code/<name>/ repo pushes freely; the knowledge base stays local.

• all: everything, notes included.

• or a list of repo names.

The knowledge base holds your notes about your work and you; most people want code at most.

Notes in each repo instead? (claude-sync.json)

By default notes live centrally in knowledge-base/projects/ and never leave the machine. If your repos already travel (cloud sessions, several machines, git pull everywhere), keep each project's notes inside its repo as HANDOFF.md and let claude-sync index them instead of owning them. Create claude-sync.json next to rollup.py (see claude-sync.example.json):

{
  "notes_home": "repo",
  "repo_roots": ["code", "~/src"],
  "learnings_path": "~/dotfiles/claude/learnings.md"
}

• notes_home: where NEW entries go: kb (central, the default) or repo (<repo>/HANDOFF.md, committed and pulled with the code). The rollup reads both kinds regardless, and a project with both shows both, labelled.

• repo_roots: folders whose sub-folders are your project repos; they don't have to live under this folder. Code search and the uncommitted-work report cover all of them.

• learnings_path: keep the cross-project lessons file somewhere that syncs (a dotfiles repo), instead of knowledge-base/_global/learnings.md.

• repo_handoff_names (optional): file names to look for, default HANDOFF.md, handoff.md, docs/HANDOFF.md.

get_project tells Claude where the next entry goes (append_next_entry_to). python test_notes_in_repo.py exercises the whole mode on a throwaway tree.

How a session uses it

1. Start: read learnings.md (the rulebook) and the project's handoff.md (get_project).

2. Work. Code goes in code/<name>/, its own repo.

3. End: append a dated entry to the handoff (what changed, what's verified vs assumed, what's next) where get_project says (append_next_entry_to), add_learning for cross-project lessons, build_rollup, and commit: in both layers in kb mode, or just the project repo in repo mode.

The single most important convention: never write "working" unless it was verified on the real thing. Notes that overclaim poison every later session.

Credits

Built by EzP41NB0W with Claude over a few months of firmware, CAD, web and homelab projects, then generalized for anyone. MIT licensed.