세션이 죽어도 살아남는 프로젝트 기억 만들기

AI에게 시킨 프로젝트가 며칠에 걸치기 시작하면 이상한 일이 벌어진다. 어제 한참을 의논해 정한 방향을 오늘 세션은 모른다. 한 번 실패해서 버린 방법을 다시 꺼내든다. 어디까지 했는지 물으면 대화를 거슬러 추측하다가, 그마저 잘리면 처음부터 다시 시작한다. 모델이 똑똑해도 그 똑똑함은 세션 하나 안에 갇혀 있다.

앞 글에서 "대화 기록을 데이터베이스로 쓰지 말고 파일시스템을 공유 상태로 쓰라"는 큰 원칙을 다뤘다. 이 글은 그 원칙을 한 가지 구체적인 문제 — 프로젝트가 세션을 넘겨 살아남게 하는 것 — 에 좁혀 적용한 노트다. 비개발자가 AI에게 작업을 맡길 때 가장 자주, 가장 아프게 부딪히는 자리다.

세션은 끝나면 프로젝트도 같이 잊는다

에이전트 세션의 기억은 본질적으로 휘발성이다. 컨텍스트 창(한 번에 들고 있을 수 있는 작업 기억)은 유한해서 대화가 길어지면 앞부분이 압축되거나 밀려나고, 새 세션을 열면 그 안은 백지다.

이건 단발성 질문에서는 드러나지 않는다. "이 문장 고쳐줘"는 세션 하나로 끝나니 기억이 휘발해도 손해가 없다. 그러나 "이 사이트를 몇 주에 걸쳐 만들자" 같은 작업은 다르다. 그동안 내린 결정, 시도하고 버린 접근, 지금 막혀 있는 지점이 대화 안에만 살아 있다면, 대화가 끝나는 순간 함께 사라진다. 했던 토론을 또 하고, 폐기한 방법을 또 시도하는 건 모델의 결함이 아니라 기억을 둘 자리가 없어서 생기는 구조적 문제다.

벤더의 숨은 메모리는 왜 부족한가

요즘 도구들은 이 문제를 자기 나름대로 푼다. 사용자나 프로젝트 정보를 자동으로 기억해 두는 "숨은 메모리(hidden memory)" 기능이다. 유용하다. 같은 말을 반복하지 않아도 되고 선호가 알아서 반영된다. 하지만 장기 프로젝트 기억의 단일 소스로 삼기엔 세 가지가 걸린다.

• 이식 불가능(not portable) — 그 기억은 특정 회사의 시스템 안에 산다. 도구를 바꾸면 따라오지 않으니, 다른 AI에게 같은 프로젝트를 맡기려면 맥락을 처음부터 다시 쌓아야 한다.
• 감사 어려움(not auditable) — 무엇이 기억됐는지 펼쳐 보거나, 틀린 항목을 골라 고치거나, diff(변경 이력)로 추적하기 어렵다. 기억이 있긴 한데 손이 닿지 않는다.
• 인수인계 어려움 — 사람이, 다른 도구가, 스크립트가 같은 작업을 이어받아야 할 때 벤더 안에 갇힌 기억은 꺼내 건네기가 까다롭다.

핵심은 숨은 메모리를 버리라는 게 아니다. 편의 기능으로는 그대로 쓰되, 프로젝트가 의존하는 장기 기억은 내가 펼쳐 보고 고치고 버전 관리하고 들고 갈 수 있는 자리에 둬야 한다는 것이다.

Seogo — 기억을 프로젝트 파일 안에 둔다

그 자리를 파일시스템에 만드는 규칙이 **seogo(서고)**다. seogo는 "책 보관소" 또는 "서가"라는 뜻으로, 이름 그대로 프로젝트의 장기 기억을 프로젝트 파일 안에 보관하는 책꽂이다. 설치할 런타임도 가져다 쓸 라이브러리도 없다 — 디스크 위 마크다운 파일 몇 개를 정해진 규칙대로 두는 것뿐이다.

seogo/
  seogo_index.md            # 라우터 (한 줄 요약 + 포인터만)
  seogo_progress.md         # 현재 대시보드 (changelog가 아님)
  seogo_failure-patterns.md # 재사용할 실수 · 폐기한 접근
  topics/  ideas/  lessons/  research/
context/
  001-2026-06-11-01.md      # 세션 핸드오프 로그

문서 스타일에도 작은 규칙이 있다. 파일마다 YAML 프론트매터(문서 맨 위 메타데이터 블록)로 상태·날짜·태그를 적고, 안정적인 슬러그(주소처럼 쓰는 짧은 식별자)를 붙이고, 문서끼리는 [[topic-slug]] 같은 위키링크로 엮는다. 태그는 단순한 배열로 둔다. 그리고 가장 중요한 한 가지 — 인덱스는 짧게, 상세는 별도 파일로. 한곳에 다 욱여넣으면 금세 읽기 힘든 덩어리가 된다.

인덱스 · 진행판 · 실패패턴이 각자 맡는 일

이 세 파일이 seogo의 뼈대다. 흔히 셋을 하나로 합치려는 충동이 드는데, 역할을 섞으면 모두 망가진다.

