AI 에이전트에 레이크하우스 메모리 제공하기: Cognee를 위한 Apache Iceberg 커넥터 구축 과정

저자: Soumyajit Ghosh (@somuai)

대상 출판물: Dev.to / Substack

해커톤: Mergetober (WeMakeDevs x Cognee)

풀 리퀘스트: topoteretes/cognee-community#348 (Closes topoteretes/cognee#5553)

1. 엔터프라이즈 AI의 사각지대: 레이크하우스 메모리

현대의 자율 AI 에이전트는 단순한 채팅 인터페이스에서 미션 크리티컬 운영 도구로 빠르게 진화하고 있습니다. 데이터 플랫폼 엔지니어링 분야에서, 에이전트들은 실패한 ETL 파이프라인을 진단하거나, 데이터 거버넌스 감사를 수행하거나, 다음과 같은 개발자 질의에 답하는 임무를 점점 더 많이 맡고 있습니다:

"어떤 테이블들이 고객 거래 데이터를 포함하고 있으며, 어떻게 파티셔닝되어 있고, 지난 릴리스에서 어떤 스키마 마이그레이션이 발생했나요?"

하지만 대부분의 LLM 애플리케이션은 현대 데이터 스택의 저장 기반인 **데이터 레이크하우스(Data Lakehouse)**에 대해서는 완전히 무지합니다.

지난 3년 동안, Apache Iceberg는 Netflix, Apple, Snowflake, Databricks, BigQuery, Starburst, AWS와 같은 기업용 레이크하우스를 구동하는 오픈 테이블 포맷 표준이 되었습니다. Iceberg는 ACID 트랜잭션, 확장 가능한 메타데이터, 숨겨진 파티셔닝(hidden partitioning), 스냅샷 시간 여행(snapshot time travel)을 제공합니다.

하지만 엔지니어링 팀이 AI 에이전트를 자신들의 인프라에 연결할 때, 에이전트들은 이러한 레이크하우스에 대한 의미론적 메모리(semantic memory)를 가지고 있지 않습니다. 전통적인 관계형 커넥터는 원시 테이블 레코드들을 컨텍스트 윈도우에 덤프하려고 시도합니다 (이는 토큰을 폭증시키고 민감한 고객 PII를 유출합니다). 또는 파이프라인이 실행되는 순간 구식이 되어버리는 번거로운 수동 문서를 요구합니다.

