GZOO Cortex
공식개발자용 로컬 우선 지식 그래프입니다. 프로젝트 파일을 감시하고 LLM을 통해 엔티티와 관계를 추출하며, 자연어와 소스 인용을 통해 프로젝트 간 질의가 가능합니다.
GZOO Cortex MCP(으)로 무엇을 할 수 있나요?
- 프로젝트에 대해 자연어 질문하기 —
cortex_ask로 지식 그래프를 쿼리하고 출처 인용과 함께 답변을 받습니다. - 시스템 상태 및 그래프 통계 확인 —
get_status를 사용하여 엔터티 수, 제공자 상태, 최근 활동을 확인합니다. - 등록된 프로젝트 목록 및 관리 —
list_projects,add_project,remove_project를 사용하여 추적 중인 디렉터리를 보고 제어할 수 있습니다. - 이름 또는 필터로 엔터티 찾기 및 검색 —
find_entity와search_entities로 결정, 구성 요소, 패턴 등을 찾습니다. - 모순 검토 및 해결 —
get_contradictions는 충돌하는 결정을 표시하고,resolve_contradiction은 해결된 것으로 표시합니다. - 필요 시 파일 수집 —
ingest_file은 감시자를 기다리지 않고 특정 파일에 대한 추출을 트리거합니다.
문서
GZOO Cortex
개발자를 위한 로컬 우선 지식 그래프. 프로젝트 파일을 감시하고, LLM을 사용하여 엔티티와 관계를 추출하며, 모든 프로젝트에서 자연어로 쿼리할 수 있게 해줍니다.
"프로젝트 전반에 걸쳐 어떤 아키텍처 결정을 내렸나요?"
Cortex는 README, TypeScript 파일, 구성 파일, 대화 내보내기에서 결정 사항을 찾아 출처 인용과 함께 답변을 합성합니다.
이유
여러 프로젝트에서 작업합니다. 결정, 패턴, 컨텍스트가 수백 개의 파일에 흩어져 있습니다. 3개월 전에 내린 결정을 잊어버립니다. 다른 저장소에서 이미 해결한 문제를 다시 해결합니다.
Cortex는 프로젝트 디렉터리를 감시하고, 지식을 자동으로 추출하여, 필요할 때 다시 제공합니다.
기능
- 프로젝트 파일(md, ts, js, py, json, yaml)의 변경 사항을 감시합니다
- 결정, 패턴, 구성 요소, 종속성, 제약 조건, 작업 항목 등의 엔티티를 추출합니다
- 프로젝트 전반에 걸쳐 엔티티 간의 관계를 추론합니다
- 결정이 충돌할 때 모순을 감지합니다
- 출처 인용과 함께 자연어로 쿼리합니다
- 의미론적으로 검색합니다 — 키워드와 벡터(임베딩) 유사성을 혼합하여 쿼리가 키워드뿐만 아니라 의미로 일치하도록 합니다 (선택 사항; 의미론적 검색 참조)
- 클라우드와 로컬 LLM 간에 지능적으로 라우팅합니다
- 프라이버시를 존중합니다 — 제한된 프로젝트는 절대 기기를 떠나지 않습니다
- 지식 그래프 시각화, 라이브 피드, 쿼리 탐색기가 있는 웹 대시보드
- Claude Code와의 직접 통합을 위한 MCP 서버
빠른 시작
1. 설치
npm install -g @gzoo/cortex
전역 설치가 EACCES 오류로 실패하면, 대신 사용자 접두사를 사용하세요:
mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @gzoo/cortex
또는 소스에서 설치하세요:
git clone https://github.com/gzoonet/cortex.git
cd cortex
npm install && npm run build && npm link
확인: cortex --version (현재 릴리스: 0.8.1)
2. 설정
대화형 마법사를 실행하세요:
cortex init
cortex doctor # verify config, providers, and DB
이 과정은 다음을 안내합니다:
- LLM 제공자 — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter, 또는 Ollama (로컬)
- API 키 —
~/.cortex/.env에 안전하게 저장됨 - 라우팅 모드 — 클라우드 우선, 하이브리드, 로컬 우선, 또는 로컬 전용
- 감시 디렉터리 — Cortex가 모니터링해야 할 디렉터리
- 예산 한도 — 월간 LLM 지출 한도
cortex init는 전역 구성을 ~/.cortex/cortex.config.json에 기록합니다. API 키는 ~/.cortex/.env에 저장됩니다.
3. 프로젝트 등록
cortex projects add my-app ~/projects/app
cortex projects add api ~/projects/api
cortex projects list # verify
4. 수집, 감시 및 쿼리
먼저 기존 파일을 백필하세요 — 감시자는 새로운 변경 사항만 감지합니다:
cortex ingest "~/projects/app/src/**/*.ts" # one-shot backfill
cortex serve # dashboard + API + file watcher (recommended)
| 명령 | 기능 |
|---|---|
cortex serve | 웹 대시보드 + API + 파일 감시자 (ignoreInitial — 시작 시 재수집 없음) |
cortex watch | CLI 전용 파일 감시자 (대시보드 없음) |
cortex ingest | 일회성 수집; 이벤트가 라이브 피드에 나타나지 않음 |
watch와serve을 함께 실행하지 마세요 — 파일 변경 사항을 두고 경쟁합니다. 라이브 피드는cortex serve의 실시간 이벤트만 표시합니다 (서버가 실행되는 동안 파일 저장).
cortex query "what caching strategies am I using?"
cortex query "what decisions have I made about authentication?"
cortex find "PostgreSQL" --expand 2
cortex contradictions
5. 웹 대시보드
cortex serve # open http://localhost:3710
원격 액세스:
cortex serve --host 0.0.0.0
비로컬호스트 호스트에서는 인증이 자동으로 적용됩니다. 베어러 토큰이 자동 생성되어 ~/.cortex/.env에 저장됩니다 (grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env로 읽기). http://<host>:3710/?token=<token>로 대시보드를 한 번 열면 — 토큰은 이미 소유를 증명한 요청에만 포함되며 이후 브라우저 탭에 유지됩니다 (따라서 익명 방문자는 절대 받지 못함). 리버스 프록시 뒤의 API/WebSocket 호출은 Authorization: Bearer <token>를 사용합니다.
파일 및 디렉터리 제외
Cortex는 기본적으로 node_modules, dist, .git 및 기타 일반적인 디렉터리를 무시합니다. 더 추가하려면:
cortex config exclude add docs # exclude a directory
cortex config exclude add "*.log" # exclude by pattern
cortex config exclude list # see all excludes
cortex config exclude remove docs # remove an exclude
작동 방식
Cortex는 모든 파일 변경 시 파이프라인을 실행합니다:
- 구문 분석 — 파일 콘텐츠가 언어 인식 파서(코드용 tree-sitter, 마크다운용 remark)에 의해 청크로 나뉩니다
- 추출 — LLM이 엔티티(결정, 구성 요소, 패턴 등)를 식별합니다
- 관계 — LLM이 새 엔티티와 기존 엔티티 간의 관계를 추론합니다
- 감지 — 모순과 중복이 자동으로 플래그 지정됩니다
- 저장 — 엔티티, 관계 및 벡터가 SQLite + LanceDB에 저장됩니다
- 쿼리 — 자연어 쿼리가 그래프를 검색하고 답변을 합성합니다
모든 데이터는 ~/.cortex/에 로컬로 유지됩니다. LLM API 호출만 기기를 떠납니다
(제한된 프로젝트의 경우 절대 그렇지 않음).
LLM 제공자
Cortex는 제공자에 구애받지 않습니다. 다음을 지원합니다:
- Anthropic Claude (Sonnet, Haiku) — 네이티브 Anthropic API를 통해
- Google Gemini — OpenAI 호환 API를 통해
- DeepSeek (Reasoner, Chat) — 강력한 추론, 매우 저렴함
- Groq — 무료 티어가 있는 빠른 추론
- 모든 OpenAI 호환 API — OpenRouter, 로컬 프록시 등
- Ollama (Mistral, Llama 등) — 완전 로컬, 클라우드 불필요
비용 추적은 DeepSeek, Gemini, Groq 및 OpenRouter 모델에 대해 제공자 인식 요금을 사용하며, Anthropic으로의 일괄 대체가 아닙니다.
임베딩(의미론적 검색용)은 채팅 모델과 독립적인 별도 제공자로 구성되므로, DeepSeek에서 채팅을 실행하고 OpenAI에서 임베딩을 실행할 수 있습니다. 의미론적 검색을 참조하세요.
라우팅 모드
| 모드 | 클라우드 비용 | 품질 | Ollama 필요 |
|---|---|---|---|
cloud-first | 제공자에 따라 다름 | 최고 | 아니요 |
hybrid | 감소 | 높음 | 예 |
local-first | 최소 | 양호 | 예 |
local-only | $0 | 양호 | 예 |
클라우드 우선 모드에서는 모든 작업이 클라우드 제공자로 라우팅됩니다. Ollama는 필요하지 않으며 예산 대체가 활성화된 경우에만 사용됩니다. 하이브리드 모드는 대량 작업(엔티티 추출, 순위 지정)을 Ollama로 라우팅하고 추론 집약적 작업(관계 추론, 쿼리)을 클라우드 제공자로 라우팅합니다.
요구 사항
- Node.js 20+
- 클라우드 모드용 LLM API 키 — Anthropic, Google Gemini, DeepSeek, Groq 또는 모든 OpenAI 호환 제공자
- Ollama —
hybrid,local-first또는local-only모드에만 필요 (설치)
구성
구성은 계층화되어 있습니다 — 나중 소스가 이전 소스를 재정의합니다:
| 우선순위 | 위치 | 범위 |
|---|---|---|
| 1 | 내장 기본값 | 전역 |
| 2 | ~/.cortex/cortex.config.json | 전역 (cortex init에 의해 생성됨) |
| 3 | ./cortex.config.json | 프로젝트 재정의 (선택 사항) |
| 4 | CORTEX_* 환경 변수 | 세션 |
API 키는 ~/.cortex/.env에 별도로 저장됩니다 (구성 JSON에는 절대 저장되지 않음).
cortex config list # see all non-default settings
cortex config set llm.mode hybrid # switch routing mode
cortex config set llm.budget.monthlyLimitUsd 10 # set budget
cortex config exclude add vendor # exclude a directory from watching
cortex privacy set ~/clients restricted # mark directory as restricted
cortex doctor # validate setup
전체 구성 참조: docs/configuration.md
의미론적 검색 (임베딩)
Cortex는 키워드(전체 텍스트) 검색과 벡터 유사성을 혼합하여 쿼리가 정확한 단어가 아닌 의미로 일치하도록 합니다. 임베딩은 선택 사항이며 기본적으로 꺼져 있습니다 — 클라우드 임베딩 제공자로 활성화하세요 (로컬 GPU 또는 Ollama 불필요):
cortex config set llm.embeddings.enabled true
cortex config set llm.embeddings.baseUrl https://api.openai.com/v1
cortex config set llm.embeddings.model text-embedding-3-small
cortex config set llm.embeddings.apiKeySource env:OPENAI_API_KEY
cortex config set llm.embeddings.dimensions 1536
# then add the key to ~/.cortex/.env:
echo 'OPENAI_API_KEY=sk-...' >> ~/.cortex/.env
임베딩 제공자는 채팅 제공자와 독립적입니다 — DeepSeek(또는 Anthropic, Groq 등)에서 채팅을 실행하고 OpenAI에서 임베딩을 실행하세요. 모든 OpenAI 호환 임베딩 엔드포인트가 작동합니다.
새 파일은 수집될 때 자동으로 임베딩됩니다. 이미 수집한 그래프에 대한 인덱스를 구축하려면 일회성 재인덱싱을 실행하세요:
cortex reindex # all projects
cortex reindex my-app # a single project
명령
| 명령 | 설명 |
|---|---|
cortex init | 대화형 설정 마법사 |
cortex doctor | 구성, 제공자, 프로젝트, 비밀 및 데이터베이스 유효성 검사 |
cortex projects add/list/remove/show | 등록된 프로젝트 관리 |
cortex serve | 웹 대시보드 + API + 파일 감시자 (포트 3710) |
cortex watch [project] | CLI 전용 파일 감시자 |
cortex ingest <file-or-glob> | 일회성 파일 수집 (라이브 피드와 별도) |
cortex reindex [project] | 기존 엔티티에 대한 의미론적(임베딩) 검색 인덱스 재구축 |
cortex query <question> | 인용이 포함된 자연어 쿼리 |
cortex find <term> | 이름으로 엔티티 찾기 |
cortex status | 그래프 통계, 비용, 제공자 상태 |
cortex costs | 상세 비용 분석 |
cortex contradictions | 활성 모순 나열 |
cortex resolve <id> | 모순 해결 |
cortex models list/pull/test/info | Ollama 모델 관리 |
cortex mcp | Claude Code용 MCP 서버 시작 |
cortex report | 수집 후 요약 |
cortex privacy set/list | 디렉터리 개인 정보 설정 |
cortex config list/get/set/validate | 구성 읽기/쓰기 |
cortex config exclude add/remove/list | 파일/디렉터리 제외 관리 |
cortex stop / cortex restart | 실행 중인 감시/제공 프로세스 관리 |
cortex db | 데이터베이스 작업 |
전체 CLI 참조: docs/cli-reference.md
웹 대시보드
cortex serve를 실행하여 http://localhost:3710에서 전체 웹 대시보드를 엽니다:
- 대시보드 홈 — 그래프 통계, 최근 활동, 엔티티 유형 분석
- 지식 그래프 — 클러스터링이 있는 대화형 D3-force 그래프, 클릭하여 탐색
- 라이브 피드 — WebSocket을 통한 실시간 파일 변경 및 엔티티 추출 이벤트 (
cortex serve에서만) - 쿼리 탐색기 — 스트리밍 응답이 있는 자연어 쿼리
- 모순 해결기 — 충돌하는 결정 검토 및 해결
원격 배포
로컬호스트를 넘어 액세스하려면 모든 인터페이스에 바인딩하고 Cortex를 리버스 프록시 뒤에 두세요:
cortex serve --host 0.0.0.0
nginx 구성 예시 — 기본 인증으로 /api/ 및 /ws 보호; 인증 없이 정적 자산 제공 (대시보드가 베어러 토큰을 HTML에 주입함):
location /api/ {
auth_basic "Cortex";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:3710;
proxy_set_header Authorization "Bearer $CORTEX_TOKEN";
}
location /ws {
auth_basic "Cortex";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:3710;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
location / {
auth_basic off;
proxy_pass http://127.0.0.1:3710;
}
구성에서 CORTEX_SERVER_AUTH_TOKEN 또는 server.auth.token을 설정하세요. 인증이 활성화되면 Cortex는 API 및 WebSocket 호출이 자동으로 인증되도록 토큰을 대시보드 HTML에 주입합니다.
MCP 서버 (Claude Code 통합)
Cortex에는 Claude Code가 지식 그래프를 직접 쿼리할 수 있도록 MCP 서버가 포함되어 있습니다:
claude mcp add cortex --scope user -- npx @gzoo/cortex mcp
이를 통해 Claude Code에 12가지 도구가 제공됩니다:
| 도구 | 설명 |
|---|---|
cortex_ask | 프로젝트에 대한 자연어 질문 |
get_status | 시스템 상태 및 그래프 통계 |
list_projects | 등록된 프로젝트 나열 |
find_entity | 이름으로 엔티티 조회 |
query_cortex | 구조화된 지식 그래프 쿼리 |
get_contradictions | 감지된 모순 나열 |
resolve_contradiction | 모순 해결 |
search_entities | 필터로 엔티티 검색 |
ingest_file | 파일 수집 트리거 |
add_project | 새 프로젝트 등록 |
remove_project | 프로젝트 등록 취소 |
session_brief | 현재 세션에 대한 컨텍스트 요약 |
아키텍처
8개의 패키지가 있는 모노레포:
- @cortex/core — 유형, EventBus, 구성 로더, 오류 클래스
- @cortex/ingest — 파일 파서 (tree-sitter + remark), 청커, 감시자, 파이프라인
- @cortex/graph — SQLite 저장소, LanceDB 벡터, 쿼리 엔진
- @cortex/llm — Anthropic/Gemini/OpenAI 호환/Ollama 제공자, 라우터, 프롬프트, 캐시
- @cortex/cli — Commander.js CLI
- @cortex/mcp — 모델 컨텍스트 프로토콜 서버 (stdio 전송, 12개 도구)
- @cortex/server — Express REST API + WebSocket 릴레이
- @cortex/web — React + Vite + D3 웹 대시보드
아키텍처 문서: docs/
개인 정보 보호 및 보안
restricted으로 분류된 파일은 클라우드 LLM으로 절대 전송되지 않습니다- 민감한 파일(.env, .pem, .key)은 자동 감지되어 차단됩니다
- API 키 비밀은 클라우드 전송 전에 스캔 및 편집됩니다
- 모든 데이터는
~/.cortex/에 로컬로 저장됩니다 — 외부로 전송되지 않음
전체 보안 아키텍처: docs/security.md
사용된 기술
- SQLite via better-sqlite3 — 엔티티 및 관계 저장소
- LanceDB — 시맨틱 검색을 위한 벡터 임베딩
- Anthropic Claude — 클라우드 LLM 제공자
- Google Gemini — 클라우드 LLM 제공자 (OpenAI 호환 API 경유)
- DeepSeek — 클라우드 LLM 제공자 (추론 + 채팅)
- Groq — 빠른 클라우드 추론
- Ollama — 로컬 LLM 추론
- tree-sitter — 언어 인식 파일 파싱
- Chokidar — 크로스 플랫폼 파일 감시
- Commander.js — CLI 프레임워크
- React + Vite — 웹 대시보드
- D3 — 지식 그래프 시각화
기여하기
가이드라인은 CONTRIBUTING.md를 참조하세요.
라이선스
MIT — LICENSE 참조
소개
GZOO에서 제작 — AI 기반 비즈니스 자동화 플랫폼입니다.
Cortex는 여러 클라이언트 프로젝트 전반에서 컨텍스트를 유지하기 위한 내부 도구로 시작되었습니다. 하나 이상의 작업을 하는 모든 개발자는 컨텍스트를 잃게 마련이며, 자동 파일 감시 + 지식 그래프 + 자연어 쿼리라는 이 접근 방식이 이를 해결하는 올바른 방법이라고 생각하여 오픈소스로 공개했습니다.