AI 에이전트가 직접 관리하는 위키, 'wuphf' 프로젝트 살펴보기

에이전트에게도 "두 번째 뇌"가 필요하다

요즘 Cursor, Claude Code, Codex 같은 AI 코딩 에이전트를 쓰다 보면 한 가지 답답한 점을 느끼게 돼요. 분명 어제 같은 코드베이스를 같이 들여다봤는데, 오늘 새 세션을 열면 마치 처음 보는 사람처럼 굴거든요. "우리 회사 결제 모듈은 PortOne을 쓰고, webhook 서명 검증은 X.js에 있어" 같은 컨텍스트를 매번 다시 알려줘야 하죠. 컨텍스트 윈도우가 아무리 길어도, 결국 세션이 끝나면 다 사라져버려요.

그래서 사람들은 CLAUDE.md나 .cursorrules 같은 파일에 컨벤션을 적어두기 시작했는데, 이건 사람이 직접 관리해야 하니 금방 낡아버리는 게 문제였어요. 이번에 소개할 wuphf는 이 문제에 대한 한 가지 답을 제시해요. "에이전트가 스스로 유지보수하는 마크다운 위키를 코드베이스 옆에 두자" 는 거죠. Andrej Karpathy가 LLM의 "long-term memory"를 이야기하면서 제안한 아이디어를 실제 도구로 구현한 거예요.

뭐가 핵심인가: 마크다운 + Git이라는 단순한 선택

wuphf의 구조는 의외로 단순해요. 별도의 벡터 DB도 없고, 거창한 백엔드도 없어요. 그냥 마크다운 파일들의 묶음을 Git으로 버전 관리하는 거예요. 에이전트가 코드베이스를 탐색하다가 "아, 이건 기억해둘 만하다" 싶은 사실, 예를 들어 "인증 토큰은 Redis에 24시간 캐싱한다"든가 "이 함수는 절대 비동기로 호출하면 안 된다" 같은 걸 발견하면, 위키의 적절한 페이지에 추가하거나 새 페이지를 만들어요.

이게 왜 영리한 설계냐면, 첫째로 사람이 그대로 읽고 검토할 수 있어요. 마크다운이니까 PR로 변경 사항을 리뷰할 수 있고, Git 히스토리에 "에이전트가 언제 뭘 학습했는지"가 그대로 남아요. 둘째로 다른 에이전트도 똑같이 읽을 수 있어요. Claude가 적은 위키를 Cursor가 읽고, Codex가 또 업데이트할 수 있는 거죠. 벤더 락인이 없어요. 셋째로 검색이 쉬워요. ripgrep 한 방이면 끝나니, 굳이 임베딩 인덱스를 돌리고 RAG 파이프라인을 굴릴 필요가 없어요.

동작 방식을 좀 더 풀어보면, 에이전트는 작업을 시작할 때 위키의 인덱스를 먼저 읽어서 관련 페이지를 끌어와요. 그리고 작업이 끝나면 새로 알게 된 사실이나 수정해야 할 사실을 스스로 위키에 반영하죠. 이때 "무엇을 적을지"는 프롬프트로 가이드하고, 사람이 정기적으로 PR을 보면서 잘못된 학습은 걷어내는 식이에요.

비슷한 시도들과의 비교

사실 "에이전트의 장기 기억"을 풀려는 시도는 여기저기서 일어나고 있어요. Mem0, LangMem 같은 라이브러리는 대화 기록을 벡터 DB에 저장하고 의미 기반으로 검색해주는 방식이에요. Letta(이전 MemGPT) 는 OS의 가상 메모리처럼 컨텍스트를 페이징하는 구조를 갖고 있죠. 이런 도구들은 일반 채팅 에이전트나 고객 응대 봇처럼 "사용자별 기억"이 필요한 영역에 강해요.

반면 wuphf의 컨셉은 코딩 에이전트라는 좁은 영역에 특화돼 있어요. 핵심은 "코드베이스에 대한 지식"이라는 점인데, 이건 본질적으로 공유 가능하고, 검토 가능하고, 코드와 함께 진화해야 하는 정보예요. 그래서 사용자별 메모리가 아니라 레포 단위의 위키가 더 자연스러운 형태인 거죠. Anthropic이 최근 강조하는 "파일 시스템을 메모리로 쓰자"는 흐름과도 맞닿아 있어요.

한국 개발자가 시도해본다면

팀에 AI 코딩 도구를 본격적으로 도입한 곳이라면 한 번 실험해볼 가치가 있다고 봐요. 특히 레거시 코드베이스가 있고, 신규 입사자가 적응하는 데 시간이 오래 걸리는 팀에 잘 맞을 것 같아요. 에이전트가 쌓아둔 위키는 결국 사람 신입에게도 좋은 온보딩 자료가 되거든요.

다만 주의할 점도 있어요. 에이전트가 자동으로 적는다는 건 곧 잘못된 사실도 자동으로 적힐 수 있다는 뜻이에요. 그래서 위키 PR을 사람이 정기적으로 검토하는 프로세스를 함께 갖춰야 해요. 또 보안에 민감한 정보, 예를 들어 내부 API 키 위치나 어드민 엔드포인트 같은 건 위키에 남기지 않도록 가드레일을 둬야겠죠. Git에 들어간다는 건 인덱싱되고 백업된다는 의미니까요.

마무리

wuphf는 "에이전트의 기억은 결국 사람도 같이 읽을 수 있는 형태여야 한다"는 철학을 보여주는 작은 도구예요. 거창한 인프라 없이 마크다운과 Git만으로도 꽤 멀리 갈 수 있다는 걸 증명하고 있죠. 여러분은 AI 에이전트의 장기 기억, 어떤 방식이 더 합리적이라고 보세요? 위키형 vs 벡터 DB형, 한 번 의견 나눠봐요.