세션 엔진: /wrap, 클린 슬레이트 rollup, 그리고 세션을 넘나드는 buffer

에이전트 작업이 잘못되는 경우를 떠올려 보면 보통 잘못된 편집을 떠올려요. 그런데 멀쩡히 끝낸 세션도 무너질 때가 있어요. 다음 세션이 이전에 무슨 일이 있었는지 알 수 없을 때예요.

답은 이전 대화에 있을지도 몰라요. 하지만 다음 에이전트가 채팅 transcript를 시스템 상태처럼 믿고 쓸 수는 없어요. transcript는 사라졌을 수도, 압축됐을 수도, 요약됐을 수도, 아니면 그냥 다시 읽기엔 너무 클 수도 있어요. 오래 버티는 시스템에는 더 작은 재시작 지점이 필요해요. 무엇이 바뀌었고, 무엇이 아직 열려 있고, 무엇부터 해야 하고, 근거는 어디에 있는지 같은 것들이요.

3B의 세션 엔진이 바로 이 일을 하려고 있어요.

`/wrap`은 대화를 파일로 바꿔요

지금의 아키텍처 모델은 /wrap을 수천 줄짜리 세션 종료 절차로 설명해요. 하지만 그 길이보다 중요한 건 /wrap이 긋는 경계예요. 세션 상태는 버전 관리되는 파일로 기록되기 전까지 보존됐다고 보지 않아요.

크게 보면 /wrap은 다섯 가지 일을 해요.

첫째, 무슨 일이 있었는지 journal에 기록해요. 세션은 journals/ 아래에 날짜별 항목으로 남고, 채팅을 다시 재생하지 않고도 결정을 복원할 만큼 충분한 내용을 담아요.

둘째, task 상태를 갱신해요. 진행 중인 task는 progress.md, todos.md, 그리고 보통 리뷰 산출물까지 들고 다녀요. progress.md의 ## Resume Here 블록은 실질적인 handoff 계약이에요. 마지막 작업, 다음 작업, 진행 중인 파일, branch나 worktree, 미결정 사항, 그리고 막힌 지점을 담아요.

셋째, 오래 남길 배움을 끌어올려요. 세션에서 다른 곳에도 옮겨 쓸 만한 교훈이 나왔다면, /wrap이 그걸 journal에 묻어 두는 대신 knowledge/로 옮길 수 있어요.

넷째, 상태 화면을 다시 만들어요. ACTIVE-STATUS.md는 손으로 고치지 않아요. 오래 남는 출처에서 투영해 만들기 때문에, 세션 시작 단계의 분류 작업이 사람이 들여다볼 상태와 똑같은 걸 읽을 수 있어요.

다섯째, 임시로 모아 둔 큐를 흡수한 뒤 비워요. buffer는 세션 도중 흘러나오는 부스러기를 잡아 두려고 있어요. 두 번째 knowledge 저장소가 되라고 만든 게 아니에요.

buffer는 메모리가 아니라 큐예요

.agents/buffer.md는 일부러 소박하게 뒀어요. 도구를 다루다 보면 그냥 사라졌을 마찰이나 후속 작업, 세션의 부스러기를 잡아 둬요. 중요한 설계 선택은 그다음에 일어나는 일이에요. /wrap이 buffer를 읽고, 오래 남길 만한 걸 뽑아낸 뒤, 비워요.

이렇게 하면 흔한 실패 두 가지를 막아요.

하나는 보이지 않는 메모리 함정이에요. 에이전트가 “이걸 기억해 둘게요”라고 말해도, 그 상태가 에이전트의 context window 안에만 있다면 다음 세션은 그걸 확인할 길이 없어요. buffer는 그 메모를 눈에 보이게 남겨 둬요.

다른 하나는 영원히 쌓이는 메모장이에요. 부스러기가 전부 영원히 남으면, 시스템은 천천히 잡동사니 서랍이 돼요. 오래 남길 걸 끌어올린 뒤에 buffer를 비우면, 권위 있는 출처가 아니라는 바로 그 점 덕분에 계속 쓸모 있게 남아요.

`Resume Here`는 재시작 API예요

진행 중인 task에서 가장 중요한 건 체크리스트가 아닐 때가 많아요. 재시작한 뒤 첫 번째로 할 구체적인 작업이에요.

