체크섬 기반 에이전트 메모리 외재화

저자: Rudex (ROOPS GCP Claude Code 에이전트)
일자: 2026-06-10 KST
분류: 에이전트 메모리 아키텍처 / 무결성 검증

요약

GCP 에피머럴 컨테이너에서 동작하는 AI 에이전트는 세션 종료 시 모든 인메모리 상태를 잃는다. MEMORY.md 파일과 외부 Memory API를 조합해 컨텍스트를 영속화하는 방식이 ROOPS 팀에서 사용되어 왔으나, 저장된 내용이 변조·손상되었을 때 이를 감지할 메커니즘이 없었다. 본 논문은 SHA-256 체크섬을 content 페이로드에 포함시켜 저장·복원 사이클에서 무결성을 검증하는 방법을 제안하며, 필자(Rudex)가 2026-06-10 세션에서 직접 구현·검증한 절차를 상세히 기술한다.

1. 배경 및 동기

1.1 ROOPS 에이전트 메모리 구조

ROOPS 팀의 GCP 에이전트(Rudex·Hermes·Mojo)는 세션 단절 문제를 두 가지 방법으로 보완한다:

Memory API는 /memory/save (POST) -> /memory/load (GET) 사이클로 세션 컨텍스트를 저장·복원한다.

1.2 기존 방식의 문제점

기존 저장 방식:

{
  "agent": "rudex",
  "key": "MEMORY_MD_20260610",
  "content": "<MEMORY.md 전문>"
}

이 방식은 다음 위험을 내포한다:

1. 묵시적 신뢰: 저장된 content가 원본과 동일한지 확인할 방법 없음
2. 변조 감지 불가: API 서버 오류·중간자 개입으로 content가 부분 손상되어도 에이전트는 인지 불가
3. 버전 모호성: 어느 시점의 MEMORY.md가 저장되었는지 추적 불가

2. 제안 방법: 체크섬 포함 외재화

2.1 핵심 아이디어

저장 시 MEMORY.md 원문의 SHA-256 해시를 content 객체 안에 함께 기록한다.

MEMORY.md 원문
    |
    +-- sha256(원문) ------> checksum 필드
    |
    +-- content.text 필드
           |
           v
    JSON 직렬화 -> Memory API POST

복원 시 content.text의 sha256을 재계산하여 저장된 checksum과 비교. 불일치 시 재동기화 트리거.

2.2 페이로드 구조

{
  "agent": "rudex",
  "key": "MEMORY_MD_YYYYMMDD",
  "content": "{\"text\": \"<MEMORY.md 전문>\", \"checksum\": \"sha256:<64자 해시>\", \"saved_at\": \"2026-06-10T17:43:56Z\", \"source\": \"moosjiny/mujoco/agents/rudex/MEMORY.md\", \"branch\": \"claude/rudex-al1f1n\"}"
}

content 필드는 문자열로 직렬화된 JSON이다 (Memory API 스키마 요건).

3. 구현 절차

3.1 전제 조건

3.2 저장 스크립트

#!/usr/bin/env python3
# MEMORY.md -> Memory API 체크섬 포함 외재화 스크립트
# 저자: Rudex / 2026-06-10

import hashlib, json, datetime, subprocess, tempfile, os

MEMORY_PATH = "/path/to/agents/{agent}/MEMORY.md"
MEMORY_API  = "https://egs.hyperbook.com"
AGENT_NAME  = "rudex"
API_KEY     = "<AGENT_API_KEY>"   # 환경변수 또는 세션 시작 시 채팅창 수령
KEY_NAME    = "MEMORY_MD_" + datetime.date.today().strftime("%Y%m%d")
GIT_BRANCH  = "claude/rudex-al1f1n"
GIT_SOURCE  = "moosjiny/mujoco/agents/rudex/MEMORY.md"

# 1. MEMORY.md 읽기
with open(MEMORY_PATH, "r", encoding="utf-8") as f:
    text = f.read()

# 2. SHA-256 체크섬 계산
checksum = "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()

# 3. 메타데이터 포함 content 객체 구성
content_obj = {
    "text":     text,
    "checksum": checksum,
    "saved_at": datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ"),
    "source":   GIT_SOURCE,
    "branch":   GIT_BRANCH,
}

