에이전트가 관련 역할과 경로를 알고 있을 때, 문서 목차(Table of Contents)는 가장 빠른 검색 방법입니다. 사용자의 질문은 문서의 파일명과 다른 언어를 사용할 수 있으며, 질문과 문서가 서로 다른 인간 언어로 작성되어 있을 수도 있습니다. dotdotgod query는 자연어 질문과 의미론적으로(semantically) 유사한 문서 구절을 로컬에서 검색하여, 에이전트가 읽을 가치가 있는 유지 관리된 소스로 안내합니다.

문서는 프로젝트 메모리의 원천으로 남습니다. 임베딩(Embeddings)과 검색 결과는 질문을 해당 소스에 연결하는 파생된 검색 데이터입니다.

경로를 알 수 없을 때는 의미부터 시작하세요

다음 질문을 고려해 보세요:

Why does Load exclude old plans from its default context?

관련 설명은 LOAD_PROJECT.md, MEMORY_AREA_CONFIG.md, 또는 컨텍스트 큐레이션(context curation)에 관한 문서에 있을 수 있습니다. 파일명 검색은 질문의 "old plans"를 문서 내의 archive, local memory, 또는 stale과 같은 용어와 연결하지 못할 수도 있습니다.

query는 자유 형식의 질문을 수락하고 의미론적으로 관련된 마크다운(Markdown) 구절을 찾습니다.

dotdotgod query . \
  "Why does Load exclude old plans from its default context?" \
  --limit 5

<root> 이후의 여러 인자는 하나의 쿼리로 결합됩니다. --limit은 1부터 100 사이의 값을 허용하며 기본값은 30입니다. 이 제한은 구절(passage) 수가 아닌 고유한 마크다운 파일에 적용됩니다.

검색 코퍼스(Corpus)를 Docs-First 경계 내로 유지하세요

query는 docs/ 하위의 마크다운 문서를 검색하며, load.documentationSummary.exclude 정책을 적용하여 범위를 정의합니다.

기본 코퍼스는 다음 영역을 제외합니다:

docs/plan/
docs/archive/

활성 계획(Active plans)과 과거 기록은 README 인덱스와 필요할 때 명시적인 경로를 통해 읽힙니다. 숨겨진 경로, 비밀 정보가 포함된 것으로 보이는 경로, 그리고 설정된 건너뛰기(skip) 디렉토리 또한 임베딩(embedding)에서 제외됩니다.

이러한 범위 설정은 검색 과정에서 현재 공유된 문서와 로컬 작업 기록의 서로 다른 역할을 보존합니다.

헤딩 계층 구조에 따른 마크다운 분할 (Split Markdown along Its Heading Hierarchy)

유용한 검색 단위는 한 섹션의 의미와 이를 해석하기 위한 충분한 문맥(context)을 모두 필요로 합니다. dotdotgod는 마크다운(Markdown)을 헤딩(heading) 계층 구조에 따라 분할하며, 각 본문 파편(body fragment)을 1,600자로 제한하고 경로(path) 및 헤딩 정보를 부착합니다.

docs/spec/LOAD_PROJECT.md
└── Focused Query
    └── query searches shared documentation ...

각 구절(passage)은 저장소 상대 경로(repository-relative path), 최상위 레벨부터 현재 섹션까지의 헤딩 계층 구조, 그리고 제한된 범위의 본문 파편을 포함합니다. 경로는 결과값을 해석하기 위한 주소를 제공하며, 헤딩은 문맥을 제공하고, 본문은 질문과 비교할 의미를 제공합니다.

다국어 E5 모델 로컬 실행 (Run the Multilingual E5 Model Locally)

현재 Query는 하나의 모델인 Xenova/multilingual-e5-small을 지원합니다. 이 모델은 @huggingface/transformers를 통해 로컬에서 실행되므로, 문서 본문이 원격 임베딩(embedding) API로 전송되지 않습니다.

E5 입력 형식을 따라, Query는 각 입력 유형에 서로 다른 접두사(prefix)를 추가합니다.

query: Why does Load exclude old plans from its default context?
passage: path: docs/spec/LOAD_PROJECT.md ...

질문(query)에는 query: 접두사가 붙고, 문서 구절(passage)에는 passage:가 붙습니다. 모델은 이 둘을 모두 정규화된 384차원 float32 벡터(vector)로 변환합니다.

모델 파일이 없는 경우, 런타임(runtime)이 처음 사용할 때 사용자 레벨 캐시(cache)로 파일을 다운로드할 수 있습니다. 현재 원격 제공자(remote provider) 선택 및 대체 임베딩 모델 프로필은 지원되지 않습니다.

모든 구절 간의 의미적 거리 비교 (Compare Semantic Distance across Every Passage)

Query는 질문이 모든 문서 구절의 의미와 얼마나 밀접하게 일치하는지(코사인 유사도, cosine similarity)를 직접 비교합니다. 현재의 작은 로컬 코퍼스(corpus) 규모에서는 검색 범위를 가능성 있는 근접 후보로 빠르게 좁혀주는 별도의 인덱스(index, 근사 최근접 이웃/approximate nearest neighbor)가 필요하지 않습니다.