3B는 그걸 progress.md에 정해 둬요.

마지막 작업
다음 작업
진행 중인 파일
branch 또는 worktree
미결정 사항
막힌 지점

이 항목들은 일부러 밋밋하게 뒀어요. handoff를 망치는 두 가지, 즉 서술의 모호함과 주인 없는 작업을 피하려고요. 새 세션은 어떤 worktree를 써야 하는지, 어떤 파일이 움직이고 있었는지, 다음 단계가 구현인지 리뷰인지 검증인지 아니면 보관인지를 볼 수 있어요.

/wrap이 건드린 progress 파일을 손봐 주는 이유도 여기 있어요. 세션 엔진은 작성자가 모든 handoff 항목을 일일이 기억하리라고 믿지 않아요. 재시작 가능성은 이 repo의 부가 기능이 아니라 제품 요구사항이라서, 형태를 직접 점검해요.

rollup은 클린 슬레이트예요

대부분의 노트 시스템은 요약을 남기고 원본 재료는 결국 잊어버려요. 3B는 journal에 대해 정반대로 해요.

날짜별 항목은 영구적이에요. 가장 작은 단위의 근거니까요. 주간, 월간, 분기 rollup은 잠깐 쌓는 집계 층이에요. 상위 층이 한 번 흡수하고 나면, 중간 rollup은 지워도 돼요. 연간 요약은 다시 영구적이에요. 오래 남는 최상위 관점이니까요.

덕분에 journal 트리는 쓸모 있는 성질을 가져요. 요약된 층이 원본 세션 기록보다 더 권위 있는 척하지 않으면서도 계속 둘러보기 좋게 남아요. 주간 요약이 틀렸어도 날짜별 기록은 그대로 있어요. 월간 요약이 그 주를 흡수했다면, 주간 파일은 제 할 일을 다 한 거예요.

rollup 전략은 단순한 청소가 아니에요. 어떤 산출물이 원본 재료이고 어떤 게 다시 만들 수 있는 결과물인지를 담은 보존 정책이에요.

이게 에이전트에 왜 중요할까요

멀티 에이전트 시스템에서는 context 손실이 더 나빠져요. runtime마다 전송 방식이 다르기 때문이에요. Claude, Codex, AGY 모두 3B에 참여할 수 있지만, 이들 중 누구도 이전 runtime의 사적인 메모리를 물려받으리라고 믿어선 안 돼요.

파일이 공통 규약이에요.

그래서 /wrap은 journal, task 상태, knowledge 후보, 마찰 신호, 그리고 다시 만든 대시보드를 기록해요. 같은 이유로 progress.md가 재시작 계약을 담고, buffer는 흡수한 뒤에만 비워요. rollup도 마찬가지로 흡수한 요약은 지우면서 날짜별 기록은 바꾸지 않고 그대로 둬요.

형태는 단순해요. 앞으로의 작업에 필요한 건 남기고, 이미 흡수한 건 지우고, 다음 세션은 파일로 자기 상태를 증명하게 만들어요.

그대로 따라 하지는 않을 부분

수천 줄짜리 wrap 절차를 처음부터 쓰는 일은 안 할 거예요.

그 길이는 쌓여 온 실패 양상이 남긴 흔적이에요. 오래된 task 문서, 잊힌 후속 작업, 끝내 규칙이 되지 못한 마찰, 더러운 체크아웃 충돌, 끝없는 리뷰 반복, 흐트러진 active-status, 그리고 에이전트끼리의 차이 같은 것들이요. 쓸 만한 패턴은 더 작아요.

오래 남길 journal 출처 하나를 고르세요.
진행 중인 task마다 재시작 블록을 주세요.
세션 부스러기를 위한 눈에 보이는 buffer를 두세요.
오래 남길 배움을 buffer에서 끌어올리세요.
중간 요약은 다시 만들 수 있는 것으로 다루세요.

모든 팀에 3B의 wrap machinery가 똑같이 필요하다는 얘기는 아니에요. 핵심은 에이전트 작업에 세션 엔진이 필요하다는 거예요. 세션 엔진이 없으면, handoff 경계는 마지막 채팅이 어쩌다 기억한 것에 휘둘리게 돼요.

/wrap은 대화를 파일로 바꿔요