giancarloerra/SocratiCode

Enterprise-grade (40m+ LOC) codebase intelligence, zero-setup, local & private Plugin/Skill/Extension or MCP: hybrid semantic search, polyglot dependency graphs, symbol-level impact analysis & call-flow, interactive HTML viewer, cross-project & branch-aware search, DB/API/infra knowledge. 61% less tokens, 84% fewer calls, 37x faster. Cloud in beta.

SocratiCode – 코드베이스 인식 AI 엔진

개요 – SocratiCode는 모든 LLM(Claude, OpenAI, Gemini 등)이 쿼리 시마다 모든 파일을 읽지 않고도 리포지토리의 전체 의미를 이해할 수 있게 해주는 오픈 소스 코드베이스 컨텍스트 엔진입니다. 로컬 인덱스(임베딩 + AST 인식 청크, 의존성 그래프, 심볼 수준의 영향 데이터)를 구축하고 Claude Code, OpenAI Codex, VS Code, Cursor, Gemini CLI 및 기타 호스트에서 사용하는 MCP(Multi-Chat-Protocol) 인터페이스를 통해 제공합니다.

중요성 – 대규모 코드베이스(수천만 줄)를 LLM에 입력하는 것은 토큰 비용, 지연 시간 및 환각 문제로 인해 비용이 많이 듭니다. SocratiCode는 무거운 작업을 미리 계산하여 어시스턴트가 정확한 심볼, 호출 흐름 및 관련 아티팩트(DB 스키마, API 사양, 인프라 구성)를 몇 밀리초 만에 검색할 수 있도록 합니다. 이는 컨텍스트 크기, 토큰 사용량 및 도구 호출을 줄이고, 더 작고 저렴한 모델이 아키텍처 수준의 추론을 수행할 수 있도록 합니다.

핵심 기능(README 설명 기준)

하이브리드 검색 – 의미론적(임베딩) 및 BM25(키워드) 검색을 상호 순위 융합(Reciprocal Rank Fusion)으로 결합합니다.
다국어 의존성 그래프 – 18개 언어를 파싱하고 심볼 수준의 호출 흐름/영향 범위 그래프를 구축하며, 대화형 HTML 탐색기로 시각화합니다.
영향 분석 – 변경 사항이 어떤 함수, 클래스 또는 파일에 영향을 미치는지 추적합니다.
컨텍스트 아티팩트 – DB 스키마, OpenAPI 사양, Terraform/클라우드 구성, 아키텍처 문서 등을 인덱싱하고 검색 가능하게 만듭니다.
제로 구성 시작 – npx socraticode@latest 명령으로 Docker 스택(Qdrant 벡터 DB + 로컬 임베딩용 Ollama)을 자동으로 실행합니다.
자동 증분 인덱싱 – 파일 감시자가 변경될 때마다 인덱스를 업데이트하며, 충돌 시 재개 가능한 체크포인트를 지원합니다.
멀티 리포지토리 / 멀티 브랜치 / 멀티 에이전트 – 단일 인덱스를 여러 AI 에이전트가 동시에 공유할 수 있습니다.
기본 비공개 – 모든 작업이 로컬에서 실행됩니다. 클라우드 임베딩(OpenAI, Google Gemini)이나 외부 Qdrant 인스턴스를 선택하지 않는 한 API 키가 필요하지 않습니다.
클라우드 준비 – SocratiCode Cloud(비공개 베타)는 SSO, 감사 로그, 브랜치 인식 인덱싱 및 VPC/에어갭 배포를 추가하면서도 핵심 엔진은 무료로 유지합니다.
광범위한 호스트 통합 – Claude Code, OpenAI Codex, VS Code(에이전트 플러그인 및 에디터 확장), Cursor, Gemini CLI, Continue, Cline, Zed, OpenCode 및 직접 MCP 모드용 네이티브 플러그인.
벤치마크 성능 – 245만 줄의 VS Code 프로젝트에서 grep 기반 워크플로우(Claude Opus 4.6) 대비 컨텍스트 61% 감소, 도구 호출 84% 감소, 37배 빠른 속도를 기록했습니다.

시작하기(퀵스타트 흐름)

