AI 에이전트를 위한 프로젝트 메모리(Project Memory)를 설계할 때, 검색(Retrieval) 기술을 먼저 선택하고 싶은 유혹에 빠지기 쉽습니다. 문서를 임베딩(Embedding)하거나, 대화 내용을 저장하거나, 그래프(Graph)를 구축하기 전에, 프로젝트는 지속 가능한 지식이 어디에 머물 것인지 결정해야 합니다. dotdotgod 방식은 사람들이 검토하고 버전을 관리할 수 있는 문서에 해당 지식을 보관하며, 검색(Search)과 그래프(Graph)를 에이전트가 필요한 문서로 안내하는 파생 레이어(Derived Layers)로 사용합니다. 이것이 문서 우선(Docs-first) 프로젝트 메모리의 기본 구조입니다.

이전 글에서는 디렉토리, 파일 이름, 그리고 README 파일이 어떻게 AI 에이전트를 위한 문서 목차를 형성하는지, 그리고 dotdotgod가 어떻게 그 목차를 최신 상태로 유지하는지 설명했습니다. 이 글에서는 프로젝트 메모리의 권위 있는 소스(Authoritative Source)를, 그로부터 재구축할 수 있는 검색 데이터(Retrieval Data)와 분리함으로써 다음 단계로 나아갑니다.

소스(Sources)와 파생 데이터(Derived Data)의 분리

프로젝트 메모리는 서로 다른 수명을 가진 여러 레이어를 포함합니다.

관리되는 문서(Maintained documents)는 사람들이 읽고, 변경하고, 검토할 수 있습니다. 이러한 문서들이 Git에 커밋되면, 프로젝트는 내용이 언제 변경되었는지 추적할 수 있으며, 동일한 변경 사항 내에서 사양(Specs)과 테스트(Tests) 사이의 관계를 검토할 수 있습니다.

.dotdotgod/ 아래의 벡터 캐시(Vector cache)는 선택된 마크다운(Markdown) 구절로부터 계산됩니다. 그래프 캐시(Graph cache)는 패키지, 소스, 테스트 및 구성 메타데이터뿐만 아니라 문서 간의 관계를 인덱싱(Indexing)합니다. 두 방식 모두 검색 속도와 품질을 향상시키지만, 제품 동작과 설계 결정에 대한 권위는 관리되는 문서와 코드에 그대로 유지됩니다.

관리되는 문서 (Maintained documents)
  ├── 관계 추출 (relationship extraction) → 그래프 인덱스 (graph index)
  ├── 구절 임베딩 (passage embedding)       → 벡터 캐시 (vector cache)
...

이 화살표들의 방향은 중요합니다. 유지 관리되는 문서(Maintained documents)는 의미를 보존하며, 그래프(graph), 벡터 캐시(vector cache), 세션 컨텍스트(session context)는 현재 작업을 위해 그 의미를 검색하고 전달합니다.

파생 데이터는 재구축 가능해야 한다 (Derived Data Should Be Rebuildable)

소스(sources)와 파생 레이어(derived layers)를 분리하면 명확한 장애 경계(failure boundary)가 생성됩니다. 벡터 캐시(vector cache)를 삭제하더라도 마크다운(Markdown) 소스는 온전하게 유지되며, 오래되거나 손상된 그래프 인덱스(graph index)는 저장소 파일(repository files)로부터 재구축할 수 있습니다. 의미론적 검색(semantic retrieval)을 사용할 수 없는 상황에서도, 에이전트(agent)는 디렉토리 문서 맵(directory documentation map)과 README 인덱스를 통해 여전히 탐색할 수 있습니다. 공유 규칙(shared rules)과 사양(specs) 또한 개별 에이전트 세션이 종료된 후에도 저장소에 그대로 남습니다.

이러한 복구 가능성(recoverability)은 모델, 임베딩 형식(embedding formats), 에이전트 도구(agent tools)가 변경되더라도 필수적인 프로젝트 지식을 보존해 줍니다. 로컬 벡터 및 그래프 캐시(Local vector and graph caches)는 소스와 분리되어 유지되므로, 소스 파일, 유지 관리되는 문서, 프로젝트 설정으로부터 다시 계산될 수 있습니다.

검색 결과는 정답이 아니라 주소이다 (A Search Result Is an Address, Not the Answer)