인덱스(seogo_index.md)는 라우터다. 내용을 담지 않고 어디에 무엇이 있는지만 가리킨다. 각 줄은 한 줄 요약 더하기 파일 포인터, 그게 전부다. 새 세션은 이 파일 하나로 프로젝트 지도를 얻는다. 그래서 새 파일을 만들면 인덱스도 같이 갱신해야 한다 — 가리켜지지 않는 파일은 사실상 죽은 파일이다.

진행판(seogo_progress.md)은 현재 대시보드다. 변경 이력(changelog)이 아니라 지금 이 순간의 상태판이다. 무엇이 끝났고 진행 중이고 막혀 있는지. 짧게 유지하는 게 핵심이다. 지나간 구현 내역을 여기 쌓으면 대시보드가 일지로 변질돼 정작 봐야 할 "지금 상태"가 묻힌다. 상세한 경과는 세션 로그로 보낸다.

실패패턴(seogo_failure-patterns.md)은 폐기한 접근의 묘지다. 시도했다 버린 방법, 다시 밟지 말아야 할 함정을 적는다. 이게 없으면 새 세션은 같은 막다른 길을 또 걸어 들어간다 — 모델은 어제의 실패를 기억하지 못하니까.

공통 원리는 하나다. 각자 한 가지 질문에만 답한다. 어디에 있나(인덱스), 지금 어떤가(진행판), 무엇을 피해야 하나(실패패턴). 질문이 섞이지 않으니 읽기도 쓰기도 가볍다.

세션 핸드오프의 핵심: "다음 세션 시작 가이드"

기억의 책꽂이를 만들었다면 이제 세션과 세션을 잇는 다리가 필요하다. 그게 context/에 쌓는 세션 핸드오프 로그다. 한 세션을 마칠 때 001-2026-06-11-01.md 같은 파일을 남겨, 다음 세션이 거기서 곧장 이어받게 한다.

여기서 흔한 실수는 대화 전체를 보존하려는 것이다. 주고받은 말을 통째로 받아 적으면, 다음 세션은 긴 기록을 다시 읽느라 시간을 쓰고도 "그래서 지금 뭘 하면 되는데?"에는 답을 못 얻는다. 보존할 건 대화가 아니라 다음에 유용한 상태다. 세션 로그에서 가장 중요한 단 하나의 섹션은 이것이다.

## Next Session Start Guide (다음 세션 시작 가이드)

이 섹션은 다음 에이전트에게 다섯 가지를 말해 줘야 한다 — 무엇을 방금 정했는가, 어떤 파일이 중요한가, 먼저 무엇을 할 것인가, 무엇을 반복하지 말 것인가, 무엇이 막혀 있는가. 이 다섯 줄만 제대로 있으면 다음 세션은 대화를 거슬러 재생하지 않고도 정확히 이어서 일한다. 알 수 없는 항목은 비워 두지 말고 UNKNOWN이라고 적는다 — 빈자리는 다음 세션이 추측으로 메우게 만들지만, UNKNOWN은 "여기는 아직 미정"이라는 정확한 신호다.

직접 굴려본 자리

이건 종이 위 이론만은 아니다. 지금 읽고 있는 이 블로그(ja-dan.com/notes) 자체가 바로 이 seogo 방식으로 운영된다. 진행 상태, 폐기한 접근, 세션 핸드오프가 전부 저장소 안 파일로 남는다. 한 세션이 끝나면 진행판이 갱신되고 핸드오프 로그가 쌓이며, 다음 세션은 그 파일들을 먼저 읽고 움직인다. 그래서 대화가 리셋되거나 압축돼도 작업은 끊기지 않고 파일에서 이어진다.

특별한 점은 이 기억이 프로젝트와 함께 버전 관리된다는 것이다. 진행판이나 실패패턴이 바뀌면 그 변화가 일반 코드 변경과 똑같이 diff로 남는다. 기억의 진화를 추적할 수 있고, 잘못 적었으면 되돌릴 수 있고, 프로젝트를 통째로 옮겨도 기억이 따라온다. 숨은 메모리가 줄 수 없는 성질이다.

이 글에서 설명한 패턴은 한곳에 정리해 공개 저장소로 묶어 두었다. seogo를 포함한 네 가지 프로토콜이 들어 있고, 전부 설치할 것 없는 순수 파일 규칙이다.

저장소: github.com/aminpiano/agentic-workflows

참고

이 글은 notes 프로젝트의 실제 운영 방식과 공개 저장소의 project memory 패턴을 바탕으로 쓴 운영 노트다. 검증 단서는 저장소 안의 seogo/, context/, CLAUDE.md 같은 파일 구조와 위 공개 저장소의 파일 기반 프로토콜이다.

정리

세션은 끝나면 프로젝트 맥락을 함께 잊는다. 벤더의 숨은 메모리는 편의로는 좋지만 이식 불가능하고 감사하기 어렵고 인수인계가 안 돼 장기 기억의 단일 소스로는 부족하다. seogo는 그 기억을 프로젝트 파일 안에 둔다 — 인덱스가 길을 가리키고, 진행판이 현재를 보여주고, 실패패턴이 함정을 막고, 세션 핸드오프 로그가 세션 사이를 잇는다. 다리의 핵심은 "다음 세션 시작 가이드"다. 대화 전체를 보존하려 들지 말고 다음에 유용한 상태만 남긴다. 그러면 세션이 죽어도 프로젝트는 살아남는다.