AI 메모리 구축을 위한 Cognee 가이드

Summary

Cognee를 설치하고 AI 메모리를 저장·검색하는 첫 단계까지 안내합니다.

빠른 시작

저장소: topoteretes/cognee

Apache-2.0 license 29.2k stars 2.8k forks

가장 짧은 체험 순서는 다음과 같습니다.

1. Python 3.10~3.14를 준비합니다.
2. PowerShell에서 uv와 Cognee를 설치합니다.
3. 작업 폴더에 .env 파일을 만들고 LLM API 키를 설정합니다.
4. cognee-cli remember로 문장을 저장합니다.
5. cognee-cli recall로 저장한 내용을 검색합니다.

pip install uv
uv pip install cognee

.env 파일에는 다음 형식으로 키를 기록합니다.

LLM_API_KEY="YOUR_OPENAI_API_KEY"

그다음 PowerShell에서 실행합니다.

cognee-cli remember "Cognee turns documents into AI memory."
cognee-cli recall "What does Cognee do?"

WARNING

실제 API 키를 문서, 화면 캡처 또는 Git 커밋에 포함하지 마세요. LLM 제공자에 따라 외부 API 호출과 비용이 발생할 수 있습니다.

저장소 소개

Cognee는 AI 에이전트에 세션을 넘어 유지되는 장기 메모리를 제공하는 오픈 소스 Python 플랫폼입니다. 여러 형식의 데이터를 받아 자체 호스팅 지식 그래프를 만들고, 의미 기반 벡터 검색과 관계 기반 그래프 추론을 결합합니다.

README에서 확인되는 주요 작업은 다음 네 가지입니다.

작업	의미
remember	데이터를 영구 그래프 메모리 또는 세션 메모리에 저장
recall	질문에 맞는 검색 방식을 자동 선택해 메모리 조회
forget	데이터셋 또는 소유한 메모리 삭제
improve	메모리 개선 작업

기본 개발 환경은 별도 서버 없이 SQLite, LanceDB, Kuzudb를 사용하는 구성이며, 배포 환경에서는 PostgreSQL을 전체 메모리 계층으로 사용할 수 있다고 README에 설명되어 있습니다.

Windows 사전 준비

필수 조건은 Python 3.10~3.14입니다. 설치 후 사용할 PowerShell 창에서 다음 명령이 인식되는지 확인합니다.

python --version
pip --version

python --version과 pip --version은 일반적인 확인 방법이지만, 제공된 원본에 이 두 확인 명령은 직접 기재되어 있지 않습니다. 따라서 명령이 동작하지 않을 때의 Windows PATH 설정 방법은 원본에서 확인되지 않음입니다.

빠른 시작에 사용할 구성 요소는 다음과 같습니다.

구성 요소	필요 여부	원본에서 확인된 내용
Python	필수	3.10~3.14
uv	이 가이드에서 사용	pip install uv 설치 명령 확인
LLM API 키	기본 구성에서 필요	.env의 LLM_API_KEY 사용
Docker	기본 CLI 체험에는 불필요	로컬 UI의 MCP 서버 실행에는 필요
관리자 권한	확인되지 않음	원본에서 확인되지 않음

TIP

처음에는 Docker나 프런트엔드를 함께 실행하지 말고, CLI의 저장과 검색만 먼저 확인하세요.

설치와 실행

작업용 폴더에서 PowerShell을 열고 다음 명령을 순서대로 실행합니다.

pip install uv
uv pip install cognee

이후 같은 작업 폴더에 .env라는 파일을 만들고 다음 내용을 입력합니다. YOUR_OPENAI_API_KEY는 본인의 실제 키로 바꿉니다.

LLM_API_KEY="YOUR_OPENAI_API_KEY"

다른 LLM 제공자도 지원된다고 안내되어 있지만, 제공자별 정확한 환경 변수와 모델 설정은 이 자료에서 모두 확인되지 않습니다. 해당 설정은 원본의 LLM Provider Documentation에서 확인해야 합니다.

메모리를 저장하고 조회합니다.

cognee-cli remember "Cognee turns documents into AI memory."
cognee-cli recall "What does Cognee do?"

실습 데이터를 모두 삭제하려면 다음 명령을 사용할 수 있습니다.

cognee-cli forget --all

WARNING

cognee-cli forget --all은 저장한 메모리를 모두 삭제하는 명령입니다. 필요한 데이터가 없는 실습 환경에서만 실행하세요.

로컬 UI는 다음 명령으로 열 수 있습니다.

cognee-cli -ui

다만 README에 따르면 이 UI가 시작하는 MCP 서버는 Docker 컨테이너 안에서 실행됩니다. Docker Desktop 또는 작동하는 docker CLI를 제공하는 호환 런타임이 필요합니다.

첫 성공 확인

다음 두 명령이 오류 없이 순서대로 끝나면 기본 설치가 작동한 것입니다.

