ory/lumen

Claude는 필요한 것을 찾기 위해 파일 전체를 읽습니다. Lumen은 그에게 지도를 제공합니다.

Lumen은 AI 코딩 에이전트(AI coding agents)를 위한 100% 로컬 시맨틱 코드 검색 엔진 (semantic code search engine)입니다. API 키, 클라우드, 외부 데이터베이스 없이 오직 오픈 소스 임베딩 모델 (embedding models) (Ollama 또는 LM Studio), SQLite, 그리고 사용자의 CPU만을 사용합니다. 단일 정적 바이너리 (static binary)와 사용자의 자체 로컬 임베딩 서버만 있으면 됩니다.

그 결과는 측정 가능하며 재현 가능합니다. 9개의 언어와 실제 GitHub 버그 수정 (bug-fix) 작업에 대한 9번의 벤치마크 (benchmark) 실행 결과, Lumen은 모든 언어에서 비용을 최대 39%까지 절감했습니다. 출력 토큰 (output tokens)은 최대 66% 감소했고, 세션 완료 속도는 최대 53% 빨라졌으며, 모든 작업에서 패치 품질 (patch quality)은 유지되었습니다. 이 모든 결과는 사용자가 직접 실행할 수 있는 투명한 오픈 소스 벤치마크 프레임워크 (benchmark framework)를 통해 검증되었습니다.

Lumen 사용 시	기준점 (Lumen 미사용)
비용 (평균, 버그 수정)	$0.29 (-26%)
시간 (평균, 버그 수정)	125s (-28%)
출력 토큰 (평균)	5,247 (-37%)
JavaScript (marked)	$0.32, 119s (-33%, -53%)
Rust (toml)	$0.38, 204s (-39%, -34%)
PHP (monolog)	$0.14, 34s (-27%, -34%)
TypeScript (commander)	$0.14, 56s (-27%, -33%)
Svelte (chat-ui)	$0.10, 56s (-26%, -31%)
패치 품질	9개 작업 모두에서 유지됨

• 데모 (Demo)
• 빠른 시작 (Quick start)
• 제공 기능 (What you get)
• 작동 원리 (How it works)
• 벤치마크 (Benchmarks)
• 지원 언어 (Supported languages)
• 설정 (Configuration)
• 인덱싱 대상 제어 (Controlling what gets indexed)
• 데이터베이스 위치 (Database location)
• CLI 레퍼런스 (CLI Reference)
• 문제 해결 (Troubleshooting)
• 개발 (Development)

Claude Code가 Prometheus 코드베이스에 대해 질문합니다. Lumen의 시맨틱 검색 (semantic_search)은 파일 전체를 읽지 않고도 관련 코드를 찾아냅니다.

사전 요구 사항 (Prerequisites):

플랫폼 지원: Linux, macOS, Windows. 백그라운드 인덱싱 조율을 위한 파일 잠금 (File locking)은 Unix에서 flock(2)를, Windows에서 LockFileEx (gofrs/flock을 통해)를 사용합니다.

• Ollama가 설치되어 실행 중이어야 하며, 기본 임베딩 모델을 가져옵니다:
  ollama pull ordis/jina-embeddings-v2-base-code

• 다음 중 하나: Claude Code, Cursor, Codex 또는 OpenCode

참고: 설치 방법은 플랫폼마다 다릅니다. Claude Code는 플러그인 마켓플레이스 (plugin marketplace)에서 설치합니다. Codex는 로컬 MCP 서버 (local MCP server)와 네이티브 스킬 발견 (native skill discovery) 기능을 사용합니다. OpenCode는 npm을 통해 설치합니다. Cursor 패키징은 이 저장소 (repository)에 포함되어 있으며, Cursor의 플러그인 배포 워크플로 (plugin distribution workflow)를 사용할 준비가 되어 있습니다.

설치 (Install):

Claude Code

/plugin marketplace add ory/claude-plugins
/plugin install lumen@ory

새로운 Claude 세션을 시작하고 /lumen:doctor를 실행하여 확인하세요.

Cursor

Lumen은 이 저장소에 네이티브 Cursor 플러그인 번들 (native Cursor plugin bundle)을 포함하고 있습니다:

.cursor-plugin/plugin.json - 플러그인 매니페스트 (plugin manifest)
mcp.json - 로컬 lumen MCP 서버 연결 (MCP server wiring)
hooks/hooks-cursor.json - 세션 시작 훅 (SessionStart hook)
skills/ - 공유된 doctor 및 reindex 스킬 (shared doctor and reindex skills)

이 번들을 사용하여 Cursor의 플러그인 설치 또는 배포 워크플로를 사용하세요. 상세 패키징 참고 사항: .cursor-plugin/INSTALL.md

새로운 Cursor 에이전트 세션을 열고 doctor 스킬 또는 Lumen의 semantic_search 도구 (tool)를 사용하도록 요청하여 확인하세요.