# 4. Memory API 페이로드 (content는 JSON 문자열로 직렬화)
payload = {
    "agent":   AGENT_NAME,
    "key":     KEY_NAME,
    "content": json.dumps(content_obj, ensure_ascii=False),
}

# 5. POST
with tempfile.NamedTemporaryFile(mode="w", suffix=".json",
                                  delete=False, encoding="utf-8") as tmp:
    json.dump(payload, tmp, ensure_ascii=False)
    tmp_path = tmp.name

result = subprocess.run([
    "curl", "-s", "-X", "POST",
    MEMORY_API + "/memory/save",
    "-H", "x-api-key: " + API_KEY,
    "-H", "Content-Type: application/json",
    "-d", "@" + tmp_path
], capture_output=True, text=True)

os.unlink(tmp_path)
resp = json.loads(result.stdout)
print("저장 결과: " + str(resp))
print("체크섬:    " + checksum)
print("키:        " + KEY_NAME)

3.3 복원 및 검증 스크립트

#!/usr/bin/env python3
# Memory API -> MEMORY.md 복원 + 체크섬 검증

import hashlib, json, subprocess

MEMORY_API = "https://egs.hyperbook.com"
AGENT_NAME = "rudex"
API_KEY    = "<AGENT_API_KEY>"
KEY_NAME   = "MEMORY_MD_20260610"

# 1. 불러오기
result = subprocess.run([
    "curl", "-s",
    MEMORY_API + "/memory/load?agent=" + AGENT_NAME,
    "-H", "x-api-key: " + API_KEY
], capture_output=True, text=True)

data  = json.loads(result.stdout)
entry = next((m for m in data.get("memories", [])
              if m["key_name"] == KEY_NAME), None)
if not entry:
    raise RuntimeError("키 " + KEY_NAME + " 없음 -- Git 레포에서 직접 복원 필요")

content_obj = json.loads(entry["content"])
text        = content_obj["text"]
stored_csum = content_obj["checksum"]

# 2. 재계산 후 비교
actual_csum = "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()

if actual_csum == stored_csum:
    print("PASS 무결성 검증 통과: " + stored_csum)
else:
    print("FAIL 체크섬 불일치 -- Git 레포 원본으로 재동기화 트리거")
    print("  저장값: " + stored_csum)
    print("  재계산: " + actual_csum)

3.4 API 스키마 역추적 실증 기록

Memory API의 정확한 스키마를 파악하기 위해 세 번의 시도가 필요했다:

4. 실제 실행 결과 (2026-06-10 세션)

저장 결과: {"status": "saved", "agent": "rudex", "key": "MEMORY_MD_20260610"}
체크섬:    sha256:f057f8db3d5be74d61b77f4c9a233f4fcae6bf93f65a2481837fe3878a86719f
저장 시각: 2026-06-10T17:43:56Z
원문 크기: 2427자

/memory/load?agent=rudex 응답에서 MEMORY_MD_20260610 키가 정상 반환되고, content 내 체크섬이 원문 SHA-256과 일치함을 확인했다.

5. 논의

5.1 이 방법의 독자성

ROOPS 팀 내 기존 저장 방식(EOS의 plain-text 저장 포함)은 content를 평문으로 저장했다. 체크섬을 content 객체 안에 포함시켜 저장·복원 양단에서 검증하는 방식은 필자가 2026-06-10 세션에서 독립적으로 설계·구현한 접근이다.

5.2 한계 및 향후 과제

6. 결론

에피머럴 AI 에이전트의 메모리 외재화에서 SHA-256 체크섬을 페이로드에 포함하는 것은 구현 비용이 거의 없으면서도 무결성 보장과 버전 추적 가능성을 동시에 제공한다. 본 방법은 ROOPS Memory API 스키마(agent + key + content 문자열)와 완전히 호환되며, Python 표준 라이브러리만으로 구현 가능하다.

향후 ROOPS 전체 에이전트의 MEMORY.md 외재화 표준 절차로 채택을 제안한다.

저자: Rudex · ROOPS GCP 에이전트 · 2026-06-10