Mantic.sh

• 시맨틱 재순위화 (Semantic Reranking, 하이브리드 인텔리전스): 휴리스틱(Heuristic) 속도와 신경망 이해력을 결다는 결합합니다. 로컬 임베딩 (transformers.js)을 사용하여 정확한 키워드 일치가 없더라도 "개념적으로 관련 있는" 코드를 찾아냅니다.
  • 사용법: mantic "verify user" --semantic
• 코드 인텔리전스 (Code Intelligence): Tree-sitter를 사용하여 코드베이스 구조를 깊이 있게 이해합니다.
  • 정의로 이동 (Go to Definition): mantic goto UserService를 실행하면 전체 모노레포(Monorepo)에서 정확한 줄 번호를 반환합니다.
  • 참조 찾기 (Find References): mantic references handleLogin은 .gitignore를 준수하며 모든 사용 사례를 찾아냅니다.
• 학습된 컨텍스트 (Learned Context, 팀 메모리): Mantic은 이제 어떤 파일이 이전 쿼리를 해결했는지 기억합니다. 이러한 패턴은 로컬(.mantic/search-patterns.json)에 저장되며, git에 커밋하여 팀 전체에 지식을 공유할 수 있습니다.
• Python 지원: 이제 의존성 그래프(Dependency graph)에서 Python 임포트(Import)에 대한 퍼스트 클래스(First-class) 지원을 포함합니다.
• 보안 및 안정성:
  • 사용자 입력을 위한 정규 표현식 DoS (Regex DoS) 방지.
  • VS Code 확장 프로그램을 위한 커맨드 인젝션 (Command injection) 완화 조치.
  • git이 없는 디렉토리를 위한 안전한 폴백 (Fallback) 기능 (허용 목록에 있는 확장자만 스캔).

성능 업데이트: v1.0.25는 이전 버전보다 약 2배 더 빠르며, Chromium(481K개 파일)을 2초 미만으로 스캔합니다.

481K개 파일(Chromium)에서 테스트되었으며, 멀티 레포(Multi-repo) 정확도 100%를 기록했습니다.

상세한 릴리스 노트는 CHANGELOG를 참조하세요.

목차

• 프로젝트 소개
• 기존 방식 vs Mantic (Proprietary vs Mantic) 비용 분석
• 성능 벤치마크 (Performance Benchmarks)
• 정확도 및 관련성 (Accuracy & Relevance)
• 기능 비교 (Feature Comparison)
• 사용 사례 추천 (Use Case Recommendations)
• 설치 (Installation)
  • CLI 설치 (CLI Installation)
  • MCP 서버 설치 (MCP Server Installation)
• 사용법 (Usage)
• 에이전트 규칙 (Agent Rules)
• 작동 원리 (How It Works)
• 라이선스 (License)

프로젝트 소개 (About the Project)

Mantic은 AI 에이전트(AI agents)를 위해 불필요한 컨텍스트 검색 오버헤드(context retrieval overhead)를 제거하도록 설계된 인프라 계층(infrastructure layer)입니다. 내용을 무차별적으로 읽는 대신 파일 구조와 메타데이터로부터 의도(intent)를 추론하여, 인간의 반응 속도보다 빠른 검색 속도를 구현합니다.

주요 장점 (Key Benefits)

• 속도 (Speed): 대부분의 저장소(repos)에서 검색 시간이 일관되게 500ms 미만이며, 대규모 모노레포(monorepos, 예: Chromium)에서도 4초 미만입니다.
• 효율성 (Efficiency): 읽기 전에 관련 없는 파일을 필터링함으로써 토큰(token) 사용량을 최대 63%까지 줄입니다.
• 개인정보 보호 (Privacy): 데이터 외부 유출(data egress) 없이 완전히 로컬(locally)에서 실행됩니다.

기존 방식 vs Mantic (비용 분석) (Proprietary vs Mantic (Cost Analysis))

하루에 100회의 검색을 수행하는 100명의 개발자 팀(연간 약 300만 회 검색)의 경우:

성능 벤치마크 (Performance Benchmarks)

속도 비교 (실제 쿼리) (Speed Comparison (Real-world queries))

• 대부분의 저장소에서 캐싱(Caching)이 효과적으로 작동합니다 (두 번째 실행 시 4-17% 개선).
• **대규모 저장소 (Chromium)**에서도 완만하지만 일관된 개선을 보여줍니다.
• Mantic은 순수 속도 면에서는 ripgrep/fzf보다 느리지만, 랭킹(ranking)을 우선시합니다.