전제 조건 – Node ≥ 18.17, PATH에 npx 포함, Docker 실행 중(기본 Qdrant + Ollama 스택용).
설치 – 가장 간단한 방법은 MCP 호스트를 통하는 것입니다:
```
{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"]
    }
  }
}
```
또는 Claude Code, VS Code, Cursor용 원클릭 배지를 사용하세요(README에 동일한 npx 명령을 트리거하는 배지 링크가 있습니다).
첫 인덱싱 – 채팅에서 어시스턴트에게 “Index this codebase”라고 요청하세요. SocratiCode가 백그라운드에서 실행되어 리포지토리를 감시하고 codebase_update / codebase_watch 명령을 통해 진행 상황을 보고합니다.
사용 – 인덱싱이 완료되면 다음을 수행할 수 있습니다:
- codebase_search { query: "…" } – 하이브리드 의미론적 + BM25 검색.
- codebase_graph { symbol: "MyClass.method" } – 의존성 그래프 보기.
- codebase_impact { symbol: "…" } – 영향 범위 분석 가져오기.
- schema_search, api_spec_search 등 아티팩트 쿼리.
최신 상태 유지 – 엔진은 MCP 서버 시작 시 자동으로 업데이트됩니다(npm @latest). 플러그인/확장 기능은 호스트의 일반적인 확장 업데이트 메커니즘을 통해 업데이트됩니다.

일반적인 워크플로우 예시

User:  Index this codebase.
Assistant (via SocratiCode):  Indexing started… 45 % done.
User:  What function reads the `config.yaml` file?
Assistant:  (runs `codebase_search` → returns `loadConfig` in `src/config.ts`)
User:  Show me the call-flow from `loadConfig`.
Assistant:  (runs `codebase_graph` → displays interactive HTML graph)
User:  Which modules would be affected if I change `Database.connect`?
Assistant:  (runs `codebase_impact` → lists dependent services, tests, docs)

모든 무거운 분석은 로컬에서 수행되며, LLM은 간결한 결과만 받습니다.

구성 하이라이트

임베딩 제공자 – EMBEDDING_PROVIDER는 ollama(기본값, 로컬), openai 또는 google로 설정할 수 있습니다. 환경 변수를 통해 적절한 API 키를 설정하세요.
감시 모드 – SOCRATICODE_WATCHER=off|manual|auto로 자동 파일 감시 업데이트를 제어합니다.
재개 동작 – SOCRATICODE_AUTO_RESUME_PROJECTS / SOCRATICODE_AUTO_RESUME를 통해 여러 리포지토리를 미리 로드할 수 있습니다.
버전 고정 – SOCRATICODE_SPEC을 특정 npm 버전(예: socraticode@1.14.0)으로 설정하여 재시작 시 엔진을 고정할 수 있습니다.
Docker 리소스 – README는 대규모 리포지토리를 위해 Qdrant/Ollama 컨테이너에 CPU/RAM을 할당하는 방법을 설명합니다.

권장 사용자

개발자 – 소스 코드를 외부 서비스에 노출하지 않고 모노레포, 마이크로서비스 아키텍처 또는 코드형 인프라(IaC)에 대해 LLM 어시스턴트(Claude, ChatGPT, Gemini 등)가 추론하기를 원하는 경우.
팀 – AI 기반 내부 DevOps 도구, 코드 리뷰 봇 또는 자동화된 영향 분석 파이프라인을 구축하는 경우.
기업 – 자체 호스팅 및 정책 제어가 가능한 코드 인텔리전스 계층이 필요한 경우(MCP 거버넌스, PII 마스킹, 속도 제한 등은 자매 프로젝트 JanuScope 참조).

라이선스 및 커뮤니티

라이선스: AGPL-3.0(전체 소스 코드 제공, 상업적 사용 시 AGPL 준수 필요).
커뮤니티: 지원을 위한 Discord 서버, 버그/기능 요청을 위한 GitHub Issues, SSO 및 감사 로그가 포함된 관리형 호스팅을 원하는 팀을 위한 비공개 베타 SaaS 서비스(SocratiCode Cloud).

결론

SocratiCode는 리포지토리 전체의 로컬 최신 인덱스를 구축하고 표준 MCP 인터페이스를 통해 강력한 검색, 그래프 및 영향 분석 도구를 노출함으로써 모든 LLM을 코드 인식 어시스턴트로 변환합니다. 제로 구성 및 개인정보 보호를 최우선으로 하는 기업 규모의 배포를 위해 설계되었지만, VS Code 또는 Claude Code 플러그인을 통해 단일 개발자도 쉽게 사용할 수 있습니다.