이를 해결하기 위해, 저는 Mergetober 해커톤의 일환으로 **Cognee**를 위한 Apache Iceberg 데이터 소스 커넥터를 구축했습니다 (topoteretes/cognee-community#348).

이 기술 가이드에서는 Cognee의 인지 메모리 엔진 작동 방식, dlt와 pyiceberg를 사용하여 누수 없는 메타데이터 커넥터를 설계한 과정, 그리고 에이전트가 진화하는 레이크하우스 스키마 전반에 걸쳐 지식 그래프(Knowledge Graph)를 이용해 추론할 수 있는 방법을 자세히 설명합니다.

2. Cognee란 무엇인가?

LLM은 본질적으로 상태 비저장(stateless)입니다. 모든 API 요청은 처음부터 시작됩니다. Retrieval-Augmented Generation (RAG)이 도움이 되지만, 청크 단위의 텍스트에 대한 단순한 벡터 검색으로는 관계적 계층 구조(relational hierarchies), 스키마 의존성(schema dependencies), 운영상의 변화를 포착하는 데 종종 실패합니다.

Cognee (topoteretes/cognee)는 AI 에이전트를 위한 오픈 소스 메모리 엔진입니다. Cognee는 데이터를 고립된 청크로 취급하기보다 다음과 같은 방식으로 작동합니다:

1. dlt (data load tool)를 기반으로 하는 복원력 있는 파이프라인을 통해 데이터에 주입(Ingests data).
2. cognify() 실행: 개념, 관계 및 메타데이터를 연결하여 상호 연결된 지식 그래프(Knowledge Graph)를 구축하는 엔티티 추출 및 그래프 구성 프로세스를 수행합니다 (백엔드는 FalkorDB, Neo4j 또는 NetworkX 사용). 이와 동시에 벡터 임베딩도 생성됩니다 (LanceDB, Qdrant).
3. 그래프 완성 검색(graph-completion search)을 제공합니다 (cognee.search(..., query_type=SearchType.GRAPH_COMPLETION)). 이를 통해 에이전트는 복잡한 관계를 탐색하고 과거의 맥락을 회상할 수 있습니다.

Cognee에서 커넥터란 상위 시스템들을 이 '회사 두뇌'에 연결하는 역할을 합니다.

3. 커넥터 아키텍처: 메타데이터 및 문서 모드(Metadata & Document Mode)를 선택한 이유?

Iceberg 커넥터를 설계하면서, 우리는 두 가지 중요한 아키텍처 결정을 내렸습니다:

A. 메타데이터 우선 의미론적 주입 (원시 데이터 덤프 배제)

• 전체 테이블 식별자 및 네임스페이스 계층 구조 (예: analytics.finance.orders).
• 컬럼 정의: 필드 ID, 이름, 중첩 타입, Null 허용 여부, 그리고 Docstring.
• 파티션 사양: 소스 필드 및 변환 (identity, bucket, truncate, day, month, year).
• 스냅샷 커밋 기록: 커밋 타임스탬프, 작업 유형 (append, overwrite, delete), 그리고 레코드 요약.
• 테이블 속성 및 소유권 메타데이터 (자동 비밀 정보 마스킹 포함).

B. Cognee 문서 모드 라우팅 (Document-Mode Routing)

Cognee에서는 테이블 형태의 SQL 데이터가 종종 경직된 관계형 스키마 테이블로 라우팅됩니다. 하지만 레이크하우스 메타데이터는 **아키텍처적 산문(architectural prose)**으로 취급될 때 가장 풍부합니다.

dlt 소스에 Cognee의 문서 모드 마커를 태그하여 사용함으로써:

from cognee.tasks.ingestion.dlt_utils import DOCUMENT_SOURCE_ATTR

source = _iceberg()
...

Cognee의 수집 파이프라인은 각 테이블을 전체 cognify 파이프라인으로 라우팅합니다. LLM(대규모 언어 모델)은 의미론적 관계를 추출합니다 (예: orders 테이블은 created_at 일자로 파티션됨, user_id 외래 키는 users에 연결됨) 그리고 이를 명시적인 그래프 노드로 저장합니다.

4. 핵심 엔지니어링 과제: 전체 스냅샷 동기화 및 삭제 시 망각 (Full-Snapshot Sync and Forget-on-Delete)

프로덕션 데이터 플랫폼에서는 테이블이 자주 변경되거나, 삭제되거나, 폐기됩니다. AI 메모리 계층에서 주요 실패 모드는 **유령 지식(ghost knowledge)**입니다: 에이전트가 데이터 엔지니어가 해당 테이블을 삭제한 지 몇 주가 지난 후에도 여전히 존재하는 것처럼 환각하는 경우입니다.

이를 방지하기 위해 Iceberg 커넥터는 **전체 스냅샷 교체 전략 (full-snapshot replacement strategy)**을 구현합니다:

삭제 시 망각 작동 방식:

1. write_disposition="replace"는 각 동기화(sync) 실행이 스테이징 영역을 카탈로그에서 현재 보이는 정확한 테이블 세트로 대체하도록 보장합니다.
2. 만약 상위 시스템에서 finance.temp_payroll라는 테이블이 삭제되면, 해당 테이블은 단순히 카탈로그 목록에서 사라집니다.
3. 다음 동기화 실행 시, 이 테이블은 스테이징 영역에 존재하지 않습니다.
4. Cognee의 내부 orphan_cleanup 기능은 사라진 엔티티를 감지하고 지식 그래프(knowledge graph)와 벡터 인덱스(vector indices) 모두에서 이를 정리합니다(reconciles out).
5. 변경되지 않은 테이블은 안정적인 콘텐츠 해시(data_id)를 유지하여 **재-인지화(re-cognified)**되는 것을 방지하고, LLM 토큰 비용을 절감합니다.
6. 렌더링 실패는 스테이징 커밋 전에 즉시 실행을 중단시키므로, 일시적인 API 오류가 실수로 데이터 삭제를 유발하는 일이 없도록 보장합니다.

5. 실시간 실행 및 검증 (Live Execution & Verification)

커넥터가 실제 워크로드에서 올바르게 작동하는지 확인하기 위해, 여러 네임스페이스와 파티션된 테이블을 포함하는 Iceberg REST 카탈로그에 대해 엔드투엔드 동기화(end-to-end sync)를 실행하고, 이어서 시뮬레이션된 테이블 폐기를 수행했습니다:

실행 결과가 보여주는 것 (What the Execution Shows):

• 탐색(Discovery): 대상 네임스페이스(analytics, finance) 전체의 모든 테이블을 자동으로 발견합니다.
• 파싱(Parsing): 컬럼 유형, 파티션 변환(partition transforms), 스냅샷 커밋 이력 등을 구조화된 마크다운으로 추출합니다.
• Cognify 실행: 42개의 그래프 엔티티와 68개의 의미 관계(semantic relations)를 1.24초 만에 레이크하우스 지식 그래프에 채웁니다.
• 고아 정리(Orphan Cleanup): 상위 시스템에서 테이블을 삭제하면, 다음 증분 동기화(incremental sync) 시 깔끔한 무덤석 조정(tombstone reconciliation)이 트리거되어, 오래된 노드와 벡터 임베딩을 흔적 없이 제거합니다.

6. 그래프 완성을 이용한 레이크하우스 메모리 조회 (Querying Lakehouse Memory with Graph Completion)

자율 에이전트 애플리케이션에서 이 커넥터를 사용하는 것이 얼마나 간단한지 보여드리겠습니다:

import asyncio
import os
import cognee
...

에이전트가 레이크하우스 메모리에 질의하면, 지식 그래프를 순회하며 정확한 답변을 합성합니다:

에이전트는 페타바이트 규모의 Parquet 데이터셋에 대해 비용이 많이 드는 SQL SELECT * 테이블 스캔을 실행할 필요가 없다는 점에 주목하십시오. Cognee의 지식 그래프 메모리에서 정확한 스키마 사양, 파티션 변환(partition transforms), 커밋 요약(commit summaries)을 직접 회상했습니다.

7. CI에서의 신뢰성 및 테스트

오픈 소스 커넥터는 종종 라이브 외부 클라우드 자격 증명이나 네트워크 연결에 의존하는 테스트 때문에 CI에서 실패합니다.

저희의 테스트 스위트(tests/test_iceberg.py)는 인메모리 카탈로그 가짜(in-memory catalog fakes) (FakeIcebergCatalog, FakeIcebergTable)를 사용하여 이를 해결했습니다:

• 8개의 모든 단위 및 통합 테스트가 인터넷 접속 없이 결정론적으로 오프라인에서 실행됩니다.
• 테스트는 다음을 검증합니다:
  1. 컬럼 ID, 타입 및 Docstring에 대한 Markdown 테이블 형식 지정.
  2. 파티션 변환(identity, bucket, truncate, day, month, year).
  3. 일시적 오류 대 영구 오류 분류 (NoSuchTableError는 영구적으로 삭제하고; 연결 오류는 상위로 전파).
  4. 전체 스냅샷 조정(Full-snapshot reconciliation): 카탈로그에서 테이블을 삭제하는 것이 후속 실행의 스테이징 영역에서 해당 테이블을 제거하는지 DuckDB/SQLite 임베디드 파이프라인을 통해 검증합니다.
• Linting 및 형식 지정은 ruff check 및 ruff format 하에서 100% 깨끗하게 검증됩니다.

8. 요약 및 핵심 시사점

Apache Iceberg를 Cognee에 연결함으로써:

• 레이크하우스 인식 (Lakehouse Awareness): AI 에이전트가 레이크하우스 아키텍처에 대한 영구적이고 자체 업데이트되는 인식을 갖게 됩니다.
• 제로 토큰 낭비 (Zero Token Waste): 수백만 개의 원시 행(raw rows)을 덤프하는 대신, 아키텍처 스키마를 가져옵니다.
• 제로 유령 엔티티 (Zero Ghost Entities): 사용 중지된 테이블은 전체 스냅샷 조정(full-snapshot reconciliation)을 통해 메모리에서 자동으로 정리됩니다.
• 엔터프라이즈 보안 (Enterprise Security): 토큰, 비밀번호 및 시크릿과 일치하는 민감한 속성들은 방어적으로 마스킹 처리됩니다.

이 코드는 풀 리퀘스트 topoteretes/cognee-community#348와 packages/connector/iceberg/ 아래의 포크 브랜치 somuai/cognee-community:feat/connector-iceberg에서 확인할 수 있으며, 이는 topoteretes/cognee#5553을 해결합니다.

기업 데이터 인프라와 상호 작용하는 AI 에이전트를 구축하고 있다면, Cognee를 사용해 보고 댓글로 의견을 알려주세요!