그래프 검색과 벡터 검색으로 AI 에이전트의 장기 메모리 만들기

## 메모리를 데이터 가져오기부터 검색까지 단계로 나누기 영속 지식에 대해 하나의 명시적 수명 주기를 정의한다. 원시 파일, URL 또는 텍스트를 데이터셋으로 수집하고, 자료를 엔터티, 관계, 청크, 요약으로 변환하고, 선택한 전략으로 관련 지식을 조회하고, 저장된 그래프를 추가 맥락이나 규칙으로 보강한다. 각 단계는 독립적으로 호출할 수 있어야 하되 조합할 때도 일관성을 유지해야 한다. 수집 단계는 변환 전에 영속적인 데이터셋 레코드와 데이터 레코드를 생성해야 한다. 변환 단계는 콘텐츠를 분류하고 청크로 나누며, 구조화된 관계를 추출하고, 유용한 경우 요약하며, 서로 호환되는 그래프 및 벡터 표현을 기록한다. 조회 단계는 결과를 반환하기 전에 인가를 적용해야 한다. 보강 단계는 출처 이력과 버전 메타데이터를 보존해야 한다. ## 핵심 코드가 공급자를 직접 부르지 않도록 계층으로 나누기 버전이 지정된 API 또는 SDK 진입점, 수명 주기 함수, 파이프라인 오케스트레이션, 작업 실행, 도메인 모듈, 인프라 어댑터, 외부 서비스를 분리한다. 도메인 동작이 공급자별 클라이언트를 직접 가져오지 않도록 의존성은 이 계층들을 따라 아래쪽을 향해야 한다. 그래프의 원자적 개념을 명시적으로 유지한다. 노드 또는 데이터 포인트에는 안정적인 식별자, 유형, 설명, 버전, 메타데이터가 포함되고, 에지에는 출발점, 도착점, 관계 유형이 포함되며, 트리플은 주어-술어-목적어 사실을 나타낸다. 지식 그래프 컨테이너를 사용해 추출, 저장, 조회 사이에서 서로 일관된 노드 및 에지 모음을 이동한다. ## 작은 작업으로 파이프라인을 만들고 검색 전략을 분명히 고르기 처리 단계를 조합 가능한 작업으로 표현하고, 데이터 의존성이 허용하면 순차 또는 병렬로 실행할 수 있게 한다. 파이프라인은 분류, 청크 추출, 구조화된 그래프 추출, 요약, 저장을 별도 단위로 명확히 드러내어 오류와 재시도가 해당 범위 안에 머물게 해야 한다. 명시적인 전략 유형을 통해 검색을 라우팅한다. 컴플리션을 포함한 그래프 순회, 요약 기반 그래프 맥락, 트리플 조회, 벡터 및 어휘 기반 청크 검색, 문서 요약, 시간 기반 조회, 자연어를 구조화 쿼리로 변환, 직접 그래프 쿼리, 타당한 경우의 자동 전략 선택을 지원한다. 모든 전략은 동일한 인가 필터링과 안정적인 결과 계약을 사용해야 한다. ## 스토리지와 모델 공급자를 인터페이스 뒤에 두어 바꿀 수 있게 하기 그래프, 벡터, 관계형 스토리지에 각각 별도 인터페이스를 정의한다. 팩토리를 통해 구체적인 엔진을 선택하여 로컬 기본값, 원격 서비스, 운영 데이터베이스를 도메인 작업의 변경 없이 교체할 수 있게 한다. 공급자별 연결 로직, 기능 확인, 지원되지 않는 작업에 대한 오류는 어댑터 내부에 둔다. 언어 모델, 임베딩 엔진, 구조화 출력 프레임워크, 파일 로더, 객체 스토리지에도 같은 경계를 적용한다. 구성은 구현체를 선택하고 도메인 코드는 인터페이스를 사용한다. 백엔드에 직접 그래프 쿼리나 특정 조회 모드 같은 기능이 없으면, 다른 의미로 조용히 저하시키지 말고 해당 작업을 명시적으로 거부한다. ## 사용자별로 데이터를 나눌 때는 반드시 인증을 함께 켜기 접근을 사용자에서 데이터셋을 거쳐 데이터로 이어지는 관계로 모델링하고, 그래프 또는 벡터 조회 전에 읽기, 쓰기, 삭제, 공유 권한을 적용한다. 지원되는 경우 사용자와 데이터셋별로 스토리지를 격리하여 필터링 오류가 다른 테넌트의 지식을 노출하지 못하게 한다. 백엔드 접근 제어와 API 인증을 하나의 보안 태세로 취급한다. 테넌트 격리를 활성화하려면 반드시 인증을 요구해야 하며, 인증을 명시적으로 끄는 설정이 활성화된 접근 제어를 무시해서는 안 된다. 단일 사용자용 공유 스토리지는 의도적으로 선택하는 별도의 모드다. 접근할 수 없는 레코드가 존재한다는 사실을 밝히지 말고 빈 결과를 반환하되, 인가된 운영자를 위한 내부 진단 정보는 충분히 보존한다. ## 언어 모델과 임베딩을 짝으로 설정하고 운영 환경 설정을 함께 점검하기 언어 모델 공급자와 임베딩 공급자를 한 쌍으로 구성한다. 둘 중 하나만 설정하면 다른 쪽에 대한 암묵적 기본값 때문에 자격 증명이 누락되거나, 토큰화가 호환되지 않거나, 예상치 못한 외부 호출이 발생할 수 있다. 시작할 때 두 공급자, 엔드포인트, 모델, 구조화 출력 모드, 속도 제한을 모두 검증한다. 비밀 정보는 환경 기반 구성에 보관하고 선택적 통합은 추가 설치 옵션이나 기능 그룹을 통해 제공한다. 로컬 기본값으로 파일 기반 관계형, 벡터, 그래프 스토리지를 사용할 수 있지만, 운영 배포에서는 스토리지 경로, 원격 요청 권한, 로컬 파일 접근, 원시 쿼리 권한, 인증, 테넌트 격리, 영속 객체 스토리지를 함께 검토해야 한다. ## 새 스토리지나 검색 전략은 정해진 등록 지점으로 추가하기 가장 좁고 안정적인 확장 지점에 기능을 추가한다. 작업을 구현해 파이프라인에 등록하거나, 새 백엔드를 위한 스토리지 인터페이스를 구현하거나, 모델 게이트웨이 뒤에 공급자 구성을 추가하거나, 새 형식을 지원하도록 문서 로더를 확장하거나, 조회 전략을 등록하거나, 공통 데이터 포인트 계약을 확장하는 그래프 모델을 정의한다. 온톨로지 기반 추출에서는 리졸버, 온톨로지 소스, 매칭 전략을 구성 가능하게 유지한다. 저장 전에 추출된 엔터티 유형과 관계가 선택한 의미 체계를 준수하는지 검증한다. 새 확장 기능은 필요한 의존성, 지원 기능, 구성 필드, 실패 동작을 명시해야 한다. ## 구성 요소별 테스트와 가져오기부터 검색까지 전체 흐름 테스트 작성하기 단위 동작, 통합 경계, 명령줄 또는 API 진입점, 작업별 동작을 기준으로 테스트를 구성한다. 모든 기능에는 집중된 테스트가 필요하며, 스토리지 어댑터, 모델 게이트웨이, 기타 통합에는 현실적인 구성과 실패 응답을 사용한 경계 테스트가 필요하다. 수집에서 변환을 거쳐 조회까지 이어지는 전체 수명 주기 통합 경로를 하나 이상 유지하며, 비동기 실행과 인가 필터링을 포함한다. 각 공개 비동기 함수는 직접 대기하거나 이벤트 루프 실행기를 사용해 테스트한다. 저장소 정책에 따라 커버리지, 린트, 포맷팅, 타입 검사를 실행하고 테스트를 소스 계층 구조에 맞춘다. ## 먼저 설정을 확인하고 빈 검색 결과와 오류를 구분하기 파이프라인 로직을 변경하기 전에 구성 오류를 진단한다. 서로 짝을 이루는 모델 및 임베딩 설정, 구조화 출력 모드, 토크나이저 호환성, 데이터베이스 URL과 자격 증명, 서비스 가용성, 속도 제한 설정을 확인한다. 공급자 폴백을 명확히 드러내어 부분적인 구성이 의도하지 않은 원격 서비스를 조용히 선택하지 못하게 한다. 인가를 거친 빈 결과와 전송 또는 파싱 오류를 구분한다. 권한으로 필터링된 검색은 레코드의 존재를 노출해서는 안 되고, 연결 오류는 어댑터와 실패한 전제 조건을 밝혀야 하며, 속도 제한 오류는 재시도 시점을 알려야 하고, 구조화 출력 오류는 구성된 추출 모드를 밝혀야 한다. 구조화 로그와 선택적 디버그 계측을 사용하되 자격 증명이나 조회된 민감한 콘텐츠는 절대 기록하지 않는다.