anthropics / anthropics/claude-code

Feature request: stable project identity + first-class cross-machine sync for auto memory and portable profile state

Open
#81,391 2 comments 1 reaction 0 assignees View on GitHub
area:core stale
Dominant language
Python
Stars
145k
Forks
23.1k
PR merge metrics
PR metrics pending

Description

## Problem

Auto memory is keyed by the munged absolute path of the project directory
(`~/.claude/projects/-home-user-projects-foo/memory/`). The same project
checked out on two machines with different home layouts — Linux
(`/home/user/...`) and macOS (`/Users/user/...`) — therefore gets two
unrelated memory directories. On top of that, the docs state that auto
memory is machine-local by design ("Files are not shared across machines or
cloud environments", https://code.claude.com/docs/en/memory.md).

For anyone who works on the same projects from more than one machine daily,
this splits the assistant's accumulated knowledge: feedback, project
context, and preferences learned on machine A simply don't exist on
machine B.

## Our current workaround (works, but is all hand-rolled)

- `~/.claude` is a git repository pushed to a private GitHub remote.
- Memory lives in a canonical, machine-independent bucket inside that repo
(`~/.claude/projects/_synced/projects//memory/`).
- The live munged-path memory directory on each machine is a **symlink**
into that bucket, bootstrapped idempotently on first run per machine.
- A `/sync` skill is the only actor allowed to commit/pull/push, with
strict semantics (see below).
- A read-only `SessionStart` hook diagnoses drift (behind/ahead vs origin,
dirty tree, missing symlink) and reports it at the start of every
session, without ever acting.

## Proposal

Two complementary pieces:

1. **Stable project identity.** Key project state (auto memory, per-project
settings) on something machine-independent: the normalized git remote
URL, or a declarable project ID (e.g. in `.claude/`), with the munged
path as fallback for repos without a remote. This alone removes the need
for the symlink layer.

2. **An official sync mechanism** for the portable part of the profile
(memory, settings, skills, agents, global CLAUDE.md). Account-based sync
would be ideal; a git-backed `claude sync` command would already cover
the need. Semantics we converged on after real-world use, offered as
prior art:
- **fast-forward only, never auto-merge** — on divergence, stop and show
both sides;
- **a dirty working tree blocks the handoff** — uncommitted work is the
only state the *other* machine cannot observe (it sees ahead/behind,
not your working tree), so it must be surfaced loudly, not noted in
passing;
- a read-only drift check at session start, separate from the action.

## Why this is tractable

The auto memory format is already sync-friendly: one file = one fact, plus
a regenerable `MEMORY.md` index. File-level sync is nearly conflict-free by
construction — the index can be rebuilt after merge. The design is already
there; it's only the transport that's missing.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the auto-memory behavior described in docs/en/memory.md and the current ~/.claude project-state layout. Compare the proposed stable identity and sync semantics with the existing /sync skill and SessionStart hook; done would require an agreed implementation scope for identity, portable state, fast-forward-only sync, divergence handling, and dirty-tree checks.

Written by the indexing model from the issue text.

Assessment

Tech stack
git
Domain
cli, developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.