cognee-cli remember "Cognee turns documents into AI memory."
cognee-cli recall "What does Cognee do?"

recall 결과의 정확한 출력 형식과 문구는 원본에서 확인되지 않음입니다. 다만 저장한 문장의 의미와 관련된 결과가 반환되는지를 확인하면 됩니다.

실패한다면 다음 항목만 우선 점검합니다.

• Python 버전이 3.10~3.14인지 확인합니다.
• .env 파일 이름이 정확한지 확인합니다.
• LLM_API_KEY의 따옴표 안에 실제 키가 들어 있는지 확인합니다.
• LLM 제공자의 네트워크 연결과 사용 한도 또는 결제 상태를 확인합니다. 구체적인 오류별 해결 명령은 원본에서 확인되지 않음입니다.
• cognee-cli -ui만 실패한다면 Docker Desktop과 docker CLI가 준비되었는지 확인합니다.

핵심 구조

경로	역할
README.md	프로젝트 소개, 기본 설치, CLI·Python 사용법, Docker 실행 안내
cognee/	Python 메모리 엔진과 작업 모듈, 평가 도구, 테스트가 포함된 핵심 영역
cognee-mcp/	Cognee 메모리 엔진을 MCP 서버로 제공
cognee-frontend/	Next.js 기반 프런트엔드
examples/	데모, 가이드, 사용자 정의 파이프라인, 데이터베이스 구성 예제
distributed/	배포 스크립트와 워커 구성
.env.template	환경 변수 설정의 출발점
cognee-starter-kit/	폐기된 스타터 키트로, 새 작업의 출발점으로 사용하지 않는 것이 안전

MCP 서버는 에이전트용으로 remember, recall, forget 중심의 메모리 API를 제공합니다. 프런트엔드는 별도 Next.js 프로젝트이며 개발 서버 주소로 http://localhost:3000이 제시되어 있습니다.

동작 흐름

README에서 확인된 기본 메모리 흐름은 다음과 같습니다.

flowchart LR
    A[텍스트 또는 문서] --> B[remember]
    B --> C[세션 메모리]
    B --> D[영구 지식 그래프]
    C --> E[recall]
    D --> E
    E --> F[검색 결과]
    D --> G[forget]

session_id를 지정한 remember는 빠른 세션 캐시에 저장한 뒤 백그라운드에서 그래프와 동기화합니다. session_id 없이 호출하면 영구 그래프 메모리에 저장합니다. recall에 session_id가 있으면 세션 메모리를 먼저 조회하고, 필요한 경우 영구 그래프로 이어서 검색합니다.

내부 처리에는 벡터 임베딩, 그래프 추론, 온톨로지 생성이 결합됩니다. 다만 각 단계의 정확한 클래스 호출 순서와 모든 내부 진입점은 제공된 README 자료만으로 확인되지 않음입니다.

안전 주의사항

WARNING

.env에는 비밀 키가 들어갑니다. 이 파일을 Git에 추가하거나 다른 사람에게 전달하지 마세요.

• remember에 개인정보, 회사 기밀, 인증 정보 또는 접근 토큰을 넣지 마세요. 영구 메모리로 저장될 수 있습니다.
• 외부 LLM을 사용하면 입력 데이터가 해당 제공자에게 전송될 수 있습니다. 전송·보관 정책은 선택한 제공자에서 별도로 확인해야 합니다.
• forget --all은 전체 메모리를 지우므로 실행 전 대상과 백업 필요성을 확인합니다.
• Docker에서 -p 8000:8000 같은 포트 매핑을 사용하면 서비스 접근 범위가 달라질 수 있습니다. 방화벽과 외부 공개 여부를 확인하세요.
• MCP의 HTTP 또는 SSE 전송을 외부에 공개할 때 필요한 인증·TLS 구성 절차는 제공된 원본에서 확인되지 않음입니다.
• 저장소의 배포 스크립트에는 bash 기반 명령이 포함되어 있습니다. Windows PowerShell에서 그대로 실행할 수 있는지는 원본에서 확인되지 않음입니다.
• cognee-starter-kit은 폐기되었다고 명시되어 있으므로 해당 폴더의 예제를 새 프로젝트 기준으로 사용하지 마세요.

다음 단계

1. examples/에서 기본 사용 사례를 살펴봅니다.
2. 설치 문서에서 환경 구성을 확인합니다.
3. Python 비동기 API가 필요하면 README의 asyncio, cognee.remember(), cognee.recall() 예제를 읽습니다.
4. 에이전트 연동이 목표라면 cognee-mcp/README.md를 확인합니다.
5. PostgreSQL 구성이 필요하면 cognee[postgres] 선택 설치와 DB_PROVIDER, VECTOR_DB_PROVIDER, GRAPH_DATABASE_PROVIDER, CACHE_BACKEND 설정을 검토합니다.
6. 기여하려면 CONTRIBUTING.md와 행동 강령을 먼저 읽습니다.

참고한 원본

GitHub에서 원본 저장소 열기 →