Metadata-Version: 2.4
Name: alphavaults-ai
Version: 0.4.0
Summary: Unified knowledge management: Search + Graph + Wiki
Author: Gforce10-design
License-Expression: MIT
Project-URL: Homepage, https://github.com/Gforce10-design/AlphaVaults
Project-URL: Repository, https://github.com/Gforce10-design/AlphaVaults.git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: networkx
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-typescript
Requires-Dist: tree-sitter-javascript
Requires-Dist: tree-sitter-go
Requires-Dist: tree-sitter-rust
Requires-Dist: tree-sitter-java
Requires-Dist: tree-sitter-swift
Requires-Dist: tree-sitter-kotlin
Requires-Dist: tree-sitter-c
Requires-Dist: tree-sitter-cpp
Requires-Dist: tree-sitter-ruby
Requires-Dist: tree-sitter-c-sharp
Requires-Dist: python-docx>=1.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: python-pptx>=0.6.21

<p align="center">
  <h1 align="center">AlphaVaults</h1>
  <p align="center">AI 코딩 도구의 "장기 기억" — 코드베이스를 자동으로 지식 그래프 + 위키 + 검색 인덱스로 변환</p>
</p>

<p align="center">
  <a href="https://pypi.org/project/alphavaults-ai/"><img src="https://img.shields.io/pypi/v/alphavaults-ai?color=blue" alt="PyPI"></a>
  <img src="https://img.shields.io/pypi/pyversions/alphavaults-ai" alt="Python 3.10+">
  <img src="https://img.shields.io/github/license/Gforce10-design/AlphaVaults" alt="MIT License">
</p>

[English](README.en.md) | **한국어**

---

## 왜 AlphaVaults인가?

AI 코딩 도구(Claude Code, Cursor, Copilot 등)는 **세션이 끝나면 맥락을 전부 잊어버립니다.** 새 세션을 열 때마다 "이 프로젝트는 이런 구조고, 이 함수는 이렇게 동작하고..."를 반복 설명해야 합니다. 이건 **시간 낭비이자 토큰 낭비**입니다.

기존에는 이 문제를 해결하기 위해 3개의 도구가 각각 존재했습니다:

| 기존 도구 | 역할 | 한계 |
|-----------|------|------|
| **qmd** | BM25 로컬 검색 | 검색만 가능, 관계 파악 불가 |
| **graphify** | 지식 그래프 생성 | 검색/위키 없음 |
| **llm-wiki-compiler** | 위키 컴파일 | 그래프/검색 없음 |