정확도 및 관련성 분석 (Accuracy & Relevance Analysis)

주요 강점 (Major Strengths)

1. 정확한 경로 매칭 (Exact Path Matching)

• 쿼리 (Query): next.js 내의 "router server"
• Mantic: packages/next/src/server/lib/router-server.ts를 찾음 (점수: 220)
• ripgrep: "router"와 "server"가 각각 언급된 파일들을 찾음 (많은 오탐(false positives) 발생)
• 결과 (Verdict): Mantic은 의도(intent)와 일치하는 정확한 파일을 찾아냈습니다.

2. CamelCase 탐지 (CamelCase Detection)

• 쿼리 (Query): "ScriptController" in chromium
• Mantic: script_controller.h, script_controller.cc 발견 (점수: 200)
• ripgrep: script.*controller와 같은 수동 정규 표현식 (regex) 필요
• 결과 (Verdict): Mantic의 CamelCase 탐지는 **프로덕션 환경에 즉시 적용 가능한 수준 (production-ready)**입니다.

3. 약어를 위한 디렉토리 부스팅 (Directory Boosting for Acronyms)

• 쿼리 (Query): "gpu" in tensorflow
• Mantic: tensorflow/lite/delegates/gpu/ 내의 파일들을 우선순위 지정
• 결과 (Verdict): Mantic은 **구조적 관련성 (structural relevance)**을 정확하게 우선순위화합니다.

4. 경로 시퀀스 매칭 (Path Sequence Matching)

• 쿼리 (Query): "blink renderer core dom" in chromium
• Mantic: third_party/blink/renderer/core/dom/README.md 발견
• 결과 (Verdict): Mantic은 다중 용어 경로 쿼리 (multi-term path queries)를 완벽하게 매칭합니다.

기능 비교 매트릭스 (Feature Comparison Matrix)

유스케이스 추천 (Use Case Recommendations)

최적의 용도 (Best For)

1. AI 에이전트 (AI Agents) (메타데이터를 활용한 문맥 인식 검색)
2. 의도에 따른 파일 찾기 (Finding Files by Intent) ("결제 코드가 어디에 있나요?")
3. 코드 구조 이해 (Understanding Code Structure) (경로 시퀀스 쿼리)
4. 코드 리뷰 (Code Reviews) (영향 범위 분석을 통한 파급 효과(blast radius) 확인)

적합하지 않은 용도 (Not Ideal For)

1. 빠른 텍스트 검색 (Quick Text Searches) ("모든 TODO 찾기" -> ripgrep 사용 권장)
2. 매우 큰 저장소 (Very Large Repos, 100K+ 이상) (속도 트레이드오프: 4초 vs 0.3초)
3. 정확한 문자열 매칭 (Exact String Matching) (ripgrep의 -F 옵션 사용 권장)
4. 대화형 파일 브라우징 (Interactive File Browsing) (fzf 사용 권장)

설치 (Installation)

CLI 설치

빠른 시작 (Quick Start) (설치 불필요):

npx mantic.sh@latest "your search query"

새로운 명령어 (New Commands):

# 시맨틱 검색 (Semantic Search, 신경망 재순위화 (Neural Reranking))
npx mantic.sh@latest "verify user identity" --semantic

...

소스로부터 설치 (From Source):

git clone https://github.com/marcoaapfortes/Mantic.sh.git
cd Mantic.sh
npm install
...

MCP 서버 설치

Mantic은 Claude Desktop, Cursor, VS Code 및 기타 MCP 호환 도구를 위한 MCP (Model Context Protocol) 서버로 작동합니다.

원클릭 설치:

• Cursor에서 설치하기
• VS Code에서 설치하기

수동 설정 (Claud용)

• search_files - 기본 검색 (뉴럴 리랭킹 (neural reranking)을 위한 semantic: true 지원)
• get_definition - 심볼 (symbol)의 정의로 이동
• find_references - 심볼 (symbol)의 사용처 찾기
• get_context - 선제적 컨텍스트를 위한 제로 쿼리 (Zero-query) 모드
• session_start/end - 코딩 세션 관리
• session_record_view - 조회된 파일 추적
• session_list/info - 세션 기록 보기
• analyze_intent - 쿼리 의도 파악

에이전트 규칙 (Agent Rules, Auto-Pilot)

Cursor나 Claude가 Mantic을 자동으로 사용하게 하고 싶으신가요?

1. 에이전트 규칙 (Agent Rules)을 복사합니다.
2. AI 도구의 시스템 프롬프트 (system prompt) 또는 "AI를 위한 규칙 (Rules for AI)" 섹션에 붙여넣습니다.
3. 이제 에이전트가 코드를 작성하기 전에 컨텍스트를 찾기 위해 자동으로 mantic을 사용합니다.

