cognee 딥다이브
— AI 에이전트에게 "잊지 않는 기억"을 주는 오픈소스 메모리 플랫폼

문서·코드·대화 등 어떤 데이터든 집어넣으면, cognee가 그것을 지식 그래프(서로 연결된 점과 선)와 벡터 임베딩(의미 좌표)으로 동시에 바꿔, AI가 세션이 바뀌어도 "의미로 검색하고 + 관계로 연결해서" 기억을 꺼내 쓰게 한다. 단순 RAG가 아니라 GraphRAG 기반 메모리 계층이며, remember / recall / forget / improve 네 줄로 다룬다. (저장소: topoteretes/cognee · v1.2.1 · Python · Apache-2.0 · 논문 arXiv:2505.24478 보유 · TrendShift #7)

1프로젝트 한줄 요약

"내 데이터를, AI가 평생 기억하고 연결해서 쓰는 두뇌로 바꿔준다."

핵심 용어 두 개부터 풀자. 지식 그래프(knowledge graph)는 정보를 노드(점)와 엣지(선)로 표현한 지도다. "스티브 잡스—설립—애플"처럼 점과 점을 관계로 잇는다. 벡터 임베딩(vector embedding)은 글의 의미를 숫자 목록(좌표)으로 바꾼 것으로, 좌표가 가까우면 의미가 비슷하다. cognee는 이 둘을 한꺼번에 만들어, "키워드가 안 겹쳐도 의미가 비슷한 것"과 "직접 연결된 사실"을 모두 검색할 수 있게 한다.

cognee는 라이브러리(파이썬 패키지)이면서, 동시에 API 서버·MCP 서버·웹 UI로도 띄울 수 있다. 만든 곳은 topoteretes(Vasilije Markovic, Boris Arzentar 등)이고, 단순 오픈소스를 넘어 학술 논문(「지식 그래프와 LLM 인터페이스 최적화」, arXiv:2505.24478)까지 낸, 이론적 배경이 있는 프로젝트다.

2왜 주목받는가

"벡터만 쓰는 평범한 RAG의 한계를, 그래프를 더해 넘어선다."

2024~2026년 AI 앱의 표준 기억법은 RAG(검색 증강 생성)였다. 문서를 잘게 잘라 벡터로 만들고, 질문과 의미가 가까운 조각을 찾아 LLM에 붙여 준다. 강력하지만 약점이 뚜렷하다 — "조각들 사이의 관계"를 모른다. "A가 B의 상사이고, B가 C 프로젝트를 망쳤다"는 연결된 추론은, 흩어진 텍스트 조각만으로는 잘 안 된다.

트렌딩을 끌어올린 결정적 변화는 "메모리 플랫폼"으로의 재포지셔닝이다. 초기 cognee는 "GraphRAG 라이브러리"였지만, 지금은 에이전트의 장기 기억 인프라를 표방한다. 특히 Claude Code 플러그인으로 코딩 에이전트의 세션 기억을 자동 저장/주입하고, remember / recall / forget / improve라는 사람이 외우기 쉬운 4개 동사 API를 전면에 내세워 진입 장벽을 확 낮췄다.

경쟁/대안과 무엇이 다른가

물론 대가도 있다. 데이터를 넣을 때 LLM으로 개체·관계를 뽑는 단계(cognify)가 들어가, 순수 벡터 RAG보다 인덱싱이 느리고 LLM 호출 비용이 든다. 즉 cognee의 매력은 "가장 빠르고 싼 검색"이 아니라, "관계까지 기억하는, 추론 가능한 메모리"다. 빠른 1회성 검색이면 평범한 RAG가 낫고, 누적되는 지식·에이전트 장기 기억이면 cognee가 빛난다.

3기술 스택 전체 지도

100% 파이썬. 핵심은 'LLM 추상화 + 갈아끼우는 DB 어댑터 + 비동기 파이프라인'.

cognee는 Voicebox 같은 데스크탑 앱과 달리 순수 파이썬 라이브러리(Python 3.10~3.14)다. 그래서 "프론트엔드/백엔드/인프라"보다 ① LLM 레이어 ② 저장소(DB) 레이어 ③ 파이프라인/서빙 레이어 세 축으로 보는 게 머리에 잘 들어온다. 가장 큰 설계 미덕은 모든 외부 의존성을 '갈아끼울 수 있는 어댑터'로 추상화했다는 점이다.

① LLM·임베딩 레이어 — "어떤 모델이든 꽂는다"

cognee는 특정 LLM에 묶이지 않는다. litellm이라는 통합 클라이언트로 OpenAI·Anthropic·Ollama(로컬)·Mistral·Groq 등 수십 개 공급자를 같은 코드로 부른다. 그리고 instructor로 LLM의 자유로운 텍스트 응답을 구조화된 데이터(Pydantic 객체)로 강제한다 — 지식 그래프를 뽑으려면 "사람·관계"가 정해진 형식으로 나와야 하기 때문이다.

② 저장소(DB) 레이어 — 세 종류 DB를 동시에

cognee의 진짜 독특함은 여기 있다. 보통 앱은 DB 하나를 쓰지만, cognee는 관계형 + 벡터 + 그래프 세 종류를 함께 쓴다. 각각 어댑터 패턴으로 추상화돼, 환경변수만 바꾸면 로컬 임베디드 ↔ 운영용 서버로 갈아끼운다.

③ 파이프라인·서빙 레이어 — 비동기로 굴러가는 ETL

데이터를 기억으로 바꾸는 과정은 여러 단계의 비동기 작업(Task) 사슬이다(다음 절에서 자세히). 이걸 API로도 열 수 있게 FastAPI 서버, MCP 서버, Next.js 프론트엔드가 함께 들어 있다.

4아키텍처 심화 분석 — ECL 파이프라인

cognee의 심장은 'Extract → Cognify → Load' 라는, 데이터를 기억으로 굽는 3단계 가마다.

cognee의 동작은 두 줄의 핵심 함수로 요약된다. cognee.add(데이터)로 원본을 받아 적재(ingest)하고, cognee.cognify()로 그걸 지식 그래프 + 벡터로 굽는다. 이 cognify가 cognee를 cognee이게 하는 부분으로, 내부적으로 ECL(Extract–Cognify–Load) 파이프라인을 돈다. 실제 소스(cognify.py)의 기본 작업 사슬은 다음과 같다.

핵심 설계 패턴 1 — Task 파이프라인 (조립식 사슬)

위 ①~⑤는 모두 Task(함수, 설정...) 객체로, 리스트에 담긴 작업 사슬이다. run_pipeline이 이 리스트를 순서대로 비동기 실행하며 청크를 배치(batch) 단위로 흘려보낸다. 덕분에 사용자는 기본 사슬을 그대로 쓰거나, 중간 Task를 갈아끼워 '나만의 cognify'를 만들 수 있다(예: 시간정보 추출용 temporal_tasks 사슬이 따로 존재).

# cognify.py의 기본 작업 사슬 (요지)
default_tasks = [
    Task(classify_documents),                 # E: 타입 분류
    Task(extract_chunks_from_documents, ...), # E: 청크 분할
    Task(extract_graph_and_summarize, ...),   # C: 그래프+요약 (LLM)
    Task(add_data_points, ...),               # L: DB 저장
    Task(extract_dlt_fk_edges),               # L: 외래키 엣지
]
# run_pipeline이 이 리스트를 batch로 비동기 실행

핵심 설계 패턴 2 — DataPoint (모든 노드의 공통 DNA)

그래프에 들어가는 모든 노드는 DataPoint라는 Pydantic 모델을 상속한다. 여기에 cognee의 영리한 한 수가 있다 — identity_fields. 기본 ID는 랜덤(UUID)이라 실행할 때마다 다른 노드가 되지만, "이름" 같은 정체성 필드를 지정하면 그 값으로 ID를 결정론적으로 계산한다. 그래서 "스티브 잡스"가 문서 10곳에 나와도 전부 같은 노드 하나로 병합된다(개체 통합·중복 제거).

핵심 설계 패턴 3 — 검색 전략(SearchType)을 골라 쓴다

같은 그래프라도 질문 성격에 맞는 검색 방식이 다르다. cognee는 search(질의, query_type=SearchType.XXX)로 전략을 고른다. 대표적인 것만:

마지막으로, 사용자가 마주하는 2계층 API를 정리하자. V1(저수준)은 add / cognify / search / prune처럼 파이프라인을 직접 다루고, V2(메모리 지향)는 remember / recall / forget / improve로 추상화했다. remember()는 내부적으로 add + cognify + improve를 묶어 실행하는 식이다 — 초보자는 V2 4동사부터, 깊이 파면 V1 파이프라인으로 내려가면 된다.

5디렉토리 구조 해부

레포는 '라이브러리 본체(cognee/) + 서버·UI·분산'의 모노레포다.

저장소 최상위는 크게 ① 라이브러리 본체(cognee/) ② MCP 서버(cognee-mcp/) ③ 프론트엔드(cognee-frontend/) ④ 분산 실행(distributed/) ⑤ 예제·평가로 나뉜다. 핵심은 cognee/ 안의 3분할 구조다 — api(겉으로 드러난 명령), modules(도메인 로직), tasks(파이프라인 한 칸 한 칸), 그리고 그 아래를 받치는 infrastructure(DB·LLM 어댑터).

6학습 포인트 (기술별)

cognee 한 레포에 'AI 메모리 시스템'을 짓는 데 필요한 거의 모든 조각이 들어 있다.

① GraphRAG — 검색의 다음 단계

벡터 RAG만 알던 사람에게 cognee는 "왜 그래프를 더하는가"의 살아 있는 교과서다. tasks/graph/와 modules/retrieval/를 읽으면, LLM으로 관계를 뽑아 그래프를 만들고 그걸 순회해 답하는 흐름이 보인다.

② 어댑터 패턴 — 의존성 갈아끼우기

infrastructure/databases/는 인터페이스(추상) + 구현(어댑터) 분리의 모범 사례다. vector_db_interface.py라는 약속을 정해두고, LanceDB·pgvector가 각자 구현한다. 새 벡터 DB를 붙이고 싶으면 인터페이스만 채우면 된다 — OCP(개방-폐쇄 원칙)의 실전.

③ LLM 구조화 출력 — instructor 패턴

"LLM이 JSON을 깨뜨린다"는 흔한 고통을 cognee는 instructor + Pydantic으로 푼다. tasks/graph/에서 KnowledgeGraph 스키마를 정의하고 LLM 출력을 그 틀에 맞춰 검증·재시도하는 코드를 보면, 프로덕션에서 LLM을 다루는 정석을 배운다.

④ 비동기 파이프라인 — asyncio 배치 처리

modules/pipelines/의 run_pipeline은 Task 리스트를 비동기로, 배치 단위로 흘려보낸다. 수백~수천 청크를 LLM에 보낼 때 동시성으로 처리량을 끌어올리는 패턴(세마포어·배치)을 학습하기 좋다.

⑤ MCP 서버 — 에이전트에 도구 열어주기

cognee-mcp/는 @mcp.tool로 cognify_file·search·list_datasets·visualize_graph_ui 등을 노출한다. "내 라이브러리를 AI 에이전트의 도구로 만드는 법"의 깔끔한 예제다.

⑥ 멀티테넌시·권한 — fastapi-users

modules/users/는 사용자·테넌트별로 데이터를 격리한다. "여러 사용자가 한 메모리 서버를 공유하되 서로 못 보게" 만드는 SaaS형 권한 설계를 엿볼 수 있다.

7하드웨어/시스템 요구사항

기본은 노트북에서도 충분 — 부담은 'GPU'가 아니라 'LLM API 비용'이다.

cognee는 Voicebox처럼 거대한 로컬 모델을 돌리는 앱이 아니다. 무거운 추론(개체·관계 추출)은 외부 LLM(예: OpenAI)에 위임하므로, 내 컴퓨터의 부담은 가볍다. 진짜 비용은 LLM API 호출(토큰) 요금이다.

8직접 해볼 수 있는 실습 과제

"설치 5분 → 기억 만들기 → 그래프 눈으로 보기 → 내 파이프라인"으로 난이도 상승.

과제 1. 5줄로 첫 기억 만들기 난이도 ★☆☆☆☆

가상환경을 만들고 pip install cognee → LLM_API_KEY 설정 → 아래를 실행한다. cognee의 V2 4동사를 몸으로 익히는 단계.

import cognee, asyncio

async def main():
    await cognee.remember("cognee는 문서를 AI 메모리로 바꾼다.")
    results = await cognee.recall("cognee가 뭐 하는 거야?")
    for r in results: print(r)

asyncio.run(main())

과제 2. 내 PDF를 지식 그래프로 굽기 난이도 ★★☆☆☆

cognee.add("./내문서.pdf") → cognee.cognify() → cognee.search(...) 흐름을 직접 돌려 본다. 작은 PDF(5~10쪽)로 시작해 "이 문서의 핵심 인물/개념의 관계"를 물어보라.

과제 3. RAG vs GraphRAG 비교 실험 난이도 ★★★☆☆

같은 데이터에 대해 SearchType.RAG_COMPLETION과 SearchType.GRAPH_COMPLETION 결과를 나란히 출력한다. multi-hop 질문("X가 속한 팀의 리더가 진행한 다른 프로젝트는?")에서 어느 쪽이 이기는지 표로 정리 — cognee의 존재 이유를 스스로 증명하는 과제.

과제 4. 그래프를 눈으로 보고 CLI/UI 띄우기 난이도 ★★★☆☆

cognee.visualize_graph()로 그래프를 그리거나, cognee-cli -ui로 로컬 UI를 띄워 노드·엣지를 시각적으로 탐색한다. "내 문서가 어떤 모양의 지식 그래프가 됐는지" 직접 보는 경험이 핵심.

과제 5. 나만의 cognify 파이프라인 / 에이전트 연동 난이도 ★★★★★

get_default_tasks()를 참고해 Task 하나를 추가·교체한 커스텀 파이프라인을 만들어 본다(예: 번역 Task 삽입, 또는 temporal 사슬 사용). 더 나아가 cognee MCP 서버를 Claude Code/Cursor에 붙여, 코딩 세션 기억이 자동 저장·주입되는 환경을 구성한다.

9관련 기술 심화 학습 로드맵

'임베딩 → 벡터 RAG → 지식 그래프 → GraphRAG → 에이전트 메모리'의 4주 코스.

10핵심 키워드 사전

cognee 문서·코드에서 반복되는 용어를 한 곳에.

11참고 링크

공식 저장소·문서·논문·커뮤니티.