AlphaVaults는 이 3개의 장점을 **설치 한 줄, 설정 제로**로 통합합니다. [Andrej Karpathy의 LLM Wiki 패턴](https://x.com/karpathy)에서 영감을 받았습니다.

---

## 3-Layer 아키텍처

```
                    질의: "인증은 어떻게 동작하나요?"
                              |
                    +---------v---------+
                    |  1. Search Layer  |  BM25 로컬 검색
                    |  (토큰 소비: 0)   |  한국어/영어/CJK 지원
                    +---------+---------+
                              |
                    +---------v---------+
                    |  2. Graph Layer   |  지식 그래프 탐색
                    |  (토큰 ~100)      |  BFS/DFS 이웃 노드
                    +---------+---------+
                              |
                    +---------v---------+
                    |  3. Wiki Layer    |  커뮤니티 위키 읽기
                    |  (토큰 ~800)      |  Why/How 컨텍스트
                    +---------+---------+
                              |
                        답변 생성
                    (질의당 총 ~900 토큰)
```

| Layer | 역할 | 토큰 소비 | 기술 |
|-------|------|-----------|------|
| **Search** | 키워드 매칭으로 관련 위키 페이지 발견 | 0 (로컬 연산) | BM25 역색인 |
| **Graph** | 매칭된 노드의 관계/이웃 탐색 | ~100 | NetworkX BFS/DFS |
| **Wiki** | 커뮤니티 페이지에서 컨텍스트 추출 | ~800 | 마크다운 위키 |
| **합계** | | **~900** | 원본 직접 읽기 대비 **60배+ 절감** |

---

## 설치

```bash
pip install alphavaults-ai
alphavaults install
```

`alphavaults install`이 자동으로 수행하는 작업:
- 현재 사용 중인 AI 도구 감지 (10개 지원)
- 각 도구별 통합 설정 파일 생성
- Git post-commit hook 설치 (커밋마다 자동 갱신)
- Claude Code `/alphavaults` Skill 등록
- **Auto-context hook 설치** — 모든 질문에 AlphaVaults 컨텍스트 자동 주입 (시스템 레벨)

### 요구사항

- **Python 3.10+**
- LLM 없이도 AST 기반 코드 구조 분석 동작
- 시맨틱 추출 시 로컬 LLM 또는 API 키 필요 (아래 [LLM 설정](#llm-설정) 참고)

---

## 빠른 시작

### 1. 설치 및 초기화

```bash
pip install alphavaults-ai
cd ~/your-project
alphavaults install .    # hooks + 데몬 자동 등록 (5분마다 변경 감지)
```

초기 지식 베이스 구축은 두 가지 방법이 있습니다:

```bash
# 방법 A: 단일 프로젝트만 빌드
alphavaults ingest .

# 방법 B: 여러 프로젝트를 한번에 통합 빌드
alphavaults global ~/projects
```

| 명령어 | 대상 | 용도 |
|--------|------|------|
| `alphavaults ingest .` | 현재 폴더 1개 | 특정 프로젝트만 빠르게 빌드 |
| `alphavaults global <root>` | 하위 모든 프로젝트 | 프로젝트 간 관계까지 통합 빌드 |

> 초기 빌드 이후에는 데몬이 5분마다 변경 사항을 자동 감지하여 업데이트합니다.
> 데몬이 필요 없으면 `alphavaults install . --no-daemon`

#### 루트 폴더 밖의 파일 인덱싱

루트 경로 밖에 있는 파일/폴더도 `alphavaults ingest`로 수동 인덱싱할 수 있습니다:

```bash
# 예: 홈 디렉토리의 설정 스크립트 인덱싱
alphavaults ingest ~/.config/my-tool/

# 예: 다른 경로의 문서 폴더 인덱싱
alphavaults ingest /opt/docs/api-reference/
```

> **주의:** 루트 폴더 밖의 경로는 데몬 자동 감시 대상에 포함되지 않습니다. 해당 파일이 변경되면 `alphavaults ingest`를 다시 실행해야 합니다.

#### 지원하는 문서 포맷

| 포맷 | 상태 | 비고 |
|------|------|------|
| `.md`, `.txt`, `.rst` | ✅ 기본 지원 | — |
| `.pdf` | ✅ 기본 지원 | 시스템에 `pdftotext` 필요 |
| `.docx`, `.xlsx`, `.pptx` | ✅ v0.2.7+ 기본 지원 | Word / Excel / PowerPoint 자동 인식 |

추가 설치 없이 `alphavaults ingest /path/to/문서폴더` 만 실행하면 위 포맷을 전부 자동 추출합니다.

### 2. 사용

```bash
# 3-layer 통합 질의
alphavaults query "인증은 어떻게 동작하나요?"

# DFS 모드 (특정 호출 체인 깊게 추적)
alphavaults query "이 함수의 전체 호출 경로는?" --dfs

# 현재 상태 확인
alphavaults status
```

### Claude Code Skill 사용

```
/alphavaults .
/alphavaults query "파이프라인 동작 방식은?"
```

---

## 동작 원리

```
소스 파일 / URL / PDF / 문서
        |
        v
  [1. Detect]     -- 코드/문서/PDF/이미지 파일 탐색, 14개 마커 파일로 프로젝트 자동 감지
        |
        v
  [2. Extract]    -- 코드: tree-sitter AST (함수, 클래스, import)
        |             문서: 구조 추출 (헤더 계층, 링크, 코드블록) ← LLM 불필요
        |             PDF: 섹션 구조 추출
        v
  [3. Semantic]   -- LLM으로 의미/의도 분석 (선택사항, 코드+문서 모두)
        |
        v
  [4. Build]      -- NetworkX DiGraph 구축, 댕글링 엣지 필터링
        |
        v
  [5. Cluster]    -- 그리디 모듈러리티 커뮤니티 탐지
        |
        v
  [6. Wiki]       -- 커뮤니티별 마크다운 위키 자동 생성 (Obsidian [[wikilinks]] 호환)
        |
        v
  [7. Index]      -- BM25 역색인 구축 (한국어/영어/CJK)
        |
        v
    alphavaults-out/
```

> **참고**: 2단계(Extract)는 입력 유형에 따라 자동 분기합니다. 코드 파일은 AST 분석, 문서/PDF는 구조 추출을 수행합니다. 두 경로 모두 LLM이 필요하지 않으며 토큰 소비 0입니다. 3단계(Semantic)는 LLM이 있을 때만 실행되며, 코드와 문서 모두에 적용됩니다.

### 출력 디렉토리 구조

```
alphavaults-out/
├── graph.json           # 원본 그래프 데이터 (노드 + 엣지)
├── graph.html           # vis.js 인터랙티브 시각화 (브라우저에서 열기)
├── GRAPH_REPORT.md      # 분석 리포트 (God Nodes, Surprising Connections)
├── wiki/
│   ├── INDEX.md         # 위키 진입점 (전체 커뮤니티 목록)
│   ├── *.md             # 커뮤니티별 위키 페이지
│   ├── _concepts.json   # 개념 인덱스 (상호참조용)
│   ├── ingested/        # 외부 자료에서 추출한 지식 페이지
│   └── queries/         # 저장된 질의/답변 기록
├── search_index.json    # BM25 검색 인덱스
└── sources/             # 수집된 외부 자료 (URL, PDF 등)
```

---

## CLI 명령어 레퍼런스

### 핵심 명령어

| 명령어 | 설명 |
|--------|------|
| `alphavaults install` | AI 도구 감지 + 통합 설정 + Git hook + Skill 등록 |
| `alphavaults ingest <path/url>` | 파일/URL/폴더 수집 → 그래프+위키+인덱스 자동 갱신 |
| `alphavaults query "<question>"` | 3-layer 통합 질의 (search → graph → wiki) |
| `alphavaults status` | 현재 그래프/위키/인덱스 상태 표시 |

### 질의 옵션

| 명령어 | 설명 |
|--------|------|
| `alphavaults query "<question>"` | 기본 BFS 모드 (넓은 탐색) |
| `alphavaults query "<question>" --dfs` | DFS 모드 (깊은 호출 체인 추적) |
| `alphavaults query "<question>" --global` | 글로벌 인덱스에서 크로스 프로젝트 검색 |

### 갱신 & 감시

| 명령어 | 설명 |
|--------|------|
| `alphavaults update` | incremental 갱신 (git hook이 자동 호출) |
| `alphavaults watch` | 파일 변경 실시간 감시 (polling 기반) |
| `alphavaults mark-dirty <path>` | 특정 파일을 dirty로 표시 (재추출 대상) |
| `alphavaults flush` | dirty 파일 일괄 처리 |

### 글로벌 모드

| 명령어 | 설명 |
|--------|------|
| `alphavaults global <root>` | 모든 하위 프로젝트 통합 빌드 |
| `alphavaults global <root> --discover` | 프로젝트 목록만 출력 (빌드 안 함) |
| `alphavaults global <root> --daemon` | 빌드 + 데몬 등록 (install에서 이미 등록된 경우 불필요) |

### 데몬 관리

> 데몬은 `alphavaults install` 시 자동 등록됩니다. 아래 명령어로 상태 확인/관리할 수 있습니다.

| 명령어 | 설명 |
|--------|------|
| `alphavaults daemon status` | 데몬 상태 확인 |
| `alphavaults daemon stop` | 데몬 중지 |
| `alphavaults daemon log` | 데몬 로그 확인 |

### 설정

| 명령어 | 설명 |
|--------|------|
| `alphavaults config llm <url>` | LLM 엔드포인트 설정 |
| `alphavaults config auto-approve true/false` | API 호출 자동 승인 설정 |
| `alphavaults config show` | 현재 설정 표시 |
| `alphavaults lint` | 위키 정합성 + 그래프 건강 검사 |
| `alphavaults --version` | 버전 확인 |

### 버전 관리 (v0.3.0+)

`wiki/` 하위 파일이 수정되기 직전 자동으로 `.history/{상대경로}/{YYYY-MM-DD-HHMMSS}.md`에 스냅샷이 저장됩니다. `review apply`와 `review normalize` 경로 모두 훅으로 연결되어 있어 사람이 직접 조작하지 않아도 복구 지점이 쌓입니다.

| 명령어 | 설명 |
|--------|------|
| `alphavaults history list <wiki_path>` | 해당 파일의 스냅샷 목록 (최신순) |
| `alphavaults history restore <wiki_path> --at YYYY-MM-DD-HHMMSS` | 지정 스냅샷으로 롤백 (현재 내용은 자동 스냅샷 후 교체) |
| `alphavaults history prune [--dry-run]` | 보존 정책 적용 (기본 `max_age_days=90`, `max_per_file=20`) |

보존 정책은 `config.json`에서 조정 가능합니다: `history_enabled`, `history_max_age_days`, `history_max_per_file`. `apply_approved` 성공 시 자동 prune이 수행됩니다.

---

## 토큰 절감 벤치마크

### 단일 프로젝트

| 시나리오 | 원본 직접 읽기 | AlphaVaults 질의 | 절감 배수 |
|----------|---------------|----------------|-----------|
| 소규모 (20 파일) | ~15,000 토큰 | ~900 토큰 | **17x** |
| 중규모 (100 파일) | ~60,000 토큰 | ~900 토큰 | **67x** |
| 대규모 (500 파일) | ~300,000 토큰 | ~900 토큰 | **333x** |

### 실제 측정 (AlphaVaults 자체 소스, 24 파일)

| 지표 | 수치 |
|------|------|
| 노드 수 | 271 |
| 엣지 수 | 373 |
| 위키 페이지 | 40 |
| 질의당 토큰 | ~900 |

### 글로벌 모드 (9개 프로젝트 통합)

| 지표 | 수치 |
|------|------|
| 노드 수 | 572 |
| 엣지 수 | 670 |
| 크로스 프로젝트 연결 | 33 |

질의 토큰 버짓은 `--budget` 옵션으로 조정 가능합니다 (기본값: 2000 토큰).

---

## 지원 프로그래밍 언어

tree-sitter 기반 AST 추출을 지원하는 13개 언어:

| 언어 | 언어 | 언어 |
|------|------|------|
| Python | TypeScript | JavaScript |
| Go | Rust | Java |
| Swift | Kotlin | C |
| C++ | Ruby | C# |
| Scala | PHP | Lua |

---

## AI 도구 자동 연동

`alphavaults install` 실행 시 감지된 도구에 맞는 설정 파일을 자동 생성합니다.

| AI 도구 | 생성되는 설정 파일 |
|---------|-------------------|
| **Claude Code** | `CLAUDE.md` + `SKILL.md` |
| **Cursor** | `.cursorrules` |
| **GitHub Copilot** | `.github/copilot-instructions.md` |
| **Windsurf** | `.windsurfrules` |
| **Gemini Code Assist** | `.gemini/styleguide.md` |
| **Cline** | `.clinerules` |
| **Aider** | `CONVENTIONS.md` |
| **AGENTS.md Standard** (OpenAI Codex CLI, Google Antigravity 등) | `AGENTS.md` |
| **Google Gemini CLI** | `GEMINI.md` |
| **Qwen Code** | `QWEN.md` |

---

## LLM 설정

AlphaVaults는 시맨틱 추출(코드의 의도/목적 분석)을 위해 LLM을 사용합니다. **LLM이 없어도 AST 기반 구조 분석은 정상 동작합니다.**

### 자동 감지 순서

로컬 LLM을 우선 탐색하고, 없으면 구독 토큰 또는 API를 사용합니다:

| 우선순위 | LLM | 방식 | 비용 | 사전 동의 |
|----------|-----|------|------|-----------|
| 1 | **Gemma (로컬)** | `localhost:8080` | 무료 | 불필요 |
| 2 | **Ollama (로컬)** | `localhost:11434` | 무료 | 불필요 |
| 3 | **Claude Code Skill** | `/alphavaults` 실행 시 | 구독 토큰 | 불필요 |
| 4 | **Anthropic Claude Haiku** | API 키 | 유료 | **필수** |
| 5 | **OpenAI GPT-4o-mini** | API 키 | 유료 | **필수** |
| 6 | **LLM 없음** | — | 무료 | — |

- **로컬 LLM**: 동의 없이 바로 호출 (무료)
- **Claude Code 구독자**: `/alphavaults` skill로 실행하면 Claude 자체가 추출을 수행합니다. 별도 API 키 없이 구독 토큰만 사용.
- **API 키 사용**: 예상 비용을 표시하고 사용자 동의를 구한 후에만 호출합니다.
- **LLM 없음**: AST 기반 코드 구조 분석은 정상 동작합니다. 시맨틱 추출(문서 의미 분석)만 건너뜁니다.

> **대부분의 사용자는 Claude Code/Cursor/Copilot 구독자입니다.** `/alphavaults` skill로 실행하면 추가 설정 없이 시맨틱 추출이 동작합니다.

```bash
# 일반 LLM 엔드포인트 수동 설정 (OpenAI-compatible)
alphavaults config llm http://localhost:8080

# Ollama 호스트 오버라이드 (WSL → Windows 호스트 Ollama 등)
alphavaults config ollama-host http://172.28.112.1:11434
# OLLAMA_HOST 환경변수도 자동 인식됩니다

# 사용할 모델명 강제 지정 (자동 탐지 결과보다 우선)
alphavaults config llm-model gemma3:e4b
alphavaults config llm-model qwen3:4b

# API 자동 승인 (매번 묻지 않음)
alphavaults config auto-approve true

# 현재 설정 확인
alphavaults config show
```

> **v0.2.9+**: Ollama는 설치된 모델 목록을 자동으로 조회하여 gemma3, gemma, qwen3, qwen 순으로 우선 선택합니다. WSL → Windows 환경에서는 `ollama-host` 또는 `OLLAMA_HOST` 환경변수로 원격 호스트를 지정할 수 있습니다.

---

## 프로젝트 자동 감지

글로벌 모드(`alphavaults global`)에서 하위 프로젝트를 자동 탐색할 때, 다음 14개 마커 파일 중 하나라도 존재하면 프로젝트로 인식합니다:

| 마커 파일 | 생태계 | 마커 파일 | 생태계 |
|-----------|--------|-----------|--------|
| `package.json` | Node.js | `Cargo.toml` | Rust |
| `pyproject.toml` | Python | `go.mod` | Go |
| `setup.py` | Python | `pubspec.yaml` | Flutter/Dart |
| `build.gradle` | Java/Kotlin | `build.gradle.kts` | Kotlin |
| `Podfile` | iOS/macOS | `Gemfile` | Ruby |
| `composer.json` | PHP | `CMakeLists.txt` | C/C++ |
| `Makefile` | 범용 | `CLAUDE.md` | Claude Code |

---

## 크로스 플랫폼 데몬

`alphavaults install`을 실행하면 데몬이 자동 등록됩니다. `alphavaults global <root> --daemon`으로도 등록할 수 있습니다. OS별 네이티브 서비스 매니저를 사용해 5분마다 변경 사항을 자동 감지하고 업데이트합니다.

| OS | 서비스 매니저 | 비고 |
|----|-------------|------|
| **macOS** | launchd (LaunchAgent) | 로그인 시 자동 시작 |
| **Windows** | Task Scheduler | 로그온 트리거 |
| **Linux** | systemd user service | `--user` 모드 |

```bash
# 데몬 상태 확인
alphavaults daemon status

# 데몬 중지
alphavaults daemon stop

# 데몬 로그 확인
alphavaults daemon log
```

---

## 캐시 & Incremental 업데이트

AlphaVaults는 **SHA256 해시 기반 incremental 캐시**를 사용합니다. 파일이 변경되지 않았으면 재처리하지 않습니다.

- Git post-commit hook이 커밋 시 `alphavaults update` 자동 실행
- 변경된 파일만 재추출 → 그래프/위키/인덱스 갱신
- `alphavaults watch`로 실시간 감시도 가능 (polling 기반)

---

## Auto-Context Hook (세션 연속성의 핵심)

AlphaVaults의 가장 중요한 기능입니다. `alphavaults install` 시 **시스템 레벨 hook**이 설치되어, 사용자가 질문할 때마다 AI가 **자동으로** AlphaVaults를 참조합니다.

```
사용자: "텔레그램 봇 영상에 달린 댓글 어떻게 답해?"
  ↓ (시스템이 자동 실행 — AI의 선택이 아님)
  alphavaults query "텔레그램 봇 영상에 달린 댓글 어떻게 답해?" --global
  ↓
  <alphavaults-context> 검색결과 + 그래프 + 위키 </alphavaults-context>
  ↓
AI: 이미 맥락을 받았으므로 정확한 답변
```

- 10자 미만 짧은 메시지("ㅇㅇ", "해")는 자동 skip
- 5초 timeout으로 응답 지연 없음
- `/` 로 시작하는 skill 명령어도 skip

이 hook이 없으면 AI는 CLAUDE.md의 지시를 "자발적으로" 따라야 하는데, 가끔 무시합니다. Hook은 **시스템이 강제**하므로 AI가 까먹을 수 없습니다.

---

## 메모리 통합

글로벌 빌드(`alphavaults global`) 시 Claude Code의 `~/.claude/projects/*/memory/*.md` 파일도 자동으로 검색 인덱스에 포함됩니다. 코드 분석 결과와 프로젝트 메모리가 **하나의 검색 인덱스**로 통합되어, 정보가 어디에 있든 한번에 찾을 수 있습니다.

```
검색: "텔레그램 봇"
  → 코드 분석 결과 (tg_notify.sh 관련 노드)
  → MEMORY.md (커스텀 봇 결정 기록)
  → 위키 페이지 (TTS 파이프라인 연결 관계)
  = 모든 소스 통합
```

---

## 점진적 지식 축적 (Karpathy LLM Wiki 패턴)

[Andrej Karpathy의 LLM Wiki 패턴](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)에서 영감을 받아, AlphaVaults의 위키는 **시간이 지날수록 풍부해집니다.**

### 기존 도구와의 차이

| | 기존 방식 | AlphaVaults |
|---|---|---|
| **위키 생성** | 매번 전체 재생성 | 변경된 부분만 업데이트, 기존 내용 보존 |
| **사용자 메모** | 재생성 시 삭제됨 | `<!-- user-notes -->` 영역은 영구 보존 |
| **외부 자료** | 별도 관리 | 기존 커뮤니티에 자동 분류/병합 |
| **질의 기록** | 사라짐 | `wiki/queries/`에 축적, 검색 가능 |
| **모순 탐지** | 없음 | 3단계 자동 판단 (아래 참고) |

### 지식이 축적되는 흐름

```
1일차: alphavaults ingest . → 코드 분석 → 위키 30페이지 생성
        ↓
2일차: 코드 수정 → 데몬이 자동 감지 → 변경된 3페이지만 업데이트
        ↓
3일차: alphavaults ingest paper.pdf → 기존 "인증" 커뮤니티에 자동 병합
        ↓
4일차: alphavaults query "인증 흐름" --save → 답변이 wiki/queries/에 저장
        ↓
  ...위키가 점점 풍부해짐. 사용자 메모도 보존.
```

### 상호참조

모든 위키 페이지는 `_concepts.json` 인덱스로 연결됩니다. 새 자료가 추가되면 관련 기존 페이지에 자동 백링크가 생성되어, Obsidian에서 Graph View로 전체 지식 구조를 시각화할 수 있습니다.

### 모순 탐지

위키에 같은 개념이 여러 페이지에 등장할 때, `alphavaults lint`가 자동으로 모순을 탐지합니다. 사용자 환경에 따라 3단계로 동작합니다:

| 환경 | 모순 판단 방식 | 정확도 |
|---|---|---|
| **로컬 LLM 있음** (Gemma/Ollama) | LLM이 두 설명이 모순인지 직접 판단 | 높음 |
| **구독형 AI에서 실행** (`/alphavaults lint`) | Claude/Cursor가 직접 판단 | 높음 |
| **둘 다 없음** | 문자열 비교로 의심 모순 보고 | 기본 |

- 로컬 LLM은 무료이므로 동의 없이 바로 사용합니다
- API 키는 lint에서 절대 사용하지 않습니다 (비용 발생 방지)
- 문자열 비교만으로도 "같은 개념, 다른 설명"은 탐지 가능합니다

---

## 사용 예시

### 새 프로젝트에 AlphaVaults 적용

```bash
cd my-project
pip install alphavaults-ai
alphavaults install          # AI 도구 연동 + Git hook
alphavaults ingest .         # 전체 빌드
alphavaults status           # 결과 확인
open alphavaults-out/graph.html  # 브라우저에서 그래프 시각화
```

### 외부 자료 수집

```bash
# 파일 수집
alphavaults ingest docs/architecture.pdf

# URL 수집
alphavaults ingest https://example.com/api-docs

# 디렉토리 일괄 수집
alphavaults ingest ./references/
```

### 글로벌 모드 (여러 프로젝트 통합)

```bash
# 하위 프로젝트 자동 탐색
alphavaults global ~/projects --discover

# 전체 빌드
alphavaults global ~/projects

# 빌드 + 데몬 등록 (install에서 이미 등록된 경우 불필요)
alphavaults global ~/projects --daemon

# 크로스 프로젝트 질의
alphavaults query "어떤 프로젝트에서 인증 모듈을 사용하나?" --global
```

### 위키 정합성 검사

```bash
alphavaults lint
# 위키 페이지의 [[wikilinks]] 유효성 검사
# 그래프의 고아 노드, 순환 참조 탐지
# God Node (과도한 연결) 경고
```

---

## 의존성

| 패키지 | 용도 |
|--------|------|
| `networkx` | 그래프 연산, 커뮤니티 탐지 |
| `tree-sitter` >= 0.23.0 | AST 파싱 엔진 |
| `tree-sitter-python` | Python AST |
| `tree-sitter-typescript` | TypeScript AST |
| `tree-sitter-javascript` | JavaScript AST |
| `tree-sitter-go` | Go AST |
| `tree-sitter-rust` | Rust AST |
| `tree-sitter-java` | Java AST |
| `tree-sitter-swift` | Swift AST |
| `tree-sitter-kotlin` | Kotlin AST |
| `tree-sitter-c` | C AST |
| `tree-sitter-cpp` | C++ AST |
| `tree-sitter-ruby` | Ruby AST |
| `tree-sitter-c-sharp` | C# AST |

---

## 영감을 준 프로젝트

- [Andrej Karpathy의 LLM Wiki 패턴](https://x.com/karpathy) — 코드를 위키로 변환하여 LLM 컨텍스트 효율화
- [graphify](https://github.com/safishamshi/graphify) — 코드베이스 지식 그래프 생성
- [llm-wiki-compiler](https://github.com/nicholaschenai/llm-wiki-compiler) — 지식을 위키로 컴파일
- [qmd](https://github.com/nicholaschenai/qmd) — 로컬 BM25 마크다운 검색

---

## 라이선스

MIT

---

<p align="center">
  <sub>AlphaVaults v0.2.9 | 개발: <a href="https://github.com/Gforce10-design">Gforce10-design</a></sub>
</p>
