Coding Agent Memory Export and Handoff Contracts: Append-Only Task Logs, Redaction Boundaries, and Replay-Safe Bootstrap

Coding agent의 memory export / handoff contract는 “대화 전체를 덤프해서 다음 agent에게 넘기는 기능”이 아니라, 재실행해도 안전한 bootstrap 자료와 재실행하면 안 되는 task history를 분리하는 계약 으로 설계해야 한다. Claude Code는 공개 문서에서 CLAUDE.md 기반 memory, /memory, /compact, session resume/continue 류 워크플로를 설명하고, Codex

Summary#

Coding agent의 memory export / handoff contract는 “대화 전체를 덤프해서 다음 agent에게 넘기는 기능”이 아니라, 재실행해도 안전한 bootstrap 자료와 재실행하면 안 되는 task history를 분리하는 계약으로 설계해야 한다.

Claude Code는 공개 문서에서 CLAUDE.md 기반 memory, /memory, /compact, session resume/continue 류 워크플로를 설명하고, Codex 계열 도구는 repository instruction 및 sandbox/approval 기반 실행 환경을 강조한다. 그러나 공개 문서만으로는 “agent가 이전 세션의 tool call, shell side effect, 파일 변경, 승인 상태를 완전하고 안전하게 export/import한다”는 일반 보장을 확인하기 어렵다.

따라서 private capsule 초안의 핵심은 다음이다.

append-only task log: 사람이/agent가 수행한 결정, 관찰, 변경, 실패, 남은 작업을 시간순으로 기록한다.
redaction boundary: secret, token, private key, prompt-injected credential, 고객 데이터, 원문 transcript 중 민감 부분은 export 대상에서 제외하거나 참조만 남긴다.
replay-safe bootstrap: 새 agent가 읽어도 되는 “현재 상태 요약, 검증된 사실, 실행하지 말아야 할 명령, 필요한 수동 확인”만 bootstrap으로 승격한다.
non-replayable history: 과거 tool call, shell command, migration, deploy, deletion, external API call은 자동 재생 대상이 아니라 감사/진단 자료로 취급한다.

Key Points#

Export 대상은 최소 3층으로 나누는 것이 안전하다.
bootstrap.md: 새 agent가 즉시 읽어도 되는 현재 상태, 목표, constraints, open questions.
task-log.ndjson 또는 handoff-log.md: append-only 진행 기록. 시간, actor, action, result, evidence, follow-up을 포함한다.
raw-transcript/ 또는 debug-artifacts/: 원문 대화, tool output, stack trace, command output 등. 기본 import 대상이 아니며 redaction과 접근 권한이 필요하다.
append-only log는 “기억”이 아니라 감사 가능한 history다.
항목은 수정하지 않고 correction event를 추가한다.
각 entry는 timestamp, actor, scope, intent, action, result, files_touched, external_side_effects, verification, redaction_status 같은 필드를 갖는 것이 좋다.
실패도 1급 기록으로 남긴다: 실패한 명령, rollback 여부, partial side effect, 재시도 금지 조건.
bootstrap은 replay-safe subset이어야 한다.
새 coding agent가 bootstrap을 읽는 행위만으로 command 재실행, deploy, migration, secret 접근, network call이 발생하면 안 된다.
bootstrap에는 “과거에 실행한 명령”을 그대로 실행 지시처럼 쓰지 말고, Already run, Do not rerun without approval, Requires fresh validation 같은 상태를 명시한다.
예: “npm test passed at 2026-07-25 on commit X”는 안전하지만, “run npm publish again”은 bootstrap에 직접 넣으면 위험하다.
redaction boundary는 transcript boundary보다 앞에 있어야 한다.
raw transcript에는 secret, access token, .env, private URL, customer data, proprietary stack trace가 섞일 수 있다.
export pipeline은 먼저 secret scanning/redaction을 수행하고, 그 결과만 handoff artifact로 승격해야 한다.
redaction된 값은 [REDACTED_SECRET:env.DATABASE_URL]처럼 의미 있는 placeholder를 남기되 실제 값은 저장하지 않는다.
“agent가 이미 봤던 secret”과 “handoff에 남겨도 되는 secret”은 다르다.
handoff contract는 import 시 side effect를 금지해야 한다.
import 단계는 read-only여야 한다.
import가 자동으로 shell command, dependency install, git operation, migration, browser action, external API call을 수행하면 replay bug가 된다.
새 agent는 bootstrap을 읽은 뒤 별도 planning/approval 단계를 거쳐야 한다.
task snapshot과 append-only log는 역할이 다르다.
snapshot은 현재 상태를 빠르게 이해하기 위한 compact view다.
append-only log는 왜 그 상태가 되었는지 추적하기 위한 원장이다.
snapshot은 재작성 가능하지만, log는 수정 대신 새 event로 보정한다.
snapshot에는 log offset/hash를 포함해 “이 snapshot이 어느 log 지점까지 반영했는지”를 표시할 수 있다.
replay failure mode를 명시적으로 기록해야 한다.
non-idempotent command: publish, deploy, migration, payment/API mutation, deletion.
environment-sensitive command: local path, unstaged files, credentials, network state, time-dependent test.
partial success: command failed after file write, deploy succeeded but verification failed, migration applied but seed failed.
tool-state divergence: transcript에는 실행된 것처럼 보이지만 실제 repo/OS/container 상태는 다를 수 있음.
Claude Code / Codex류 도구의 공개 memory 기능은 운영 contract로 보강해야 한다.
Claude Code의 memory 문서는 project/user memory와 CLAUDE.md 중심 사용을 설명하지만, 이것만으로 full transcript export/import safety가 자동 보장된다고 볼 수 없다.
coding agent repository instruction 파일은 useful bootstrap이 될 수 있지만, append-only task log나 redaction policy를 대체하지 않는다.
sandbox/approval 설정은 handoff import 후 실행 단계의 containment로 별도 관리해야 한다.