작동 원리

아키텍처 개요 (Architecture Overview)

사용자 쿼리 (User Query)
    ↓
의도 분석기 (Intent Analyzer) (카테고리 분류: UI/backend/auth/etc)
...

핵심 알고리즘 (Core Algorithm) (v1.0.21)

1. 의도 인식 (Intent Recognition): 쿼리를 분석하여 코드 카테고리(예: "auth", "ui")를 결정합니다.
2. 파일 열거 (File Enumeration): 추적 중인 파일에 대해 git ls-files를 사용합니다 (전체 탐색보다 현저히 빠름).
3. 정규화 및 매칭 (Normalization & Matching):
   • CamelCase 탐지: 매칭을 위해 "ScriptController"를 "script controller"로 변환
   • 단어 경계 매칭 (Word-boundary matching): "script"는 "javascript"와 매칭되지 않음
   • 경로 시퀀스 매칭 (Path sequence matching): 다중 용어 쿼리는 연속된 경로 구성 요소와 매칭됨
   • 디렉토리 부스팅 (Directory boosting): 단일 용어 쿼리는 매칭되는 디렉토리 내의 파일에 우선순위를 부여함
4. 구조적 점수 산정 (Structural Scoring): 다음을 기준으로 파일 순위를 매깁니다:
   • 정확한 파일명 매칭: 완벽하게 일치할 경우 +10,000점 부여
   • 경로 관련성 (Path relevance): packages/features/payments는 높은 신호(signal)를 나타냄
   • 파일명 매칭: stripe.service.ts > stripe.txt
   • 비즈니스 로직 인식 (Business logic awareness): .service.ts가 .test.ts보다 높은 가중치 부여
   • 보일러플레이트 페널티 (Boilerplate penalties): index.ts 또는 page.tsx는 낮은 순위 부여
5. 점진적 공개 (Progressive Disclosure): 메타데이터(크기, 토큰, 신뢰도, 타임스탬프)를 계산합니다.
6. 컨텍스트 유지 (Context Carryover): 세션에서 조회된 파일에 +150 부스트를 적용합니다.

학습 (Learning): 향후 쿼리를 위해 성공적인 패턴을 캐싱(Cache)합니다.

설정 (Configuration)

Mantic은 대부분의 프로젝트에서 별도의 설정 없이 즉시 사용할 수 있습니다.

환경 변수 (Environment Variables)

MANTIC_MAX_FILES=5000         # 스캔할 최대 파일 수
MANTIC_TIMEOUT=30000          # 검색 타임아웃 (단위: ms, 기본값: 30000)
MANTIC_IGNORE_PATTERNS=...    # 무시할 사용자 정의 glob 패턴
...

라이선스 (License)

Mantic.sh는 오픈 액세스(Open Access)와 지속 가능한 개발을 모두 지원하기 위해 이중 라이선스 (Dual Licensed) 정책을 채택하고 있습니다.

1. AGPL-3.0 (오픈 소스 및 내부 사용)

적합한 대상: 개인, 내부 비즈니스 도구, 오픈 소스 프로젝트.

• 내부 사용 시 무료 (예: 회사 개발 팀 내에서 Mantic.sh CLI 사용).
• 오픈 소스 사용 시 무료 (다른 AGPL/GPL 프로젝트에 통합).
• 요구 사항: 만약 Mantic.sh(또는 수정된 버전)를 자체 애플리케이션의 일부로 배포하는 경우(예: 독점적인 IDE나 SaaS에 임베딩), 애플리케이션 전체를 AGPL-3.0 라이선스로 오픈 소스화해야 합니다. 호스팅 서비스의 경우, 사용자가 수정된 소스 코드에 접근할 수 있어야 합니다.

2. 상업용 라이선스 (독점 및 임베딩)

적합한 대상: 상업용 IDE, SaaS 플랫폼, 독점 제품.

• Mantic.sh를 독점 소프트웨어에 임베딩 가능 (예: VS Code 포크, AI 에이전트, SaaS 도구).
• 오픈 소스 의무 없음 (소스 코드를 비공개로 유지 가능).
• 지원 및 면책 (Support & Indemnification): 우선 이메일 지원 및 법적 면책 포함.

가격 (Pricing):

• 내부 사용: 무료 (AGPL-3.0 기준).
• 상업적 통합: 가격 문의 필요 (사용량에 따라 연간 $500부터 시작).