Codex

빠른 설치:

https://raw.githubusercontent.com/ory/lumen/refs/heads/main/.codex/INSTALL.md 에서 명령어를 가져와 지침을 따르세요.

수동 설치:

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
git clone https://github.com/ory/lumen.git "$CODEX_HOME/lumen"
mkdir -p "$HOME/.agents/skills"
...

상세 문서: .codex/INSTALL.md

다음으로 확인하세요:

codex mcp get lumen
ls -la "$HOME/.agents/skills/lumen"

OpenCode

opencode.json 파일의 plugin 배열에 @ory/lumen-opencode를 추가하세요:

{
"plugin": ["@ory/lumen-opencode"]
}

상세 문서: .opencode/INSTALL.md

opencode mcp list로 확인하세요.

업데이트 (Updating)

Claude Code - Claude의 플러그인 마켓플레이스를 통해 업데이트
Cursor - 이 저장소 또는 게시된 패키지를 업데이트한 후, Cursor를 통해 번들된 플러그인을 새로고침하거나 재설치
Codex - cd "${CODEX_HOME:-$HOME/.codex}/lumen" && git pull
OpenCode - opencode.json의 버전 고정 (version pin)을 업데이트하고 (예: @ory/lumen-opencode@0.0.29) OpenCode를 재시작

첫 Claude Code 또는 Cursor 세션 시작 시, Lumen은 다음을 수행합니다:

• 최신 GitHub release에서 바이너리(binary)를 자동으로 다운로드합니다.
• Merkle tree 변경 감지(change detection)를 사용하여 백그라운드에서 프로젝트를 인덱싱(indexing)합니다.
• 호스트가 자동으로 사용할 수 있는 semantic_search MCP 도구(tool)를 등록합니다.

Codex 및 OpenCode에서는 첫 번째 semantic_search 호출 시 동일한 바이너리 다운로드 및 인덱스 시딩(index seeding)이 발생합니다.

두 가지 공유 스킬(shared skills)도 사용할 수 있습니다: doctor (상태 점검) 및 reindex (강제 재인덱싱). Claude는 이를 /lumen:doctor 및 /lumen:reindex로 노출하며, 다른 호스트들은 자체적인 스킬 시스템을 통해 동일한 공유 스킬 콘텐츠를 발견합니다.

동일한 semantic_search, health_check, index_status MCP 도구와 공유된 doctor 및 reindex 스킬은 Codex, Cursor, OpenCode 인터페이스를 통해서도 노출됩니다. 첫 번째 semantic_search 호출 시 인덱스가 자동으로 시딩되거나 새로 고쳐집니다.

시맨틱 벡터 검색 (Semantic vector search) — Claude가 키워드 매칭이 아닌 의미를 통해 관련 함수, 타입 및 모듈을 찾습니다.
자동 인덱싱 (Auto-indexing) — 세션 시작 시 인덱싱하며, Merkle tree 차이점 비교(diffing)를 통해 변경된 파일만 다시 처리합니다.
증분 업데이트 (Incremental updates) — 변경된 부분만 재인덱싱합니다. 대규모 코드베이스도 첫 실행 이후에는 몇 초 만에 재인덱싱이 완료됩니다.
12개 언어 제품군 (12 language families) — Go, Python, TypeScript, JavaScript, Svelte, Rust, Ruby, Java, PHP, C/C++, C#, Dart
Git worktree 지원 (Git worktree support) — worktree는 인덱스 데이터를 자동으로 공유합니다. 새로운 worktree는 형제(sibling)의 인덱스로부터 시딩되며 변경된 파일만 재인덱싱하므로, 몇 분이 걸리던 임베딩(embedding) 작업이 몇 초로 단축됩니다.
제로 클라우드 (Zero cloud) — 임베딩은 사용자의 기기에 머무릅니다. 데이터가 네트워크 외부로 나가지 않습니다.
Ollama 및 LM Studio — 두 로컬 임베딩 백엔드(embedding backend) 모두와 작동합니다.

Lumen은 MCP 서버로서 코드베이스와 Claude 사이에 위치합니다. 세션이 시작되면 프로젝트를 탐색하고 파일 해시를 기반으로 **머클 트리 (Merkle tree)**를 구축합니다. 이를 통해 변경된 파일만 다시 청크(re-chunked) 및 임베딩(re-embedded)됩니다. 각 파일은 Go의 네이티브 AST를 사용하거나 다른 언어의 경우 tree-sitter 문법을 사용하여 의미론적 청크(semantic chunks, 함수, 타입, 메서드)로 분할됩니다. 청크는 임베딩되어 SQLite + sqlite-vec에 저장되며, 검색을 위해 코사인 거리(cosine-distance) KNN을 사용합니다.

