브랜치 로그

브랜치 로그를 사용하면 여러 에이전트가 같은 백업 snapshot에서 시작해 로컬 메모리를 독립적으로 기록한 뒤 유지할 브랜치만 병합할 수 있습니다.

메모리 자체가 실험의 일부일 때 유용합니다.

상황	브랜치 로그가 도움이 되는 이유
여러 클라우드 에이전트가 하나의 baseline에서 같은 작업을 시도	각 worker가 hot SQLite 파일을 공유하지 않고 자체 팩트를 기록합니다.
prompting, extraction, retrieval 전략 비교	candidate lesson을 분리하고 외부 평가 후 승자를 병합합니다.
위험한 자동화가 noisy 메모리를 기록할 수 있음	브랜치 로그를 push하고 검사한 뒤 유용할 때만 병합합니다.
에이전트 실행의 재생 가능한 아티팩트가 필요	segment JSONL과 manifest가 해당 브랜치가 추가하려 한 내용을 기록합니다.

브랜치 로그를 완전한 multi-master 충돌 해결로 사용하지 마세요. Merge는 멱등적이고 append 중심입니다. 중복 레코드는 건너뛰고 독립적인 새 팩트는 추가하며, 경쟁하는 두 결정 같은 semantic 충돌은 호출자 정책에 맡깁니다.

워크플로

Baseline 백업을 만듭니다.

aidememo --store ./main.sqlite backup create ./shared

백업을 별도의 candidate 저장소로 복원합니다.

aidememo --store ./candidate-a.sqlite backup restore ./shared/backup-01... --force
aidememo --store ./candidate-b.sqlite backup restore ./shared/backup-01... --force

서로 다른 시도를 실행하고 메모리를 로컬에 기록합니다.

aidememo --store ./candidate-a.sqlite fact add \
  "Candidate A used broad context and produced noisy results." \
  --type lesson \
  --entities Experiment

aidememo --store ./candidate-b.sqlite fact add \
  "Candidate B used focused context and produced the best result." \
  --type lesson \
  --entities Experiment

백업 cursor 이후의 delta로 각 브랜치를 push합니다.

aidememo --store ./candidate-a.sqlite branch push \
  --branch candidate-a \
  --base ./shared/backup-01... \
  ./shared

aidememo --store ./candidate-b.sqlite branch push \
  --branch candidate-b \
  --base ./shared/backup-01... \
  ./shared

승리한 브랜치만 병합합니다.

aidememo --store ./main.sqlite branch merge --branch candidate-b ./shared

브랜치를 버린다는 것은 병합하지 않는다는 뜻입니다. 저장된 아티팩트도 제거하려면 해당 브랜치 디렉터리 또는 S3 prefix를 삭제합니다.

./shared/branches/candidate-a/
s3://bucket/prefix/branches/candidate-a/

소스 아래의 모든 브랜치를 병합하려면 --branch를 생략합니다.

aidememo --store ./main.sqlite branch merge ./shared

SDK와 바인딩 호출

Python composition SDK는 코드 우선 에이전트에 같은 흐름을 제공합니다.

from aidememo_agent import Memory

candidate = Memory.open(store_path="./candidate-b.sqlite", storage_backend="libsqlite")
candidate.branch_push(
    "candidate-b",
    "./shared",
    base="./shared/backup-01...",
)

main = Memory.open(store_path="./main.sqlite", storage_backend="libsqlite")
main.branch_merge("./shared", branch="candidate-b")

aidememo-python은 branch_push(branch, destination, base=None)와 branch_merge(source, branch=None)을 제공합니다. aidememo-napi는 JSON 문자열 보고서를 반환하는 branchPush, branchMerge를 제공합니다. aidememo_nif는 decode된 map 보고서를 반환하는 AideMemoNif.branch_push/4, AideMemoNif.branch_merge/3을 제공합니다. 로컬 경로는 이미 열린 네이티브 저장소 handle을 사용하므로 SDK 또는 plugin 코드가 같은 파일을 다시 열지 않습니다. S3 지원은 CLI의 --features s3 빌드가 제어하므로 S3 브랜치 URI는 CLI를 사용해야 합니다.

저장 구조

로컬 브랜치 로그는 다음 경로에 저장됩니다.

<DEST>/branches/<branch-id>/segments/<segment-id>.jsonl
<DEST>/branches/<branch-id>/segments/<segment-id>.manifest.json

S3 브랜치 로그는 같은 prefix 구조를 사용하고 payload를 압축합니다.

s3://bucket/prefix/branches/<branch-id>/segments/<segment-id>.jsonl.zst
s3://bucket/prefix/branches/<branch-id>/segments/<segment-id>.manifest.json

각 segment manifest는 저장된 object와 decode된 JSONL payload 모두의 byte 수와 SHA-256 checksum을 기록합니다. Merge는 import 전에 이를 검증합니다.

보장과 한계

현재 보장하는 항목:

branch push --base <BACKUP>은 백업 manifest의 sync cursor 이후에 기록된 레코드를 내보냅니다.
branch merge --branch <ID>는 해당 브랜치만 가져옵니다.
같은 segment를 다시 병합해도 sync_import를 거치므로 팩트가 중복되지 않습니다.
S3는 브랜치 아티팩트 전송 수단이며 live database 백엔드가 아닙니다.

아직 보장하지 않는 항목:

Candidate의 자동 품질 평가
경쟁하는 결정 사이의 semantic 충돌 해결
일급 branch delete 명령
실행 중인 저장소 사이의 양방향 live replication

현재 검증 근거는 측정 원장의 "Branch Log Push / Merge"를 참고하세요.

워크플로​

SDK와 바인딩 호출​

저장 구조​

보장과 한계​

워크플로

SDK와 바인딩 호출

저장 구조

보장과 한계