GZOO Cortex

개발자를 위한 로컬 우선 지식 그래프입니다. 프로젝트 파일을 감시하고, LLM을 사용하여 엔티티와 관계를 추출하며, 모든 프로젝트에 걸쳐 자연어로 쿼리할 수 있게 해줍니다.

“내가 프로젝트 전반에 걸쳐 어떤 아키텍처 결정을 내렸지?”

Cortex는 README, TypeScript 파일, 설정 파일 및 대화 내보내기 파일에서 결정을 찾아내고, 출처 인용과 함께 답변을 종합합니다.

왜 필요한가요?

당신은 여러 프로젝트에서 작업합니다. 결정 사항, 패턴, 컨텍스트는 수백 개의 파일에 흩어져 있습니다. 3개월 전에 무엇을 결정했는지 잊어버립니다. 다른 저장소에서 이미 해결한 문제를 다시 해결합니다.

Cortex는 프로젝트 디렉토리를 감시하고, 지식을 자동으로 추출하며, 필요할 때 다시 제공합니다.

Related MCP server: agentmako

주요 기능

• 감시: 프로젝트 파일(md, ts, js, json, yaml)의 변경 사항을 감시합니다.

• 추출: 엔티티(결정, 패턴, 컴포넌트, 의존성, 제약 조건, 작업 항목)를 추출합니다.

• 추론: 프로젝트 간 엔티티 간의 관계를 추론합니다.

• 감지: 결정 사항이 충돌할 때 모순을 감지합니다.

• 쿼리: 출처 인용과 함께 자연어로 쿼리합니다.

• 라우팅: 클라우드 LLM과 로컬 LLM 간의 지능적인 라우팅을 수행합니다.

• 개인정보 보호: 제한된 프로젝트는 절대 로컬 머신을 벗어나지 않습니다.

• 웹 대시보드: 지식 그래프 시각화, 라이브 피드, 쿼리 탐색기를 제공합니다.

• MCP 서버: Claude Code와의 직접적인 통합을 지원합니다.

빠른 시작

1. 설치

npm install -g @gzoo/cortex

또는 소스에서 설치:

git clone https://github.com/gzoonet/cortex.git
cd cortex
npm install && npm run build && npm link

2. 설정

대화형 마법사를 실행하세요:

cortex init

다음 과정을 안내합니다:

• LLM 제공자 — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter 또는 Ollama(로컬)

• API 키 — ~/.cortex/.env에 안전하게 저장됨

• 라우팅 모드 — 클라우드 우선, 하이브리드, 로컬 우선 또는 로컬 전용

• 감시 디렉토리 — Cortex가 모니터링할 디렉토리

• 예산 제한 — 월간 LLM 지출 한도

설정은 ~/.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 watch                               # start watching for changes
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는 기본적으로 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는 모든 파일 변경 시 파이프라인을 실행합니다:

1. 파싱 — 파일 콘텐츠는 언어 인식 파서(코드용 tree-sitter, 마크다운용 remark)에 의해 청크로 나뉩니다.

2. 추출 — LLM이 엔티티(결정, 컴포넌트, 패턴 등)를 식별합니다.

3. 관계 설정 — LLM이 새로운 엔티티와 기존 엔티티 간의 관계를 추론합니다.

4. 감지 — 모순과 중복이 자동으로 플래그 지정됩니다.

5. 저장 — 엔티티, 관계 및 벡터가 SQLite + LanceDB에 저장됩니다.

6. 쿼리 — 자연어 쿼리가 그래프를 검색하고 답변을 종합합니다.

모든 데이터는 ~/.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 등) — 완전 로컬, 클라우드 불필요

라우팅 모드

하이브리드 모드는 대량 작업(엔티티 추출, 순위 지정)을 Ollama로 라우팅하고, 추론이 많이 필요한 작업(관계 추론, 쿼리)을 클라우드 제공자로 라우팅합니다.

요구 사항

• Node.js 20 이상

• 클라우드 모드를 위한 LLM API 키 — Anthropic, Google Gemini, DeepSeek, Groq 또는 모든 OpenAI 호환 제공자

• Ollama (하이브리드/로컬 모드용) — 설치

설정

모든 설정은 ~/.cortex/cortex.config.json에 있습니다. API 키는 ~/.cortex/.env에 있습니다.

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

전체 설정 참조: docs/configuration.md

명령어

전체 CLI 참조: docs/cli-reference.md

웹 대시보드

cortex serve를 실행하여 http://localhost:3710에서 전체 웹 대시보드를 엽니다:

• 대시보드 홈 — 그래프 통계, 최근 활동, 엔티티 유형 분석

• 지식 그래프 — 클러스터링이 포함된 대화형 D3-force 그래프, 클릭하여 탐색

• 라이브 피드 — WebSocket을 통한 실시간 파일 변경 및 엔티티 추출 이벤트

• 쿼리 탐색기 — 스트리밍 응답이 포함된 자연어 쿼리

• 모순 해결사 — 충돌하는 결정 검토 및 해결

MCP 서버 (Claude Code 통합)

Cortex는 Claude Code가 지식 그래프를 직접 쿼리할 수 있도록 MCP 서버를 포함합니다:

claude mcp add cortex --scope user -- npx @gzoo/cortex mcp

이것은 Claude Code에 12가지 도구를 제공합니다:

아키텍처

8개의 패키지로 구성된 모노레포:

• @cortex/core — 타입, EventBus, 설정 로더, 오류 클래스

• @cortex/ingest — 파일 파서(tree-sitter + remark), 청커, 감시자, 파이프라인

• @cortex/graph — SQLite 저장소, LanceDB 벡터, 쿼리 엔진

• @cortex/llm — Anthropic/Gemini/OpenAI 호환/Ollama 제공자, 라우터, 프롬프트, 캐시

• @cortex/cli — 18개 명령어가 포함된 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 키 비밀은 클라우드 전송 전에 스캔되고 수정(redacted)됩니다.

• 모든 데이터는 ~/.cortex/에 로컬로 저장됩니다 — 외부로 데이터를 보내지 않습니다.

전체 보안 아키텍처: docs/security.md

사용된 기술

• SQLite (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는 여러 클라이언트 프로젝트 전반의 컨텍스트를 유지하기 위한 내부 도구로 시작되었습니다. 하나 이상의 프로젝트를 작업하는 모든 개발자가 컨텍스트를 잃어버린다는 점을 깨닫고, 자동 파일 감시 + 지식 그래프 + 자연어 쿼리라는 이 접근 방식이 문제를 해결하는 올바른 방법이라고 생각하여 오픈 소스로 공개했습니다.