질문을 의미적 좌표로 변환
  → 모든 구절과 의미적 거리 비교
  → 제목 및 경로에서 일치하는 단어에 대해 작은 보너스 추가
...

질문의 단어가 결과 경로(result path)나 제목에 직접 나타나면, Query는 작은 보너스(lexical boost, 어휘적 부스트)를 추가합니다. 의미적 근접성(Semantic proximity)이 주요 신호로 유지되지만, 명시적인 파일명 및 헤딩(heading) 일치 또한 기여합니다.

정렬 후, Query는 Markdown 경로를 기준으로 결과의 중복을 제거합니다. 하나의 문서에서 여러 구절이 높은 점수를 받더라도, 가장 높은 점수를 받은 구절 하나만이 해당 파일을 대표합니다. 이를 통해 한두 개의 긴 문서가 결과 세트를 가득 채우는 것을 방지하고, 에이전트(agent)가 검토할 수 있는 더 넓은 범위의 문서 세트를 제공합니다.

변경되지 않은 구절에 대한 임베딩 (Embeddings) 재사용

파생된 벡터 데이터는 Git에서 제외된 리포지토리 전용 캐시(cache)에 저장됩니다.

.dotdotgod/vectors/
├── manifest.json
├── chunks.jsonl
...

manifest.json은 스키마(schema), 모델(model), 차원(dimensions), 제외 정책(exclusion policy) 및 갱신 정보를 기록합니다. chunks.jsonl은 구절(passage) 및 경로 메타데이터를 저장하며, embeddings.f32는 float32 벡터를 저장합니다.

구절의 핑거프린트(fingerprint)가 동일하게 유지되면, Query는 기존 벡터를 재사용합니다. 새로운 구절이나 변경된 구절만 임베딩하며, 캐시를 다시 작성할 때 삭제된 구절은 제거합니다.

캐시가 손상되었거나, 불완전하거나, 현재의 스키마, 모델 또는 차원과 호환되지 않는 경우, Query는 이를 다시 구축합니다. 각 아티팩트(artifact)는 임시 파일에 작성된 후 원자적 이름 변경(atomic rename)을 통해 교체되어, 부분적으로 기록될 위험을 줄입니다.

캐시는 유지 관리되는 문서로부터 언제든지 다시 구축할 수 있는 파생 데이터입니다.

소스 읽기를 위한 제한된 후보 세트 반환

기본적인 사람이 읽을 수 있는 출력은 간결하게 유지됩니다. --json 옵션을 사용하면 호출자가 구조화된 쿼리(query), 모델(model), 차원(dimension), 인덱스(index) 및 결과 데이터를 검사할 수 있습니다.

각 결과는 청크 ID(chunk ID), 리포지토리 상대 Markdown 경로, 헤딩 계층 구조(heading hierarchy) 및 제한된 본문 발췌본을 제공합니다. 최종 점수에는 일치하는 표현에 대한 작은 보너스가 포함되며, 원래의 의미적 유사도(semantic-similarity) 점수도 계속 사용할 수 있습니다.

높은 점수는 질문의 의미와 유사한 유지 관리되는 소스(maintained-source) 후보를 식별합니다. docs/spec/ 아래의 제품 계약서와 docs/concept/ 아래의 설명 문서는 서로 다른 역할을 수행하면서도 동일한 단어를 사용할 수 있습니다. 에이전트는 결과 경로와 헤딩(heading)을 확인하여 해당 역할을 식별한 다음, 유지 관리되는 소스를 읽습니다.

Query와 Graph Impact가 서로 다른 질문에 답하는 방식

두 기능 모두 관련 문서를 찾지만, 서로 다른 입력값에서 시작하며 서로 다른 신호(signals)를 사용합니다.

query는 자체적인 로컬 벡터 캐시(vector cache)를 사용합니다. graph impact의 기본 랭킹은 결정론적 관계와 단어 일치 라우팅 (lexical routing)을 사용하며, 임베딩 유사도 (embedding similarity)는 기본 경로의 일부가 아닙니다.

Load는 자연어 중심의 초점이 있을 때 query 결과와 문서 맵 (documentation map)을 결합합니다. 코드나 문서가 변경된 후에는 graph impact가 다음 검토 경로를 식별합니다.

의미론적 검색과 문서 맵이 하나의 읽기 경로를 형성하는 방식

의미론적 검색 (semantic retrieval)은 경로를 알 수 없을 때 후보를 찾습니다. 그 후 경로와 README 파일이 각 후보 문서의 역할을 설명합니다.

질문 (question)
  → query를 통해 후보 경로 탐색
  → README 파일과 메모리 영역을 통해 역할 식별
...

벡터 검색 (vector search)은 질문과 문서가 서로 다른 표현을 사용하더라도 에이전트가 읽어야 할 소스 주소를 찾아냅니다.

추가 읽기

추가 읽기

• The Role of Vector Search in Docs-First Project Memory
• How dotdotgod Load Turns a Documentation Table of Contents into a Reading Route
• Query command specification
• Load Project specification