질문과 파일 이름이 서로 다른 용어를 사용할 때 자연어 검색(Natural-language retrieval)은 유용합니다. 예를 들어, 사용자가 "왜 오래된 계획들이 기본 컨텍스트에서 제외되나요?"라고 질문할 때, 관련 문서의 이름은 LOAD_PROJECT.md 및 MEMORY_AREA_CONFIG.md일 수 있습니다. 다국어 임베딩 검색(Multilingual embedding search)은 표현 방식이 다르더라도 관련된 의미를 가진 구절(passages)을 찾아낼 수 있습니다.

의미론적 근접성(Semantic proximity)만으로는 특정 구절이 현재의 사양(spec)인지, 과거의 계획인지, 혹은 검증되지 않은 아이디어인지 알 수 없습니다. 디렉토리 경로(Directory paths)는 문서의 역할을 드러내며, 각 README는 해당 영역에 대한 로컬 인덱스(local index)를 제공합니다. 메모리 영역(Memory areas)은 범위(scope)와 fresh(최신) 또는 stale(오래된) 분류를 설명하며, 명시적인 추적 가능성(traceability)은 사양을 구현(implementation) 및 테스트(tests)와 연결합니다.

따라서 검색 결과는 **읽어볼 가치가 있는 소스 문서에 대한 후보 주소(a candidate address for a source document worth reading)**입니다. 에이전트는 결과의 경로와 역할을 확인하고, 관련 소스를 읽은 다음 결정을 내립니다.

그래프는 소스 문서로 돌아가는 검토 경로를 생성한다 (The Graph Creates Review Routes Back to Source Documents)

관계 그래프(Relationship graph)는 변경된 파일과 함께 검토할 가치가 있는 사양(Specs), 테스트, 명령어를 찾아냅니다. 마크다운(Markdown) 링크, README 경로, 패키지 관계, 그리고 구조화된 추적성(Traceability)이 이러한 연결을 제공합니다.

그래프 점수(Graph score)가 검토 우선순위를 설정합니다. 결과는 기록된 관계의 범위와 품질에 따라 달라지므로, 최종 결정은 가장 높은 순위의 사양(Specs), 코드, 테스트를 읽고 검증함으로써 이루어집니다.

벡터 검색(Vector retrieval)과 관계 그래프(Relationship graph)는 서로 다른 입력값에서 시작됩니다.

Load는 소스를 복사하지 않고 읽기 범위(Reading Scope)를 생성한다

문서 우선(Docs-first) 구조는 에이전트(Agents)가 선택적으로 읽을 때 가장 유용해집니다. dotdotgod의 Load 워크플로우는 다음 5단계를 통해 현재 작업에 대한 읽기 범위를 좁힙니다.

1. AGENTS.md, 저장소 README, docs/README.md와 같은 진입점(Entry points)을 확인합니다.
2. 광범위한 문서 본문을 읽기 전에 깊이 제한이 있는 문서 지도(Documentation map)를 구축합니다.
3. 사용자가 질문을 제공하면 시맨틱 검색(Semantic retrieval)을 사용하여 문서 경로를 좁힙니다.
4. 현재 작업과 관련된 계획(Plans) 또는 이력(History)만을 선택합니다.
5. 필요한 소스 문서의 관련 섹션을 읽습니다.

Load 출력은 현재 세션과 질문에 맞춰 형성된 일시적인 검색 컨텍스트(Retrieval context)입니다. 이후의 작업은 동일한 소스 문서로부터 다른 읽기 경로를 생성할 수 있습니다.

신뢰는 프로젝트 메모리가 존재하는 곳에서 시작된다

검색 정확도만으로는 AI 프로젝트 메모리의 품질을 확립할 수 없습니다. 사람은 결과 뒤에 있는 소스를 검토할 수 있어야 합니다. 경로는 현재의 사양(Specs)과 과거의 기록을 구분해야 합니다. 프로젝트 지식은 검색 인덱스(Search index)가 삭제되어도 살아남아야 하며, 서로 다른 에이전트(Agents)가 동일한 소스와 규칙에 도달할 수 있어야 합니다.

문서 우선(Docs-first) 프로젝트 메모리는 검토 가능한 소스(Source)를 기반으로 구축된 탐색 도구로서 벡터 검색(Vector retrieval), 그래프(Graphs), 그리고 로드(Load)를 사용합니다.

유지 관리되는 문서들은 프로젝트 메모리를 보존합니다. 검색(Retrieval) 결과는 현재 읽을 가치가 있는 해당 메모리의 특정 부분을 가리킵니다.

추가 읽기

• AI Agent Memory Starts with a Documentation Table of Contents
• How dotdotgod Keeps a Documentation Table of Contents Current
• Context curation concept
• Documentation structure architecture