지난 화요일, 저는 운영 환경에서 조용히 메모리 누수(memory leaking)를 일으키고 있던 캐싱 레이어(caching layer)를 재작성하며 AI 어시스턴트와 깊은 세션에 빠져 있었습니다. 처음에는 Redis를 시도했습니다. 작동했습니다. 하지만 실제 데이터 볼륨(최대 약 50MB)을 확인하고는 그 아이디어를 폐기했습니다. 50MB를 캐싱하기 위해 전체 서비스를 구동하는 것은 터무니없게 느껴졌기 때문입니다. 대신 sqlite를 선택했습니다. 여전히 좋은 결정이었다고 생각합니다.

이틀 후, 팀원이 브랜치를 열어 삭제된 cache_memory.py 옆에 놓인 cache_sqlite.py를 보고는, 왜 우리 스택의 나머지 부분처럼 그냥 Redis를 사용하지 않는지 물었습니다. 저는 적절한 답변을 준비하지 못했습니다. 그 근거는 이미 사라져 버린 채팅 세션 안에만 존재했기 때문입니다. 결정을 내렸던 기억은 나지만, 설득력 있게 재구성할 수는 없었습니다. "믿어줘, 우리 얘기했었어"라는 말은 팀원이나, 혹은 3개월 뒤의 나 자신에게 해주기에는 그리 좋은 답변이 아닙니다.

이것이 바로 AI 보조 코딩(AI-assisted coding)에서 대부분의 도구가 놓치고 있는 부분입니다. 코드는 살아남습니다. 디프(diff)도 살아남습니다. 코드의 '기능(what it does)'을 더 많이 저장하려는 AI 메모리 도구들이 쏟아져 나오고 있으며, 몇몇 도구(Selvedge, presence)는 '이유(why)'까지 추적하기 시작했습니다. 이는 그 고통이 실재한다는 것을 말해줍니다. 하지만 그들 중 거의 대부분은 특정 에이전트(agent)에 연결해야 하는 MCP 서버이며, 리포지토리(repo) 옆에 데이터베이스를 두고 있어야 합니다. 제가 원했던 것은 더 단순하고 휴대 가능한 것이었습니다. 즉, 어떤 에디터나 에이전트가 생성했든 상관없이, 코드 옆에 제가 읽을 수 있는 일반 텍스트로 작성된 '추론(reasoning)'과 '시도했다가 버린 접근 방식들'이 있는 것입니다. 왜냐하면 그 추론은 채팅창 안에 머물고, 채팅창은 종료되기 때문입니다. Claude Code에서 Cursor로 전환하거나, 그냥 노트북을 닫아버리면 그것은 사라집니다. 사실(facts)은 남지만, 그 뒤에 숨은 판단(judgment)은 증발해 버립니다.

이것이 어려운 문제처럼 느껴지지는 않았기에, 저 자신을 위해 이를 해결할 Alpheon이라는 작은 것을 만들었습니다. 가장 단순한 버전으로 말하자면, 서버도 데이터베이스도 없는 단 하나의 Python 파일이며, git을 기반으로 작동하므로 어떤 에디터나 에이전트를 사용하는지는 상관하지 않습니다.

사실(Facts) vs 추론(reasoning)

제가 깨달은 차이점은 다음과 같습니다. 사실 (Fact)은 "cache.py가 수정되었고, cache_sqlite.py가 추가되었으며, cache_memory.py가 삭제되었습니다"와 같은 것입니다. 어떤 도구든 diff (차이점)에서 이를 추출할 수 있습니다. 추론 (Reasoning)은 "재시작 시에도 캐시가 유지되어야 했기에 Redis를 시도했으나, 데이터 양에 비해 과하다고 판단하여 대신 sqlite를 선택했다"와 같은 것입니다. 여러분의 저장소 (repo)는 직접 기록하지 않는 한 이 두 번째 부분을 포착하지 못하며, 대부분의 사람들은 그 당시에는 추론 과정이 당연하게 느껴지기 때문에 기록하지 않습니다. 하지만 일주일만 지나도 그것은 더 이상 당연하게 느껴지지 않습니다.

Alpheon이 실제로 하는 일

