머신 간 에이전트 메모리 동기화

On this page

블로샤퍼를 개발하면서 여러 머신에 같은 프로젝트를 받아 놓고 작업했습니다. 소스 코드는 Git으로 옮기면 됐습니다. 그런데 다른 머신에서 AI 에이전트와 작업을 시작하면, 코드 외에 설명할 것이 꽤 남았습니다.

왜 이 구조를 선택했는지, 어떤 방법을 시도했다가 포기했는지, 지난번에 제가 무엇을 고쳐 달라고 했는지. 코드는 최신인데 에이전트는 그 과정에 참여한 적이 없었습니다. 하던 일을 이어 가려다가 다시 배경부터 설명하게 되는 겁니다.

에이전트가 로컬에 남긴 메모리도 함께 옮기면 이 반복을 줄일 수 있겠다고 생각했습니다.

코드와 함께 옮기고 싶었던 것

제가 이어 가고 싶었던 것은 작업의 맥락이었습니다. 이미 합의한 방향을 다시 논의하거나, 실패했던 방법을 이유도 모른 채 재시도하지 않도록 하고 싶었습니다.

AGENTS.md나 CLAUDE.md 같은 하네스에는 작업 규칙을 적습니다. 메모리에는 작업하면서 알게 된 사실과 판단의 이유가 쌓입니다. 둘의 내용이 일부 겹치기도 하지만, 제가 동기화하려던 핵심은 후자였습니다.

예를 들어 어떤 구현을 선택했다는 기록에는 다른 방법을 버린 이유도 있어야 했습니다. 다음에 비슷한 문제를 만났을 때 참고할 수 있기 때문입니다. 반면 현재 코드의 구조를 길게 설명한 메모는 구현이 바뀌면 금세 낡았습니다. 저장소를 읽으면 알 수 있는 내용을 따로 복제할 필요는 없었습니다.

대화 복제에서 지식 인수인계로

Antigravity에서는 처음에 대화 데이터를 옮겨 보았습니다. 다른 머신에서도 같은 대화를 그대로 이어 갈 수 있다면 가장 간단할 것 같았습니다.

실제로는 그렇게 되지 않았습니다. 파일을 복사해도 IDE에서 세션을 제대로 인식하지 못했고, 머신마다 다른 경로도 문제였습니다. 대화 데이터 자체도 계속 커졌습니다.

그래서 동기화 대상을 바꿨습니다. Antigravity의 KI, 즉 Knowledge Items로 정리된 지식과 작업 인수인계 내용을 옮기는 방식입니다. 완료한 일과 남은 일, 다음에 볼 파일, 주의할 사항을 정리해 두고 다른 머신에서 참고하도록 했습니다.

모든 대화를 되살리지는 못해도 다음 작업을 시작할 재료는 전달할 수 있었습니다. 무엇을 기억으로 남길지 정리하는 과정이 필요했습니다.

프로젝트 메모리를 위한 별도 저장소

Claude Code에서는 처음에 프로젝트 저장소 안에서 메모리를 관리하는 방식을 시도했습니다. 이후 8월에는 프로젝트 메모리를 비공개 Git 저장소로 분리했습니다. 메모리까지 프로젝트 작업 트리에 섞여 있으면 기능 개발의 커밋이나 브랜치 작업에 함께 휘말릴 수 있었기 때문입니다.

메모리는 인덱스와 주제별 파일로 관리하고, 각 머신의 로컬 메모리 위치를 심볼릭 링크로 연결했습니다. 프로젝트를 받아 놓은 경로가 달라도 같은 프로젝트의 메모리를 가리키도록 맞췄습니다.

세션을 시작할 때 최신 메모리를 내려받고, 작업 응답이 끝나는 Stop 훅에서 변경 내용을 커밋한 뒤 원격 변경을 반영하고 올리도록 구성했습니다. 매번 제가 메모리 저장소를 찾아가서 Git 명령을 실행하지 않아도 되게 하는 것이 목적이었습니다.

공통 지침이나 스킬도 일부 함께 관리했습니다. 여러 머신에서 어떤 정보를 공유해야 작업이 이어지는지를 기준으로 삼았습니다.

