벡터DB 없이 폴더로 기억하는 코딩 에이전트: personal-monorepo-template 분석
코딩 에이전트를 매일 쓰다 보면 한 가지 벽에 반복해서 부딪힙니다. 어제 나눈 결정, 지난주에 정한 컨벤션, 특정 동료의 업무 스타일을 에이전트가 매 세션마다 처음 듣는 것처럼 다시 물어봅니다. 이 문제를 값비싼 벡터 데이터베이스나 별도 메모리 인프라 없이, 그냥 평범한 폴더 구조와 마크다운 파일 하나로 풀어낸 저장소가 최근 공개되어 개발자들 사이에서 화제가 되었습니다. Instructor 라이브러리를 만든 jxnl(Jason Liu)이 공개한 personal-monorepo-template입니다. 이 글은 그 구조를 분해하고, 스킬과 지식을 일급 리소스로 다루는 ThakiCloud의 운영 관점에서 이 설계가 무엇을 시사하는지 검증합니다.
개요
에이전트의 기억 문제를 다루는 흔한 접근은 벡터 데이터베이스입니다. 대화와 문서를 임베딩해 저장하고, 필요할 때 의미 검색으로 꺼내 오는 방식입니다. 강력하지만 운영 부담이 큽니다. 임베딩 파이프라인, 벡터 인덱스, 재색인 스케줄을 모두 관리해야 하고, 개인이 자기 워크플로에 얹기에는 과한 인프라입니다.
personal-monorepo-template은 정반대 방향을 택합니다. 기억을 검색 문제가 아니라 파일 구조 문제로 재정의합니다. 사람은 people/ 폴더에, 프로젝트는 프로젝트 패킷으로, 반복되는 작업 방식은 저장소 안의 스킬로 둡니다. 그리고 에이전트가 세션을 시작할 때마다 AGENTS.md를 통해 이 구조를 상시 로드합니다. 벡터 검색의 근사 일치 대신, 폴더 경로라는 정확한 주소로 기억에 접근하는 셈입니다.
만든 사람의 배경이 이 설계에 무게를 더합니다. jxnl은 구조화 출력(structured output) 라이브러리 Instructor의 창시자로, 이 라이브러리는 월 수백만 건 다운로드되며 OpenAI가 자사 structured output 기능의 영감으로 인용했다고 알려져 있습니다. 현재 그는 OpenAI Codex 팀의 개발자 경험(Developer Experience) 엔지니어로, 코딩 에이전트를 매일 실전에서 운용하는 사람이 자기 문제를 풀려고 만든 도구라는 점에서 참고 가치가 큽니다.
이 기술은 무엇인가
핵심 아이디어는 하나입니다. 에이전트의 기억을 모노레포 안의 평범한 폴더와 마크다운으로 표현하고, 세션마다 자동으로 로드합니다. 세 가지 축으로 나눠 볼 수 있습니다.
첫째는 사람과 프로젝트의 기록입니다. 저장소는 슬랙, 이메일, 캘린더, 깃허브를 스캔해 people 파일과 프로젝트 패킷을 만들고, 상시 로드되는 AGENTS.md의 업데이트를 제안합니다. 특정 동료의 이름을 언급하면 에이전트가 그 사람의 파일을 읽어 맥락을 즉시 복원합니다. 벡터DB 없이도 “이 사람이 누구인지”를 정확한 폴더 경로로 찾아냅니다.
둘째는 저장소 로컬 스킬입니다. 반복되는 작업 방식을 저장소 안에 스킬로 넣어 두면, 세션마다 자동으로 로드되어 에이전트가 그 절차를 따릅니다. 대표적으로 보낸 이메일과 슬랙 메시지를 학습해 사용자의 문체로 글을 쓰는 write-like-me 스킬이 내장되어 있습니다. 사용자의 과거 산출물이 곧 스킬의 학습 데이터가 되는 구조입니다.
셋째는 자동 체크인입니다. 저장소는 매일 오전 9시와 오후 4시에 자동 체크인을 실행하도록 설계되어, 그날의 프로젝트 상태와 사람 관련 맥락을 정리하고 업데이트를 제안합니다. 에이전트가 수동 호출을 기다리는 것이 아니라 정해진 시각에 스스로 기억을 갱신하는 루프입니다.
전체 흐름을 도식으로 보면 다음과 같습니다.
flowchart TB
SRC[슬랙·이메일·캘린더·깃허브] -->|스캔| SCAN[체크인 스크립트]
SCAN --> PEOPLE[people 파일 제안]
SCAN --> PKT[프로젝트 패킷 제안]
SCAN --> AGD[AGENTS.md 업데이트 제안]
AGD -.세션 시작 시 상시 로드.-> AGENT[코딩 에이전트]
PEOPLE -.폴더 경로로 조회.-> AGENT
SKILL[저장소 로컬 스킬<br/>write-like-me 포함] -.자동 로드.-> AGENT
CRON[매일 09시·16시 자동 체크인] --> SCAN
이 설계가 흥미로운 이유는, 정확히 이 저장소의 저자가 별도 글에서 정리한 “Codex-maxxing” 철학과 맞닿아 있기 때문입니다. 에이전트에게 더 좋은 모델을 붙이는 것이 아니라, 에이전트가 매번 백지에서 시작하지 않도록 주변 구조를 두텁게 쌓는 방향입니다.
설치 및 통합
이 저장소는 이름 그대로 템플릿입니다. 자신의 깃허브 계정으로 템플릿을 복제한 뒤, 코딩 에이전트(Codex 또는 유사 CLI)가 저장소 루트를 작업 디렉터리로 삼도록 설정하는 방식으로 통합합니다. 핵심 진입점은 저장소 루트의 AGENTS.md로, 에이전트가 세션을 시작할 때 이 파일을 읽어 폴더 구조와 사람·프로젝트 맥락, 그리고 로드해야 할 스킬 목록을 파악합니다.
여기서 중요한 통합 포인트는 AGENTS.md가 단순 문서가 아니라 상시 로드되는 계약이라는 점입니다. 세션마다 이 파일이 컨텍스트 앞머리에 들어가므로, 여기에 무엇을 적느냐가 곧 에이전트의 기본 행동을 정의합니다. 폴더 구조가 정해져 있으므로 에이전트는 “동료 A의 컨텍스트가 필요하면 people/A.md를 읽는다”처럼 결정론적으로 기억에 접근합니다. 벡터 검색의 확률적 근사와 달리, 파일 경로는 항상 같은 곳을 가리킵니다.
자동 체크인은 스케줄러(cron 계열)에 체크인 스크립트를 걸어 매일 정해진 시각에 실행하는 형태로 통합됩니다. 이 부분은 에이전트를 사람이 매번 호출하지 않아도 기억이 최신 상태로 유지되게 하는 장치이며, 동시에 비용 관점에서도 중요한 설계 결정입니다. 상시 폴링이 아니라 하루 두 번의 유한 실행이므로, 무한 루프로 토큰을 태우지 않습니다.
이 설계가 실제로 어떻게 동작하는가
이 저장소는 벤치마크 수치를 내세우는 도구가 아니라 워크플로 패턴이므로, 여기서는 설계가 실제로 어떤 효과를 내는지 구조적으로 짚습니다. 재현 가능한 성능 수치는 저장소가 제시하지 않으며, 저자 본인도 정량 지표가 아니라 일상 워크플로의 개선을 근거로 제시합니다. 따라서 이 글에서도 수치를 지어내지 않고 구조적 이점만 다룹니다.
가장 큰 효과는 컨텍스트 복원 비용의 제거입니다. 벡터DB 접근은 매 질의마다 임베딩 계산과 유사도 검색을 거치지만, 폴더 경로 접근은 파일 읽기 한 번입니다. 사람이 “지난번 그 프로젝트”라고 말하면 에이전트가 해당 프로젝트 패킷을 직접 읽고, 근사 검색의 오탐 없이 정확한 맥락을 복원합니다. 기억의 정밀도가 검색 품질이 아니라 폴더 설계 품질에 달리게 됩니다.
두 번째 효과는 감사 가능성입니다. 모든 기억이 사람이 읽을 수 있는 마크다운으로 저장되므로, 에이전트가 무엇을 알고 있는지 개발자가 직접 열어 확인하고 수정할 수 있습니다. 벡터 임베딩은 사람이 눈으로 검증하기 어렵지만, people/A.md는 그냥 텍스트 파일입니다. 에이전트의 기억이 틀렸을 때 그 자리에서 고칠 수 있다는 것은 실무에서 큰 차이를 만듭니다.
세 번째 효과는 이식성입니다. 특정 벡터DB 벤더나 임베딩 모델에 종속되지 않으므로, 저장소 자체가 곧 완결된 기억입니다. 다른 머신, 다른 에이전트로 옮겨도 폴더와 마크다운은 그대로 동작합니다. 인프라 종속이 없다는 점은 뒤에서 다룰 온프렘·소버린 관점과 직접 연결됩니다.
ThakiCloud 제품 적용 시사점
이 설계는 ThakiCloud가 에이전트를 운용하는 두 축 모두와 맞닿습니다.
Paxis 관점에서 가장 직접적입니다. Paxis는 ThakiCloud의 Agent-Native Cloud 제어 평면으로, 스킬(Skills)·도구(Tools)·정책(Policies)·감사 로그(Audit Logs)를 일급 리소스로 다룹니다. personal-monorepo-template이 보여 주는 “저장소 로컬 스킬 + 상시 로드 계약(AGENTS.md)” 패턴은 Paxis의 스킬 하네스 설계 방향과 정확히 겹칩니다. Paxis는 이미 다수의 스킬을 BM25로 선택해 격리 샌드박스에서 실행하는데, 이 저장소의 접근은 그보다 앞단인 “어떤 지식을 세션 컨텍스트에 상시 둘 것인가”라는 문제를 폴더 구조로 명료하게 답합니다. 특히 기억을 사람이 읽을 수 있는 파일로 두고 모든 갱신을 감사할 수 있게 만든다는 점은, 모든 에이전트 행동을 정책 게이트와 감사 로그로 통과시키는 Paxis의 원칙과 같은 철학입니다. 에이전트의 능력을 모델 등급이 아니라 주변 구조에서 끌어낸다는 발상 자체가 스킬을 일급 리소스로 다루는 우리 설계와 동형입니다.
ai-platform 관점에서는 인프라 부담의 관점이 흥미롭습니다. ThakiCloud의 ai-platform은 K8s 기반 AI/ML 인프라로 온프렘·소버린 AI 고객사의 워크로드를 서빙합니다. 이런 고객에게 벡터DB를 상시 운영해야 하는 기억 아키텍처는 추가적인 인프라 표면과 관리 비용을 의미합니다. 반면 폴더와 마크다운으로 표현되는 기억은 별도 상태 저장소 없이 파일시스템만으로 동작하므로, 규제 환경이나 폐쇄망에서 운영 부담이 훨씬 적습니다. “기억 인프라를 최소화하면서도 에이전트에 지속성을 준다”는 각도는 소버린 AI를 요구하는 고객에게 실질적인 셀링 포인트가 될 수 있습니다.
한계 및 반론
이 설계가 만능은 아닙니다. 가장 분명한 한계는 규모입니다. 폴더 경로 접근은 기억의 주소를 사람이나 에이전트가 이미 알고 있을 때 강력합니다. 그러나 수만 개의 문서에서 “어디에 있는지 모르는” 정보를 찾아야 하는 상황에서는, 의미 기반 벡터 검색이 여전히 우월합니다. 이 저장소는 개인의 사람·프로젝트·경험이라는, 상대적으로 작고 구조가 뚜렷한 기억 공간을 전제로 합니다. 팀 전체의 방대한 지식베이스로 확장하면 폴더 구조만으로는 한계가 옵니다.
두 번째 반론은 스캔의 프라이버시입니다. 슬랙·이메일·캘린더를 스캔해 사람 파일을 만든다는 것은, 민감한 대화가 평문 마크다운으로 저장된다는 뜻이기도 합니다. 개인용으로는 편리하지만 조직에 도입하려면 접근 통제와 보존 정책이 반드시 필요합니다. 감사 가능성이 장점인 만큼, 그 파일에 누가 접근하는지에 대한 통제가 없으면 그대로 위험이 됩니다.
세 번째는 자동 갱신의 신뢰성입니다. 하루 두 번의 자동 체크인이 잘못된 요약을 사람 파일에 써 넣으면, 그 오류가 이후 세션에 계속 주입됩니다. 이 저장소가 갱신을 “제안”으로 두고 사람의 확인을 전제하는 이유가 여기에 있습니다. 완전 자동화로 밀어붙이면 기억이 조용히 오염될 수 있으므로, 사람이 검토하는 게이트를 남겨 두는 것이 안전합니다.
마지막으로, 이 접근은 “인간 비서 연봉 대비 무료 대안”으로 소개되지만, 실제로 이 수준의 워크플로를 유지하려면 저장소 구조를 스스로 설계하고 다듬을 수 있는 상당한 엔지니어링 역량이 필요합니다. 도구가 무료라는 것과 그것을 잘 운용하는 비용이 무료라는 것은 다른 이야기입니다.
그럼에도 이 저장소가 던지는 핵심 메시지는 분명합니다. 에이전트의 기억은 반드시 무거운 인프라여야 하는 것이 아니며, 좋은 폴더 구조와 상시 로드되는 계약만으로도 상당한 지속성을 얻을 수 있다는 것입니다. 이는 스킬과 지식을 일급 리소스로 다루는 ThakiCloud의 방향과 정확히 같은 곳을 가리킵니다.
관련 슬라이드
본문 내용을 NotebookLM(prismatic_tech 스타일)으로 요약한 슬라이드입니다.