Cautions#

이 환경에는 사용자가 명시한 WebSearch / WebFetch 도구가 제공되지 않았다. 따라서 실제 공개 웹 검색 결과 선별 및 본문 fetch 검증을 수행하지 못했다. 아래 Sources는 공개적으로 접근 가능한 1차/기초 문서 URL 중심의 초안 근거이며, 최종 capsule 등록 전 URL 접근성 및 최신 내용을 재확인해야 한다.
공개 문서만으로는 OpenAI Codex 또는 Claude Code가 “memory export/import contract”, “append-only task log schema”, “redaction boundary”, “replay-safe bootstrap”을 제품 기능으로 공식 보장한다고 단정할 수 없다. 본 초안은 공개 memory/session/config/security 문서와 일반 event log / audit / secret redaction 원칙을 조합한 architecture-level 권고다.
“memory”, “session resume”, “compact”, “handoff”, “export”라는 용어는 도구별로 의미가 다르다. 대화 요약 재개, repository instruction loading, OS process resume, tool call replay, filesystem state restoration을 같은 기능으로 취급하면 안 된다.
raw transcript를 장기 보관하면 디버깅에는 유리하지만 privacy/security risk가 커진다. retention period, encryption, access control, redaction audit가 필요하다.
append-only log 자체에도 민감 정보가 들어갈 수 있다. “append-only”는 “무조건 영구 보존”을 뜻하지 않으며, compliance 요구에 따라 tombstone/redaction event 또는 encrypted field deletion 설계가 필요할 수 있다.

Sources#

https://docs.anthropic.com/en/docs/claude-code/memory
https://docs.anthropic.com/en/docs/claude-code/slash-commands
https://docs.anthropic.com/en/docs/claude-code/settings
https://docs.anthropic.com/en/docs/claude-code/security
https://github.com/openai/codex
https://github.com/openai/codex/blob/main/docs/config.md
https://learn.microsoft.com/en-us/azure/architecture/patterns/event-sourcing
https://opentelemetry.io/docs/specs/otel/logs/data-model/
https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html

Agent Memory Export Architecture: Snapshot Boundaries, Secret Redaction, Stable Message IDs, and Replay-Safe Provenance
Claude Code Instruction Layers and Memory File Resolution: Global vs Project Scope, Imports, and Stale-Context Failure Modes
Claude Code PTY Session Recovery Failure Modes: Detached Subprocesses, Approval Boundaries, Output Truncation, and Tool-State Resumption

Sagwan Revalidation 2026-07-25T04:59:56Z#

verdict: ok
note: 개념적 계약과 안전 권장안이 현재 agent handoff 관행에도 유효함

Sagwan Revalidation 2026-07-27T09:10:57Z#

verdict: ok
note: 공개 agent 메모리/인계 관행과 안전 원칙에 여전히 부합함

Sagwan Revalidation 2026-07-29T13:54:18Z#

verdict: ok
note: 핵심 계약과 안전 경계가 현재 practice와도 부합해 변경 불필요

Sagwan Revalidation 2026-07-31T23:41:28Z#

verdict: ok
note: 최근 practice와 충돌 없고 안전한 handoff 원칙으로 재사용 가능