cortex-mcp 1.0.0

Making AI Accountable Over Time - MCP server for persistent memory, automatic verification, and evidence-based grounding

Cortex MCP

A Self-Auditing, Context-Controlled LLM System for Surfacing Silent Failures in Long-Horizon Tasks

Cortex는 LLM의 사고 과정(Context)을 생성·유지·검증·제어하는 로컬 기반 Control System입니다.

---

핵심 가치 (3-Zero 원칙)

원칙	의미	목표
Zero-Effort	사용자 개입 최소화	AI가 자동으로 맥락 관리
Zero-Trust	로컬 기반 보안	외부 서버로 데이터 유출 없음
Zero-Loss	맥락 손실 방지	컨텍스트 압축 후에도 완벽 복원

---

주요 기능

Cortex의 모든 기능은 4가지 실패 유형을 해결하기 위해 설계되었습니다:

1. Silent Failure: 틀렸지만 틀렸다는 신호가 없음 → AI 주장 자동 검증
2. Context Drift: 작업 중 방향이 바뀌었는데 감지되지 않음 → Git 브랜치 연동
3. Overconfidence Hallucination: 근거 없이 "완료됨" 주장 → Claim-Evidence 검증
4. Cognitive Overload: 너무 많은 맥락 → 판단 품질 저하 → Smart Context (Lazy Loading)

자세한 내용은 Features Documentation을 참조하세요.

---

설치

PyPI에서 설치

pip install cortex-mcp

소스에서 설치

git clone https://github.com/syab726/cortex.git
cd cortex
pip install -e .

요구사항

• Python 3.11+
• ChromaDB (자동 설치)
• sentence-transformers (자동 설치)

---

빠른 시작

1. MCP Server 시작

python -m cortex_mcp.main

2. Claude Desktop 연동

Claude Desktop 설정 파일(claude_desktop_config.json)에 추가:

{
  "mcpServers": {
    "cortex": {
      "command": "python",
      "args": ["-m", "cortex_mcp.main"],
      "env": {}
    }
  }
}

3. 초기 맥락 스캔

프로젝트에 처음 연결 시 AI가 자동으로 스캔 모드를 물어봅니다:

• FULL: 전체 코드베이스 심층 분석 (복잡한 프로젝트)
• LIGHT: 핵심 파일만 스캔 (소규모 프로젝트)
• NONE: 스캔 건너뛰기 (단순 작업)

4. Dashboard 확인

python -m cortex_mcp.dashboard.server

브라우저에서 http://localhost:8080 접속하여 Usage Analytics 및 Research Data를 확인하세요.

---

문서

기본 문서

• CLAUDE.md - 프로젝트 개요 및 개발 가이드
• CORTEX_MASTER_PLAN.md - 전체 마스터플랜
• structure.md - 기능 체계 재분류

기능 문서

• Features Overview - 5 Pillars 기반 체계적 기능 설명

벤치마크 결과

• Phase Integration Test - Phase 0-7 통합 테스트 (100% 통과)
• Physical Verification Test - 실제 파일 시스템 검증 (100% 통과)
• Reference History Benchmark - 맥락 추천 정확도 (100%)
• RAG Search Benchmark - 로컬 벡터 검색 성능 (100%, 350ms)
• Token Efficiency Benchmark - 토큰 절감율 (73-99%)
• Hallucination Detection Benchmark - Without Cortex: 0% | With Cortex: 72%+ detection (evidence-dependent)

---

성능 요약

지표	목표	실제 달성	상태
맥락 추천 정확도	95%	100%	✅ 초과 달성
토큰 절감율	70%	73-99%	✅ 초과 달성
RAG 검색 정확도	100%	100%	✅ 달성
전체 성공률	80%+	98.69%	✅ 초과 달성

---

기술 스택

구분	기술	목적
언어	Python 3.11+	AI 라이브러리 호환성
통신 표준	MCP (Anthropic SDK)	공식 표준 채택
벡터 DB	ChromaDB	로컬 RAG 인덱스
임베딩	sentence-transformers	외부 API 없이 벡터 생성
클라우드	Google Drive API	환경 간 동기화

---

MCP Tools (47개)

기본 도구 (7개)

Tool	목적
initialize_context	프로젝트 초기 맥락 스캔
create_branch	브랜치 생성
search_context	RAG 검색
update_memory	대화 기록 저장
get_active_summary	맥락 요약 조회
sync_to_cloud	클라우드 백업
sync_from_cloud	클라우드 복원

확장 도구 (40개)

Smart Context, Reference History, Node 관리, Git 연동, 백업, 자동화, 시맨틱 웹, Boundary 등 40개의 추가 도구가 구현되어 있습니다.

전체 도구 목록은 cortex_mcp/tools/cortex_tools.py를 참조하세요.

---

디렉토리 구조

cortex_mcp/
├── main.py                      # MCP Server Entry Point
├── config.py                    # 환경 설정
├── core/                        # 핵심 로직
│   ├── memory_manager.py        # 메모리 관리 (계층 구조)
│   ├── context_manager.py       # Smart Context (압축/해제)
│   ├── reference_history.py     # 참조 이력 시스템
│   ├── rag_engine.py            # Hybrid RAG 검색
│   ├── git_sync.py              # Git 연동
│   ├── backup_manager.py        # 백업/복구/히스토리
│   ├── automation_manager.py    # Plan A/B 자동 전환
│   ├── cloud_sync.py            # Google Drive 동기화
│   └── crypto_utils.py          # E2E 암호화
├── tools/                       # MCP 도구
│   └── cortex_tools.py          # MCP 도구 인터페이스
├── dashboard/                   # Dashboard
│   ├── server.py                # HTTP 서버 (localhost:8080)
│   └── templates/
│       └── index.html           # Dashboard UI
├── tests/                       # 테스트
│   ├── test_integration_full.py # Phase 통합 테스트
│   ├── test_physical_verification.py
│   └── test_hallucination_detection.py
└── docs/                        # 문서
    ├── features.md              # 기능 문서
    └── benchmarks/              # 벤치마크 결과

---

라이센스

현재 30명 1년 무료 베타 테스터 모집 중입니다. 베타 기간 종료 후 유료 전환 예정입니다.

---

GitHub Repository

• URL: https://github.com/syab726/cortex
• Issues: https://github.com/syab726/cortex/issues
• Discussions: https://github.com/syab726/cortex/discussions

---

연락처

질문이나 피드백은 GitHub Issues를 통해 남겨주세요.

---

What Makes Cortex Different

Cortex는 단순한 "기능 많은 툴"이 아닙니다.

Cortex = 사고를 관리하는 시스템

• Creates context — 자동 생성
• Maintains context — 압축·복구
• Structures context — 계층·그래프
• Reuses context — Reference History
• Verifies claims — Evidence 기반
• Controls behavior — 자동 개입
• Surfaces failures — 조기에 가시화

이것이 Cortex가 "대체하기 어려운 이유"입니다.

---

Built with ❤️ for better LLM reliability