다른 머신에서 작업을 이어가는 과정

아래는 8월에 메모리를 별도 저장소로 분리한 뒤 사용한 Claude Code 방식입니다. Antigravity의 KI 동기화와는 별개입니다. 각 머신에 메모리 저장소를 하나씩 받아 두고, 프로젝트별 메모리 경로를 그 안의 해당 프로젝트 폴더에 연결했습니다.

sequenceDiagram participant A as 머신 A · Claude participant L as A의 로컬 메모리 participant R as 원격 Git 저장소 participant M as B의 로컬 메모리 participant B as 머신 B · Claude Note over A,L: 프로젝트 코드와 별도 저장소<br/>메모리 경로는 심볼릭 링크로 연결 A->>L: SessionStart 훅 L->>R: fetch R-->>L: 원격 변경 Note over L: ff-only로 반영<br/>불가하면 기존 로컬 상태 유지 A->>L: 필요한 메모리 읽기 A->>L: 작업 후 결정과 남은 일 기록 A->>L: 응답 종료 · Stop 훅 L->>L: 변경 커밋 L->>R: pull --rebase alt 반영 성공 L->>R: push else rebase 충돌 L->>L: rebase 중단 · 로컬 커밋 보존 Note over A,L: 충돌 내용 확인 후 해결 end Note over L,R: push 실패도 로컬 커밋 보존 B->>M: SessionStart 훅 M->>R: fetch R-->>M: A에서 올린 변경 Note over M: ff-only로 반영 B->>M: 심볼릭 링크를 통해 메모리 읽기 Note over M,B: 같은 방식으로 기록·동기화

그림의 메모리 폴더는 원격 파일을 직접 열어 쓰는 공유 드라이브가 아닙니다. 머신마다 로컬 복제본이 있고, Git으로 변경을 주고받습니다. 프로젝트 코드는 원래 코드 저장소에서 따로 관리합니다.

머신별 연결: 각 머신의 Claude 프로젝트 메모리 경로가 로컬 메모리 저장소의 같은 프로젝트 폴더를 가리키도록 심볼릭 링크를 만듭니다. 기존 메모리가 있으면 백업하고, 내용이 다른 파일과 인덱스는 확인해서 합칩니다. 머신마다 다른 절대 경로를 그대로 공유하지 않는 이유입니다.

시작할 때 가져오기: SessionStart 훅에서 원격 변경을 가져와 fast-forward가 가능할 때만 반영합니다. 실패해도 세션은 시작되므로, 이때 로컬 메모리가 최신이라는 보장은 없습니다.

기록한 뒤 보내기: Claude가 작업 중 메모리를 수정하면, 응답이 끝날 때 Stop 훅이 저장소의 변경을 커밋하고 pull --rebase 후 push합니다. 훅이 기억할 내용을 대신 작성하는 것은 아닙니다. 이미 파일에 기록한 내용을 옮기는 역할입니다.

Stop은 앱을 닫는 순간이 아니라 Claude가 응답을 마치는 시점입니다. 훅의 실행 시점은 Claude Code 공식 설명에서도 확인할 수 있습니다.

다음 작업에 필요한 메모리 예시

인덱스인 MEMORY.md에는 주제 파일을 찾을 수 있는 짧은 설명을 두고, 세부 내용은 해당 파일에 남겼습니다. 아래는 형식을 보여 주기 위한 가상 예시입니다. 실제 프로젝트 메모리를 발췌한 것은 아닙니다.


인덱스
- save-recovery.md: 저장 실패 시 복구 방침과 다음 검증 항목

주제 파일: save-recovery.md
- 현재 목표: 저장 도중 앱이 종료돼도 직전 데이터를 복구할 수 있게 하기
- 결정과 이유: 임시 파일에 쓴 뒤 교체하기. 쓰다가 기존 파일이 손상되는 경우를 줄이기 위해서
- 시도한 방법: 기존 파일에 바로 덮어쓰기는 중단 상황을 다루기 어려워 보류
- 남은 작업: 쓰기 중 강제 종료 테스트와 오류 안내 확인
- 다음에 볼 파일: src/storage/save.ts, tests/save-recovery.test.ts