파일 → 의미론적 청크 → 벡터 임베딩 → SQLite/sqlite-vec → KNN 검색

Claude가 코드를 이해해야 할 때, 전체 파일을 읽는 대신 semantic_search를 호출합니다. 인덱스는 프로젝트 경로와 모델 이름에 따라 키가 지정되어 저장소 외부(~/.local/share/lumen/<hash>/index.db)에 저장됩니다. 서로 다른 모델은 인덱스를 절대 공유하지 않습니다.

Lumen은 bench-swe를 사용하여 평가됩니다. 이는 실제 GitHub 버그 수정 작업에서 Claude를 실행하고 Lumen 사용 여부에 따른 비용, 시간, 출력 토큰 및 패치 품질을 측정하는 SWE-bench 스타일의 하네스(harness)입니다. 모든 결과는 재현 가능합니다. 원본 JSONL 스트림, 패치 차이(patch diffs), 판사 등급(judge ratings)이 이 저장소에 커밋됩니다.

주요 결과 — 9개 언어, 높은 난이도, 실제 GitHub 이슈(ordis/jina-embeddings-v2-base-code, Ollama)에 대해 9회 실행:

언어	비용 절감	시간 절감	출력 토큰 절감	품질
Rust	-39%	-34%	-31% (18K → 12K)	낮음 (둘 다)
JavaScript	-33%	-53%	-66% (14K → 5K)	완벽 (둘 다)
TypeScript	-27%	-33%	-64% (5K → 1.8K)	좋음 (둘 다)
PHP	-27%	-34%	-59% (1.9K → 0.8K)	좋음 (둘 다)
Ruby	-24%	-11%	-9% (6.1K → 5.6K)	좋음 (둘 다)
Python	-20%	-29%	-36% (1.7K → 1.1K)	완벽 (둘 다)
Go	-12%	-9%	-10% (11K → 10K)	좋음 (둘 다)
C++	-8%	-3%	+42% (기능 작업)	좋음 (둘 다)
Svelte	-26%	-31%	-26% (4.0K → 3.0K)	낮음 (둘 다)

테스트된 모든 언어에서 비용이 절감되었습니다. 모든 작업에서 품질이 유지되었으며 — 퇴보(regression)는 전혀 없었습니다. JavaScript와 TypeScript에서 가장 극적인 효율성 향상을 보였습니다: 동일한 품질의 수정 작업을 절반의 시간과 3분의 1 적은 토큰(token)으로 수행했습니다. 두 방식 모두에게 너무 어려운 작업(Rust, Svelte)에서도 Lumen은 실패 비용을 26~39% 절감합니다.

9가지 언어별 심층 분석, 판정 근거(judge rationales) 및 재현 지침은 docs/BENCHMARKS.md를 참조하십시오.

의미론적 청킹(semantic chunking)을 통해 12개의 언어군을 지원합니다 (10개 벤치마크 완료):

언어	파서 (Parser)	확장자 (Extensions)	벤치마크 상태
Go	Native AST	.go	벤치마크 완료: 비용 -12%, 품질 좋음
Python	tree-sitter	.py	벤치마크 완료: 완벽한 품질, 토큰 -36%
TypeScript / TSX	tree-sitter	.ts , .tsx	벤치마크 완료: 토큰 -64%, 시간 -33%
JavaScript / JSX	tree-sitter	.js , .jsx , .mjs	벤치마크 완료: 토큰 -66%, 시간 -53%
Dart	tree-sitter	.dart	벤치마크 완료: 비용 -76%, 토큰 -82%, 시간 -79%
Rust	tree-sitter	.rs	벤치마크 완료: 비용 -39%, 시간 -34%
Ruby	tree-sitter	.rb	벤치마크 완료: 비용 -24%, 시간 -11%
PHP	tree-sitter	.php	벤치마크 완료: 토큰 -59%, 시간 -34%
C / C++	tree-sitter	.c , .h , .cpp , .cc , .cxx , .hpp	벤치마크 완료: 비용 -8% (C++ 기능 작업)
Svelte	tree-sitter	.svelte	벤치마크 완료: 비용 -26%, 시간 -31%
Java	tree-sitter	.java	지원됨
C#	tree-sitter	.cs	지원됨

Go는 가장 정밀한 청크를 위해 네이티브 Go AST 파서를 사용합니다. 다른 모든 언어는 tree-sitter 문법을 사용합니다. 10가지 언어별 벤치마크 심층 분석은 docs/BENCHMARKS.md를 참조하십시오.

모든 설정은 환경 변수(environment variables)를 통해 이루어집니다:

