Codex와 Claude Code에 전체 코드베이스를 다시 재생하는 것을 중단한 이유

저는 긴 Codex 및 Claude Code 세션에서 동일한 문제에 계속 부딪혔습니다. 에이전트(agent)는 유능했지만, 프로젝트 메모리(project memory) 비용이 너무 비쌌습니다.

새로운 작업이 시작될 때마다 또 다른 저장소 스캔(repository scan)이 트리거되었습니다. 이전 세션에서의 결정 사항들을 다시 설명해야 했습니다. 도구(tool)의 결과물은 트랜스크립트(transcripts) 속에 파묻혔습니다. 요약본은 크기가 더 작았지만, 어떤 출처가 특정 문장을 뒷받침하는지, 혹은 새로운 결정이 이전 결정을 대체했는지 항상 알 수는 없었습니다.

그래서 저는 코딩 에이전트를 위한 Apache-2.0 라이선스의 로컬 프로젝트 메모리 컴파일러(project-memory compiler)인 Qarinah를 구축했습니다.

문제는 컨텍스트 크기(context size)만이 아닙니다

대규모 컨텍스트 윈도우(context window)는 더 많은 텍스트를 담을 수 있지만, 다음 네 가지 중요한 질문에는 답하지 못합니다:

현재 작업에 중요한 사실은 무엇인가?
각 사실은 어디에서 왔는가?
새로운 결정이 이전 결정을 대체했는가?
다른 코딩 에이전트가 동일한 답변을 검증할 수 있는가?

전체 이력을 다시 재생(replaying)하는 것은 정보를 보존하지만, 동시에 방대한 양의 무관한 자료를 함께 보냅니다. 단일 생성 요약본은 크기가 더 작지만, 증거를 누락하거나 흐리게 만들 수 있는 또 다른 권위(authority)가 되어버립니다. 일반적인 임베딩 검색(embedding retrieval)은 유사한 텍스트를 찾아내지만, 유사성이 권위(authority), 최신성(recency), 또는 승인(approval)과 동일한 것은 아닙니다.

Qarinah가 다르게 하는 점

Qarinah는 소스 기록(source record)과 컨텍스트 팩(context pack)을 분리하여 유지합니다.

허용된 결정, 도구 결과, 승인, 프로젝트 구조 및 증거는 타입화된 이벤트(typed events)가 됩니다. 관계(Relations)는 대체(supersedes), 지원(supports), 차단(blocks), 생성됨(produced-by)과 같은 방식으로 기록들을 연결합니다. 결정론적(Deterministic) Markdown 및 JSON 뷰는 저장소 내에서 검사 가능한 상태로 유지됩니다. 작업이 시작되면 Qarinah는 제한된 범위의 팩(bounded pack)을 검색하고, 이벤트 ID, 해시(hashes) 및 출처로 연결되는 인용(citations)을 포함합니다.

그 결과는 하나의 거대한 메모리 프롬프트가 아닙니다. 현재 작업을 위해 구축된, 증거와 연결된 작은 팩입니다.

접근 방식	유용한 용도	여전히 어려운 점
전체 이력 재생 (Full-history replay)	최대의 원시 회상 (Maximum raw recall)	반복되는 토큰, 노이즈, 오래된 결정
...

기본 흐름 재현하기

하나의 프로젝트 내에 설치하세요:

npm install --save-dev qarinah
npx qarinah init . --capture content
npx qarinah scan
...

결정 사항 기록하기 (Record a decision):

npx qarinah record --kind decision \
  --title "Use additive database migrations" \
  --body "Add, backfill, switch, then remove. Never rename a production column in place."

그러면 Codex, Claude Code, CLI 워크플로 또는 MCP 클라이언트가 작업과 관련된 가장 작은 인용 팩 (cited pack)을 요청할 수 있습니다. 파일의 소유권은 프로젝트에 있습니다. Qarinah는 저장소(repository)를 호스팅되는 Qarinah 백엔드에 업로드할 필요가 없습니다.

공개된 평가 도구(evaluator)가 측정한 것

커밋된 평가 도구는 React 편집, 데이터베이스 마이그레이션 (database migration), TypeScript 리팩터링 (refactoring), 웹 조사, 프로덕션 디버깅 (production debugging), 그리고 거버넌스 릴리스 (governed release) 작업을 포함하는 6가지 소프트웨어 태스크에 대해 전체 이력 입력값과 제한된 Qarinah 팩을 비교했습니다.

비교 대상 입력값은 추정치 기준 442,113개의 입력 컨텍스트 토큰 (input-context tokens)에서 5,682개로 변경되었습니다. 이는 반복되는 컨텍스트가 98.71% 감소했음을 의미하며, 압축률은 77.81:1에 달합니다. 그러면서도 모든 필수 타겟이 상위 5위 안에 들었습니다. 저장소에는 입력값, 산술 계산, 방법론 및 기계 판독 가능한 결과가 포함되어 있습니다.

이것은 해당 태스크 세트에 대한 결과이며, 모든 저장소나 전체 제공업체 비용 (provider bill)이 정확히 98.71% 감소한다는 약속은 아닙니다. 출력 토큰 (output tokens), 캐싱 (caching), 도구 호출 (tool calls) 및 제공업체 가격 책정은 별개의 문제입니다.