Alpheon은 여러분의 git diff를 읽고 Handoff Note (인수인계 노트)의 초안을 작성하는 CLI (명령줄 인터페이스) 도구입니다. 이 노트는 무엇이 변경되었는지, 왜 변경되었는지, 무엇을 시도했다가 거절했는지, 그리고 무엇이 미결 상태로 남아 있는지를 다루는 짧은 마크다운 (markdown) 블록입니다. 여러분은 초안을 검토하고 원한다면 수정하며, 그 후에만 여러분의 저장소에 존재하고 다른 파일들과 마찬가지로 커밋 (commit)되는 HANDOFF.md 파일에 추가됩니다.

위의 캐싱 예시의 경우, 생성될 노트는 다음과 같은 모습입니다:

## Handoff Note (2026-07-14 22:41)

### What changed
...

"What changed" 섹션은 git에서 직접 가져옵니다: diff 통계, 변경된 파일, 최근 커밋 메시지 등입니다. "Why"와 "rejected" 섹션은 여러분(또는 적절한 시점에 프롬프트가 입력된 AI 세션)이 설명 내용이 아직 생생할 때 실제로 이유를 설명하는 부분입니다. 또한 다음과 같이 직접 전달할 수도 있습니다:

python alpheon.py --note "tried Redis, too heavy for 50MB of data, switched to sqlite"

6개월 후, 그 노트는 설명하는 코드 바로 옆에 버전 관리되어 HANDOFF.md에 일반 텍스트로 남아 있게 됩니다. 별도의 앱도, 로그인도 필요 없습니다.

사용해 보는 방법

이미 가지고 계실 Python과 git 외에는 설치할 것이 아무것도 없습니다.

git clone https://github.com/BravoAlphaSix/alpheon.git
cd your-project
python /path/to/alpheon.py

먼저 초안 노트를 출력합니다. 'yes'를 입력하기 전까지는 HANDOFF.md 파일에 아무런 영향도 주지 않습니다. pre-commit hook(사전 커밋 훅)이나 이와 유사한 용도로 확인 절차를 건너뛰고 싶다면 --yes 플래그가 있지만, 기본 설정은 의도적으로 '검토 후 승인' 방식입니다.

의도적으로 구현하지 않은 기능들

계정 생성, 클라우드, 벡터 데이터베이스(Vector Database), 백그라운드 동기화 기능은 없습니다. 이 도구는 의존성이 전혀 없는 단 하나의 Python 파일로 구성되어 있으며, 가능한 한 오랫동안 이 상태를 유지하고 싶습니다. 저장 전 확인 단계를 의도적으로 넣은 더 큰 이유는 단순히 번거로움을 주기 위해서가 아닙니다. AI가 생성한 '이유(why)'가 사실인 것처럼 조용히 저장되는 것은, 아예 노트가 없는 것보다 훨씬 더 나쁠 수 있기 때문입니다. 왜냐하면 이제 당신의 저장소(repo)에는 잘못된 확신이 자리 잡게 되기 때문입니다. 사람이 직접 쓰기 전에 확인하게 함으로써, 이 도구가 실제로 알고 있는 것(diff)과 추측하고 있는 것(당신의 추론) 사이의 정직함을 유지하도록 했습니다.

이 프로젝트는 정말 초기 단계입니다. 저는 handoff note(인수인계 노트)가 시장성이 있다고 생각해서가 아니라, 제 개인 프로젝트를 진행하며 계속해서 이 문제에 부딪혔기 때문에 만들었습니다. MIT 라이선스로 배포되며, 침묵보다는 "X 기능이 부족하다"라는 피드백을 듣고 싶습니다.

자, 그렇다면: 결정을 내린 채팅 세션이 종료된 후, 그 결정 뒤에 숨겨진 '이유'를 현재 어떻게 기록하고 계신가요? PR(Pull Request)의 코멘트인가요, 아무도 업데이트하지 않는 위키(wiki)인가요, 아니면 단순히 기억에 의존하시나요? 저는 사람들이 실제로 어떤 방식을 사용하고 있는지 진심으로 알고 싶습니다. 왜냐하면 불과 몇 주 전까지 저에게 작동하던 방식은 "아무것도 하지 않는 것"이었기 때문입니다.

직접 살펴보고 싶으시다면 저장소는 여기 있습니다: https://github.com/BravoAlphaSix/alpheon