이 정도가 남아 있으면 다른 머신에서도 무엇을 다시 확인해야 하는지 알 수 있습니다. 완료한 검증은 기록을 갱신하고, 당장 필요한 진행 상황과 오래 남길 결정의 이유를 구분해 정리합니다.

충돌과 실패 처리

두 머신이 같은 파일을 수정하면 Git 동기화도 충돌할 수 있습니다. 제 구현은 MEMORY.md에 union 병합을 적용해 양쪽 인덱스 항목을 남겼지만, 중복이나 내용의 모순까지 해결해 주지는 않았습니다. 주제 파일에서 rebase 충돌이 나면 rebase를 중단하고 로컬 커밋을 보존하도록 했습니다.

전송만 실패한 커밋은 이후 훅 실행에서 다시 보낼 수 있게 했습니다. 충돌은 내용을 확인하고 해결해야 합니다. 이 훅들은 작업 세션을 막지 않도록 종료되기 때문에, 응답이 끝났다는 사실만으로 동기화 성공을 판단해서도 안 됩니다.

공유 범위도 정해야 합니다. 인증 정보나 다른 환경으로 옮기면 안 되는 자료는 메모리 저장소에 넣지 않아야 하고, 머신별 경로 연결은 각 머신에서 따로 설정해야 합니다. 메모리 동기화가 프로젝트 전체나 계정 설정 전체의 복사가 되지 않도록 하는 편이 좋습니다.

저장한 기억과 실제로 쓰이는 기억

동기화를 붙였다고 모든 문제가 해결되지는 않았습니다. 파일이 존재하는 것과 에이전트가 필요한 순간에 그 내용을 찾아 쓰는 것은 별개의 문제였습니다. 반드시 지켜야 할 규칙은 메모리에만 적어 두지 않고 하네스나 검증 절차에도 반영해야 했습니다.

동기화 실패도 눈에 보여야 했습니다. 작업을 방해하지 않으려고 오류를 조용히 넘기면, 저는 같은 기억을 보고 있다고 생각하는데 실제로는 머신마다 내용이 달라질 수 있었습니다.

충돌 역시 자동으로 합친다고 끝나는 일이 아니었습니다. 두 문장이 모두 남아 있어도 서로 모순될 수 있고, 한쪽을 무작정 선택하면 필요한 기록을 잃을 수 있습니다. 실패했을 때 내용을 보존하고, 확인할 수 있게 남기는 일이 중요했습니다.

메모리 자체의 정리도 필요했습니다. 특히 현재 진행 상태는 빠르게 낡습니다. 끝난 일을 계속 다음 작업으로 안내하지 않도록 갱신해야 했습니다. 오래 쓸 수 있었던 것은 대체로 결정의 이유와 실패에서 얻은 교훈이었습니다.

📝

이후 덧붙임 · 동기화를 멈춘 이유

지금은 두 동기화를 모두 중지했습니다. 다만 이유는 서로 다릅니다.

Antigravity 동기화는 주력 개발 도구가 Claude Code로 옮겨 가면서 필요가 줄었습니다. Claude 메모리 동기화는 다른 작업 머신에 프로젝트를 따로 받아 작업하는 일이 없어지고, 프로젝트도 막바지에 접어들면서 멈췄습니다.

원격 작업 환경이 좋아진 영향도 큽니다. 이제는 휴대폰이나 다른 기기에서 집에 있는 머신의 작업 상황을 확인하고 지시할 수 있습니다. 기기를 바꿀 때마다 별도의 작업 환경으로 옮겨 가기보다, 기존 환경의 세션에 접속해 이어 가는 일이 많아졌습니다.

메모리는 여전히 중요하게 사용합니다. 달라진 것은 여러 머신에 같은 기억을 복제할 필요입니다.

같은 프로젝트를 여러 곳에 독립적으로 받아 작업한다면 이 방식은 여전히 유용할 것 같습니다. 제 경우에는 소스 코드만 옮겨서는 이어지지 않던 부분을 메모리로 보완할 수 있었습니다. 다른 머신에서도 지난 결정의 이유를 다시 설명하지 않고 다음 일을 시작할 수 있다는 것. 당시 제가 해결하고 싶었던 문제는 거기까지였습니다.