AiDex
npm version
MIT License
Node.js 20+
MCP Server
GitHub Discussions
AI 코딩 에이전트를 위한 영구적인 두뇌입니다.
AiDex는 메모리(memory), 시맨틱 검색(semantic search), 라이브 텔레메트리(live telemetry)를 제공하는 MCP 서버입니다. 이는 로컬 우선(local-first)이며 모델에 구애받지 않습니다(model-agnostic). Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot 등 모든 MCP 호환 AI 비서와 작동합니다.
세 가지 기둥 (Three Pillars)
🧠 메모리 (Memory) — 작업(tasks), 메모(notes), 세션 노트는 모든 채팅을 거쳐도 유지됩니다. 자동 기록된 히스토리, 예약된 작업, 크로스-세션 연속성까지 제공합니다. 사용자의 AI는 오늘 무엇이 중요했는지 내일 알게 됩니다.
🔍 검색 (Search) — 세 가지 모드를 지원합니다: exact(식별자), semantic(개념), hybrid(두 방식의 RRF 융합). 코드, 문서 및 작업 공간 항목을 하나의 순위로 임베딩(embeddings)합니다. 크로스-프로젝트 검색이 가능하여 모든 저장소(repo)를 단일 질의로 처리할 수 있습니다. 선택적 LLM 계층은 비영어권 질의를 번역하고 결과를 재순위화(reranks)합니다.
🌐 텔레메트리 (Telemetry) — LogHub는 HTTP를 통해 어떤 앱에서든 라이브 로그를 수신합니다(SDK 불필요). AI가 단순히 코드가 '무엇이라고 말하는지'가 아니라, 실제로 '어떻게 작동하는지'를 관찰할 수 있습니다. Viewer에 실시간 스트리밍됩니다.
<details>
<summary><strong >그리고 네, 여전히 grep보다 50배 더 토큰 효율적입니다.</strong></summary>
AiDex Demo - grep vs aidex
| AiDex 없이 | AiDex 사용 시 |
|---|
PlayerHealth 찾기 | Grep → 40개 파일에서 200회 히트 → 5개 파일 읽음 → 2,000+ 토큰 | 1개의 질의 → 3개의 정확한 위치 → ~50 토큰 |
| ... | | |
| AiDex Demo GIF | | |
</details>
| 카테고리 | 도구 | 기능 |
|---|
| 시맨틱 검색 🆕 | search, settings | 코드, 문서 및 작업 공간에 대한 하이브리드/시맨틱/정확한 검색. 설정(Settings) 탭에서 임베딩 + LLM 계층 구성 가능 |
| ... | | |
| 14개 언어 — C#, TypeScript, JavaScript, Rust, Python, C, C++, Java, Go, PHP, Ruby, HCL/Terraform, Kotlin, Swift — 그리고 Astro 프론트매터(frontmatter)까지 지원합니다. | | |
<details>
<summary><strong >간편 예제(Quick Examples)</strong> — 작동하는 것을 확인해 보세요</summary>
# "PlayerHealth"가 정의된 위치 찾기 — 호출 1회, 약 50 토큰
aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156
...
</details>
목차 (Table of Contents)
의미론적 검색 및 LLM 계층 (Semantic Search & LLM Layer)
v2.0에서는 로컬에서 실행되는 임베딩(embeddings)을 통해 의미론적 검색 기능을 추가했습니다. 이제 AI는 정확한 식별자(identifier)를 알지 못해도 함수를 찾을 수 있습니다.
세 가지 모드 — 질문에 맞는 도구 선택하기
| 모드 | 기능 설명 | 사용 시점 |
|---|
exact | 식별자 일치 (aidex_query와 동일) | 이름(명칭)을 알고 있을 때. PlayerHealth → 3개 결과 |
| ... | | |
무엇이 임베딩되는가 (What gets embedded)
- 코드(Code) — 모든 메서드와 타입, 3단계 청킹(three-tier chunking) (시그니처 + 문서 주석 + 가중치 식별자 집합)
- 문서(Docs) — 마크다운 섹션 (README, CHANGELOG, docs/, plan 파일), 헤딩 경계에서 분할됨
- 작업 공간(Workspace) — 태스크(tasks), 태스크 로그(task logs), 세션 노트(session notes), 보관된 노트 기록
하나의 순위로 모든 종류를 포괄합니다. "외부 프로그램에서 로그를 작성하는 방법"과 같은 쿼리는 먼저 README의 ## Log Hub 섹션을, 그 다음 commands/log.ts에 있는 log 메서드를, 그리고 관련 작업을 표시합니다.
설정 (Setup)
aidex_init({ path: ".", embeddings: true })
...
또는 Viewer의 설정(Settings) 탭을 사용합니다 (aidex_settings({ path: ".", open: true })) — 임베딩, LLM 제공업체(provider), 모델 및 개인 정보 보호 스위치에 대한 토글이 있습니다.
선택적 LLM 레이어 (Optional LLM layer)
Anthropic / OpenAI / OpenRouter / Ollama / HuggingFace API 키가 구성되면 AiDex는 다음을 수행할 수 있습니다:
- 번역: 비영어 쿼리 번역 → "wie speichere ich Logs lokal"은 올바른 코드를 찾습니다.
- 확장: 모호한 쿼리를 2~4개의 구체적인 하위 쿼리로 확장합니다 (RRF-merged).
- 재순위화(Rerank): 상위 N개 검색 후보에 대한 재순위화를 수행합니다.
개인 정보 보호 스위치 llm_send_code는 기본적으로 꺼짐(off) 상태입니다. 오직 사용자의 실제 쿼리와 메타데이터(경로, 이름, 앵커)만 전송됩니다. 코드 본문은 로컬에 유지됩니다. 프로젝트별로 Settings에서 쉽게 확인할 수 있습니다.
Local-first: 순수 임베딩만을 사용하여 완전히 오프라인으로 작동합니다. LLM 레이어는 선택 사항이며, 절대 필수적이지 않습니다.
문제점 (The Problem)
AI 비서가 코드를 검색할 때마다 다음을 수행합니다:
- Grep(grep): 수천 개의 파일을 탐색 → 수백 개의 결과가 컨텍스트를 범람시킵니다.
- 읽기: 구조를 이해하기 위해 파일 하나하나를 읽습니다 → 더 많은 컨텍스트 소모됩니다.
- 망각: 세션이 끝나면 모든 것을 잊어버립니다 → 처음부터 반복해야 합니다.
"X는 어디에 정의되어 있나요?"라는 단 하나의 질문이 2,000개 이상의 토큰을 소모할 수 있습니다. 이것을 10번 반복하면 내비게이션만으로 컨텍스트의 절반을 태우게 됩니다.
해결책 (The Solution)
한 번 인덱싱하고 영원히 쿼리합니다:
# 이전 방식: grep이 컨텍스트를 범람시킴
AI: grep "PlayerHealth" → 40개 파일에서 200건의 히트
AI: File1.cs, File2.cs, File3.cs... 파일을 읽음
...
결과: 코드 탐색에 사용되는 컨텍스트가 50~80% 감소합니다.
왜 단순히 Grep을 사용하지 않는가?
| Grep/Ripgrep | AiDex |
|---|
| Context 사용량 | 검색당 2000개 이상의 토큰 | 약 50 토큰 |
| ... | | |
grep의 실제 비용: 모든 grep 결과에는 주변 컨텍스트(context)가 포함됩니다. 대규모 프로젝트에서 User를 검색하면 수백 개의 히트(hits)를 얻게 됩니다. 여기에는 주석, 문자열, 부분 일치 등이 포함됩니다. 사용자의 AI는 이 모든 것을 읽으면서 노이즈에 컨텍스트 토큰을 소모합니다.
AiDex는 식별자(identifiers)를 인덱싱합니다: Tree-sitter를 사용하여 코드를 실제로 구문 분석(parse)합니다. User를 검색하면 "user"라는 단어를 언급하는 모든 주석이 아니라, 클래스 정의, 메서드 매개변수, 변수 선언 등을 얻게 됩니다.
작동 방식 (How It Works)
-
프로젝트를 한 번 인덱싱합니다 (~파일 1000개당 1초 소요)
aidex_init({ path: "/path/to/project" })
-
grep을 사용하는 대신 AI가 인덱스를 검색합니다
aidex_query({ term: "Calculate", mode: "starts_with" })
→ "Calculate"로 시작하는 모든 함수 + 정확한 라인 번호
...
3. **전체 파일을 읽지 않고 파일 개요를 얻습니다**
aidex_signature({ file: "src/Engine.cs" })
→ 모든 클래스, 메서드 및 해당 시그니처(signatures)
인덱스는 `.aidex/index.db` (SQLite)에 저장됩니다. 빠르고, 이식성이 뛰어나며, 외부 종속성(dependencies)이 없습니다.
## 기능 (Features)
- **Tree-sitter 구문 분석**: 정규 표현식(regex)이 아닌 실제 코드 구문 분석 — 식별자를 인덱싱하고 키워드 및 노이즈를 무시합니다.
- **검색당 약 50 토큰**: grep 사용 시 2000개 이상의 토큰 소모 대비 — AI가 실제 작업을 위해 컨텍스트를 유지할 수 있습니다.
- **영구 인덱스 (Persistent Index)**: 세션 간에도 살아남습니다 — 재스캔(re-scanning)이나 재읽기(re-reading)가 필요 없습니다.
- **증분 업데이트 (Incremental Updates)**: 전체 프로젝트가 아닌 변경된 단일 파일만 다시 인덱싱합니다.
- **시간 기반 필터링**: 지난 한 시간, 하루 또는 일주일 동안 변경된 내용을 찾을 수 있습니다.
- **자동 정리 (Auto-Cleanup)**: 제외된 파일(예: 빌드 출력물)은 인덱스에서 자동으로 제거됩니다.
- **제로 종속성 (Zero Dependencies)**: WAL 모드의 SQLite를 사용합니다 — 단일 파일, 빠르고 이식성이 뛰어납니다.
## 지원 언어 (Supported Languages)
| Language | Extensions |
|----------|------------|
| C# | `.cs` |
| ... |
## 빠른 시작 (Quick Start)
### 전제 조건 (Prerequisites)
- **Node.js ≥ 20** (버전 확인: `node --version`)
- macOS: `brew install node` 또는 `nvm install 20 && nvm use 20`
- Linux: 패키지 관리자를 사용하거나 [nvm](https://github.com/nvm-sh/nvm)을 이용하세요.
- Windows: [nodejs.org](https://nodejs.org/)를 방문하세요.
- `nvm`을 사용하는 경우, 저장소에는 `.nvmrc` 파일이 포함되어 있습니다 — `nvm use`가 적절한 버전을 자동으로 선택합니다.
### 1. 설치 (Install)
```bash
npm install -g aidex-mcp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
설치 완료입니다. 설정은 설치 후 자동으로 실행됩니다 — 사용자가 설치한 AI 클라이언트(Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot)를 감지하고 AiDex를 MCP 서버로 등록합니다. 또한 AI의 설정 파일(~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md)에 사용 방법 지침을 추가합니다.
수동으로 설정을 다시 실행하려면: aidex setup | 등록 해제하려면: aidex unsetup | 자동 설정 건너뛰려면: AIDEX_NO_SETUP=1 npm install -g aidex-mcp
2. 또는 AI 어시스턴트와 수동으로 등록하기 (Register manually with your AI assistant)
Claude Code용 (~/.claude/settings.json 또는 ~/.claude.json):
{
"mcpServers": {
"aidex": {
...
Claude Desktop용 (Windows의 %APPDATA%/Claude/claude_desktop_config.json):
{
"mcpServers": {
"aidex": {
...
참고: aidex와 aidex-mcp 모두 명령어 이름으로 작동합니다.
중요: 설정 파일의 서버 이름이 MCP 도구 접두사를 결정합니다. 위에 표시된 대로 `
AI의 지침에 추가하세요 (예: Claude Code의 경우 ~/.claude/CLAUDE.md, 또는 사용 중인 AI 클라이언트의 해당 파일). 이렇게 하면 AI에게 grep 대신 언제, 어떻게 AiDex를 사용할지 알려줍니다:
## AiDex - 영구 코드 인덱스 (Persistent Code Index) (MCP Server)
AiDex는 미리 구축된 인덱스를 통해 빠르고 정확한 코드 검색을 제공합니다.
...
코드 검색을 해야 할까요?
├── .aidex/ 존재 → 중지! 대신 AiDex를 사용하세요.
├── .aidex/ 누락 → aidex_init 실행 (질문하지 마세요), 그 후 AiDex를 사용하세요.
└── Config/Logs/Text → Grep/Read가 괜찮습니다.
.aidex/가 존재할 때는 절대 이렇게 하지 마세요:
- ❌
Grep pattern="functionName" → ✅ aidex_query term="functionName"
...
```python
aidex_note({ path: ".", note: "Test the fix after restart" }) # 작성 (Write)
aidex_note({ path: ".", note: "Also check edge cases", append: true }) # 추가 (Append)
aidex_note({ path: "." }) # 읽기 (Read)
aidex_note({ path: ".", search: "parser" }) # 검색 기록 (Search history)
aidex_note({ path: ".", clear: true }) # 지우기 (Clear)
- 세션 종료 전: 다음 단계를 기록하는 메모를 자동으로 남깁니다.
- 사용자가 "다음 세션을 위해 기억해 줘: ..."라고 말하면 즉시 작성합니다.
...
aidex_task({ path: ".", action: "create", title: "Fix bug", priority: 1, tags: "bug" })
aidex_task({ path: ".", action: "update", id: 1, status: "done" })
aidex_task({ path: ".", action: "log", id: 1, note: "Root cause found" })
aidex_tasks({ path: ".", status: "active" })
aidex_task({ path: ".", action: "create", title: "Check PR status", due: "3d", interval: "3d", task_action: "gh pr list" })
우선순위 (Priority): 1=높음(high), 2=중간(medium), 3=낮음(low) | 상태 (Status): backlog → active → done | cancelled
전역 검색 (Global Search) (모든 프로젝트에 걸쳐)
...
### 스크린샷
```javascript
aidex_global_init({ path: "/path/to/all/repos" }) # 스캔 및 등록
aidex_global_init({ path: "...", index_unindexed: true }) # 소규모 프로젝트 자동 인덱싱 추가
aidex_global_query({ term: "TransparentWindow", mode: "contains" }) # 모든 곳에서 검색
aidex_global_signatures({ term: "Render", kind: "method" }) # 모든 곳의 메서드 찾기
aidex_global_status({ sort: "recent" }) # 모든 프로젝트 목록 표시