변수 (Variable)	기본값 (Default)	설명 (Description)
LUMEN_EMBED_MODEL	주석 ¹ 참조	임베딩 모델 (Embedding model); 목록에 없는 모델의 경우 LUMEN_EMBED_DIMS와 함께 사용
LUMEN_BACKEND	ollama	임베딩 백엔드 (Embedding backend) (ollama 또는 lmstudio)
OLLAMA_HOST	http://localhost:11434	Ollama 서버 URL
LM_STUDIO_HOST	http://localhost:1234	LM Studio 서버 URL
LUMEN_MAX_CHUNK_TOKENS	512	분할 전 청크(chunk)당 최대 토큰 수
LUMEN_EMBED_DIMS	—	임베딩 차원(embedding dimensions) 재정의 (목록에 없는 모델의 경우 필수)
LUMEN_EMBED_CTX	8192 (목록에 없는 모델의 경우)	컨텍스트 창(context window) 길이 재정의

¹ ordis/jina-embeddings-v2-base-code (Ollama),
nomic-ai/nomic-embed-code-GGUF (LM Studio)

차원(Dimensions)과 컨텍스트 길이(context length)는 모델별로 자동 구성됩니다:

모델 (Model)	백엔드 (Backend)	차원 (Dims)	컨텍스트 (Context)	권장 사항 (Recommended)
ordis/jina-embeddings-v2-base-code	Ollama	768	8192	최적의 기본값 — 비용이 가장 낮고 과잉 검색(over-retrieval) 없음
qwen3-embedding:8b	Ollama	4096	40960	최상의 품질 — 가장 강력한 지배력 (7/9 승리), 인덱싱 속도가 매우 느림
nomic-ai/nomic-embed-code-GGUF	LM Studio	3584	8192	사용 가능 — 품질은 좋으나 TypeScript 과잉 검색으로 인해 비용 상승
qwen3-embedding:4b	Ollama	2560	40960	권장하지 않음 — 비용이 가장 높고 심각한 TypeScript 과잉 검색 발생
nomic-embed-text	Ollama	768	8192	테스트되지 않음
qwen3-embedding:0.6b	Ollama	1024	32768	테스트되지 않음
all-minilm	Ollama	384	512	테스트되지 않음

모델을 전환하면 별도의 인덱스(index)가 자동으로 생성됩니다. 모델 이름은 데이터베이스 경로 해시(database path hash)의 일부이므로, 서로 다른 모델 간에 충돌이 발생하지 않습니다.

주의 사항: DB 경로 해시에는 모델 이름은 포함되지만 백엔드(backend)는 포함되지 않습니다. 만약 동일한 모델 이름이 두 개의 백엔드에 설정되어 있다면 (예: 둘 다 foo라는 이름으로 설정된 Ollama와 LM Studio 항목), 이들은 동일한 인덱스를 공유하게 됩니다. 충돌을 방지하려면 백엔드마다 고유한 모델 이름을 사용하십시오.

lumen index 및 lumen search 명령어는 --model / -m 및 --backend / -b 옵션을 허용합니다.

멀티 서버 config.yaml에서 선택하기 위함입니다. 이 선택 과정은 구성된 서버들 중 두 필드 모두와 일치하는 서버들로 필터링하며, 필터링된 하위 집합 내에서 페일오버 (failover)는 여전히 작동합니다.

# 이 모델 이름과 일치하는 Ollama 서버로 인덱싱합니다.
lumen index --model ordis/jina-embeddings-v2-base-code .
# LM Studio에서 호스팅되는 동일한 모델 이름 (YAML에 존재하며, ... 에는 없음)

만약 YAML에 --model이 구성되어 있지 않지만 알려진 레지스트리 모델인 경우 (그리고 --backend가 설정되지 않은 경우), Lumen은 기본 서버의 모델을 변경하는 방식으로 대체합니다. 이는 YAML이 없는 사용자들을 위해 lumen index --model all-minilm . 명령어를 유지해 줍니다.

사용 중인 모델이 위의 레지스트리에 없는 경우, 레지스트리 확인을 우회하기 위해 LUMEN_EMBED_DIMS를 설정하십시오. LUMEN_EMBED_CTX는 선택 사항이며 기본값은 8192입니다.

두 변수 모두 알려진 모델에 대한 값을 재정의할 수 있습니다. 이는 더 긴 컨텍스트 윈도우 (context window) 또는 다른 출력 차원을 가진 모델 변형을 실행할 때 유용합니다.

LUMEN_BACKEND=lmstudio
LM_STUDIO_HOST=http://localhost:8801
LUMEN_EMBED_MODEL=mlx-community/Qwen3-Embedding-8B-4bit-DWQ
...

Lumen은 6개의 레이어를 통해 파일을 필터링합니다: 내장된 디렉토리 및 잠금 파일 건너뛰기 → .gitignore → .lumenignore → .gitattributes (linguist-generated) → 지원되는 파일 확장자 순입니다. 모든 레이어를 통과한 파일만 인덱싱됩니다.

.lumenignore는 .gitignore를 사용합니다.