Lumen MCP server
2026년 10월 11일 커밋AI 코딩 에이전트에게 로컬 시맨틱 코드 검색 기능을 제공하여, 파일 전체를 읽지 않고도 관련 함수와 타입을 찾을 수 있게 합니다.
다른 이름 ory/lumen
- 스타
- 318
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 11일
- 라이선스
- —
Lumen MCP란?
AI 코딩 에이전트에게 로컬 시맨틱 코드 검색 기능을 제공하여, 파일 전체를 읽지 않고도 관련 함수와 타입을 찾을 수 있게 합니다.
프로젝트 README에서 생성된 요약
Lumen MCP server 정보
Lumen은 AI 코딩 에이전트에게 코드베이스의 로컬 지도를 제공합니다. Claude와 같은 모델이 컨텍스트를 찾기 위해 파일 전체를 읽도록 강제하는 대신, 이 MCP server는 시맨틱 검색을 통해 특정 함수, 타입 및 모듈을 의미 단위로 찾을 수 있게 합니다. 토큰 사용량을 줄이고 코딩 세션 속도를 높이고 싶은 Claude Code, Cursor, Codex 또는 OpenCode 사용 개발자를 위해 설계되었습니다.
시스템은 SQLite와 CPU를 사용하여 사용자의 로컬 머신에서 완전히 작동하므로 데이터가 네트워크를 벗어나지 않습니다. 작동을 위해 Ollama 또는 LM Studio와 같은 로컬 임베딩 백엔드가 필요합니다. Merkle tree 변경 감지 방식을 사용하여 서버가 증분 업데이트를 수행하므로, 실제로 변경된 파일만 다시 인덱싱하여 대규모 프로젝트에서도 효율적입니다.
Lumen은 Python, Rust, TypeScript, Go를 포함한 12개 언어 제품군을 지원합니다. 코드 검색을 위한 semantic_search와 같은 특정 도구와 상태 확인을 위한 doctor, 수동 업데이트를 위한 reindex와 같은 유지 관리 SKILL을 제공합니다. 이러한 방식은 AI 기반 버그 수정에 필요한 비용과 시간을 크게 줄이면서 패치 품질을 유지하는 데 도움이 됩니다.
활용 사례
- 1AI 토큰 비용 절감개발자가 모델에 파일 전체를 보내는 대신 시맨틱 검색을 사용하여 관련 코드 스니펫을 찾음으로써 비용을 낮출 수 있습니다.
- 2코딩 세션 속도 향상엔지니어가 AI 에이전트에게 시맨틱 의미를 사용하여 특정 함수를 찾도록 지시하여 작업을 더 빠르게 완료할 수 있습니다.
- 3로컬 임베딩으로 개인정보 보호 유지민감한 코드베이스를 다루는 팀은 데이터를 클라우드에 업로드하지 않고도 시맨틱 검색을 수행할 수 있습니다.
- 4대규모 프로젝트의 효율적인 인덱싱개발자가 수정된 파일만 다시 처리함으로써 대규모 저장소를 관리할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
구성
LM_STUDIO_HOSTLUMEN_BACKENDLUMEN_EMBED_CTXLUMEN_EMBED_DIMSLUMEN_EMBED_MODEL
| 이름 | 설명 | 유형 |
|---|---|---|
| LM_STUDIO_HOST | — | |
| LUMEN_BACKEND | — | |
| LUMEN_EMBED_CTX | — | |
| LUMEN_EMBED_DIMS | — | |
| LUMEN_EMBED_MODEL | — |
자동 검사
2026년 11월 15일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능ory/lumen is public and reachablegithub.com/ory/lumen ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)No license결함 발견
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-11github.com/ory/lumen ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기
Claude reads entire files to find what it needs. Lumen gives it a map.
Lumen is a 100% local semantic code search engine for AI coding agents. No API keys, no cloud, no external database, just open-source embedding models (Ollama or LM Studio), SQLite, and your CPU. A single static binary and your own local embedding server.
The payoff is measurable and reproducible: across 9 benchmark runs on 9 languages and real GitHub bug-fix tasks, Lumen cuts cost in every single language — up to 39%. Output tokens drop by up to 66%, sessions complete up to 53% faster, and patch quality is maintained in every task. All verified with a transparent, open-source benchmark framework that you can run yourself.
| With Lumen | Baseline (no Lumen) | |
|---|---|---|
| Cost (avg, bug-fix) | $0.29 (-26%) | $0.40 |
| Time (avg, bug-fix) | 125s (-28%) | 174s |
| Output tokens (avg) | 5,247 (-37%) | 8,323 |
| JavaScript (marked) | $0.32, 119s (-33%, -53%) | $0.48, 255s |
| Rust (toml) | $0.38, 204s (-39%, -34%) | $0.61, 310s |
| PHP (monolog) | $0.14, 34s (-27%, -34%) | $0.19, 52s |
| TypeScript (commander) | $0.14, 56s (-27%, -33%) | $0.19, 84s |
| Svelte (chat-ui) | $0.10, 56s (-26%, -31%) | $0.14, 80s |
| Patch quality | Maintained in all 9 tasks | — |
Table of contents
- Demo
- Quick start
- What you get
- How it works
- Benchmarks
- Supported languages
- Configuration
- Controlling what gets indexed
- Database location
- CLI Reference
- Troubleshooting
- Development
Demo
Claude Code asking about the
Prometheus codebase. Lumen's
semantic_search finds the relevant code without reading entire files.
Quick start
Prerequisites:
Platform support: Linux, macOS, and Windows. File locking for background indexing coordination uses
flock(2)on Unix andLockFileExon Windows (via gofrs/flock).
- Ollama installed and running, then pull the default
embedding model:
ollama pull ordis/jina-embeddings-v2-base-code - One of: Claude Code, Cursor, Codex, or OpenCode
Note: Installation differs by platform. Claude Code and Codex install from plugin marketplaces. OpenCode installs from npm. Cursor packaging is shipped in this repository and is ready for Cursor's plugin distribution workflow.
Install:
Claude Code
/plugin marketplace add ory/claude-plugins
/plugin install lumen@ory
Verify by starting a new Claude session and running /lumen:doctor.
Cursor
Lumen ships a native Cursor plugin bundle in this repository:
.cursor-plugin/plugin.json- plugin manifestmcp.json- locallumenMCP server wiringhooks/hooks-cursor.json- SessionStart hookskills/- shareddoctorandreindexskills
Use Cursor's plugin installation or distribution workflow with this bundle. Detailed packaging notes: .cursor-plugin/INSTALL.md
Verify by opening a new Cursor agent session and asking it to use the doctor
skill or the Lumen semantic_search tool.
Codex
Codex CLI 0.147.0 or newer installs Lumen as a native plugin:
codex plugin marketplace add ory/claude-plugins
codex plugin add lumen@ory
If the marketplace already exists, run codex plugin marketplace upgrade ory
before installing. Legacy manual-clone and broken-plugin repair instructions:
.codex/INSTALL.md.
Verify with:
codex mcp get lumen --json
OpenCode
Add @ory/lumen-opencode to the plugin array in your opencode.json:
{
"plugin": ["@ory/lumen-opencode"]
}
Detailed docs: .opencode/INSTALL.md
Verify with:
opencode mcp list
Updating
- Claude Code - update through Claude's plugin marketplace
- Cursor - refresh or reinstall the bundled plugin through Cursor after updating this repository or the published package
- Codex - upgrade the
orymarketplace, reinstalllumen@ory, and restart - OpenCode - update the version pin in
opencode.json(e.g.@ory/lumen-opencode@0.0.29) and restart OpenCode
On first Claude Code or Cursor session start, Lumen:
- Downloads the binary automatically from the latest GitHub release
- Indexes your project in the background using Merkle tree change detection
- Registers a
semantic_searchMCP tool that the host can use automatically
In Codex and OpenCode, the same binary download and index seeding happen on the
first semantic_search call. Codex stores the downloaded binary in the
plugin's writable data directory rather than the read-only package cache.
Two shared skills are also available: doctor (health check) and reindex
(forced re-indexing). Claude exposes them as /lumen:doctor and
/lumen:reindex; the other hosts discover the same shared skill content
through their native skill systems.
The same semantic_search, health_check, and index_status MCP tools plus
the shared doctor and reindex skills are exposed through the Codex,
Cursor, and OpenCode surfaces as well. The first semantic_search call seeds
or refreshes the index automatically.
What you get
- Semantic vector search — Claude finds relevant functions, types, and modules by meaning, not keyword matching
- Auto-indexing — indexes on session start, only re-processes changed files via Merkle tree diffing
- Incremental updates — re-indexes only what changed; large codebases re-index in seconds after the first run
- 12 language families — Go, Python, TypeScript, JavaScript, Svelte, Rust, Ruby, Java, PHP, C/C++, C#, Dart
- Git worktree support — worktrees share index data automatically; a new worktree seeds from a sibling's index and only re-indexes changed files, turning minutes of embedding into seconds
- Zero cloud — embeddings stay on your machine; no data leaves your network
- Ollama and LM Studio — works with either local embedding backend
How it works
Lumen sits between your codebase and Claude as an MCP server. When a session starts, it walks your project and builds a Merkle tree over file hashes: only changed files get re-chunked and re-embedded. Each file is split into semantic chunks (functions, types, methods) using Go's native AST or tree-sitter grammars for other languages. Chunks are embedded and stored in SQLite + sqlite-vec using cosine-distance KNN for retrieval.
Files → semantic chunks → vector embeddings → SQLite/sqlite-vec → KNN search
When Claude needs to understand code, it calls semantic_search instead of
reading entire files. The index is stored outside your repo
(~/.local/share/lumen/<hash>/index.db). Git worktrees from the same repository
use one collection for a compatible model, vector-storage, and chunking profile;
non-Git projects use private collections. Different profiles never collide.
Benchmarks
Lumen is evaluated using bench-swe: a SWE-bench-style harness that runs Claude on real GitHub bug-fix tasks and measures cost, time, output tokens, and patch quality — with and without Lumen. All results are reproducible: raw JSONL streams, patch diffs, and judge ratings are committed to this repository.
Key results — 9 runs across 9 languages, hard difficulty, real GitHub
issues (ordis/jina-embeddings-v2-base-code, Ollama):
| Language | Cost Reduction | Time Reduction | Output Token Reduction | Quality |
|---|---|---|---|---|
| Rust | -39% | -34% | -31% (18K → 12K) | Poor (both) |
| JavaScript | -33% | -53% | -66% (14K → 5K) | Perfect (both) |
| TypeScript | -27% | -33% | -64% (5K → 1.8K) | Good (both) |
| PHP | -27% | -34% | -59% (1.9K → 0.8K) | Good (both) |
| Ruby | -24% | -11% | -9% (6.1K → 5.6K) | Good (both) |
| Python | -20% | -29% | -36% (1.7K → 1.1K) | Perfect (both) |
| Go | -12% | -9% | -10% (11K → 10K) | Good (both) |
| C++ | -8% | -3% | +42% (feature task) | Good (both) |
| Svelte | -26% | -31% | -26% (4.0K → 3.0K) | Poor (both) |
Cost was reduced in every language tested. Quality was maintained in every task — zero regressions. JavaScript and TypeScript show the most dramatic efficiency gains: same quality fixes in half the time with two-thirds fewer tokens. Even on tasks too hard for either approach (Rust, Svelte), Lumen cuts the cost of failure by 26–39%.
See docs/BENCHMARKS.md for all 9 per-language deep dives, judge rationales, and reproduce instructions.
Supported languages
Supports 12 language families with semantic chunking (10 benchmarked):
| Language | Parser | Extensions | Benchmark status |
|---|---|---|---|
| Go | Native AST | .go |
Benchmarked: -12% cost, Good quality |
| Python | tree-sitter | .py |
Benchmarked: Perfect quality, -36% tokens |
| TypeScript / TSX | tree-sitter | .ts, .tsx |
Benchmarked: -64% tokens, -33% time |
| JavaScript / JSX | tree-sitter | .js, .jsx, .mjs |
Benchmarked: -66% tokens, -53% time |
| Dart | tree-sitter | .dart |
Benchmarked: -76% cost, -82% tokens, -79% time |
| Rust | tree-sitter | .rs |
Benchmarked: -39% cost, -34% time |
| Ruby | tree-sitter | .rb |
Benchmarked: -24% cost, -11% time |
| PHP | tree-sitter | .php |
Benchmarked: -59% tokens, -34% time |
| C / C++ | tree-sitter | .c, .h, .cpp, .cc, .cxx, .hpp |
Benchmarked: -8% cost (C++ feature task) |
| Svelte | tree-sitter | .svelte |
Benchmarked: -26% cost, -31% time |
| Java | tree-sitter | .java |
Supported |
| C# | tree-sitter | .cs |
Supported |
Go uses the native Go AST parser for the most precise chunks. All other languages use tree-sitter grammars. See docs/BENCHMARKS.md for all 10 per-language benchmark deep dives.
Configuration
All configuration is via environment variables:
| Variable | Default | Description |
|---|---|---|
LUMEN_EMBED_MODEL |
see note ¹ | Embedding model; use with LUMEN_EMBED_DIMS for unlisted models |
LUMEN_BACKEND |
ollama |
Embedding backend (ollama or lmstudio) |
OLLAMA_HOST |
http://localhost:11434 |
Ollama server URL |
LM_STUDIO_HOST |
http://localhost:1234 |
LM Studio server URL |
LUMEN_MAX_CHUNK_TOKENS |
512 |
Max tokens per chunk before splitting |
LUMEN_VECTOR_STORAGE |
int8 |
Vector precision (int8 or float32) |
LUMEN_EMBED_DIMS |
— | Override embedding dimensions (required for unlisted models) |
LUMEN_EMBED_CTX |
8192 (unlisted models) |
Override context window length |
¹ ordis/jina-embeddings-v2-base-code (Ollama),
nomic-ai/nomic-embed-code-GGUF (LM Studio)
Supported embedding models
Dimensions and context length are configured automatically per model:
| Model | Backend | Dims | Context | Recommended |
|---|---|---|---|---|
ordis/jina-embeddings-v2-base-code |
Ollama | 768 | 8192 | Best default — lowest cost, no over-retrieval |
qwen3-embedding:8b |
Ollama | 4096 | 40960 | Best quality — strongest dominance (7/9 wins), very slow indexing |
nomic-ai/nomic-embed-code-GGUF |
LM Studio | 3584 | 8192 | Usable — good quality, but TypeScript over-retrieval raises costs |
qwen3-embedding:4b |
Ollama | 2560 | 40960 | Not recommended — highest costs, severe TypeScript over-retrieval |
nomic-embed-text |
Ollama | 768 | 8192 | Untested |
qwen3-embedding:0.6b |
Ollama | 1024 | 32768 | Untested |
all-minilm |
Ollama | 384 | 512 | Untested |
Switching models creates a separate index automatically. The model name is part of the database path hash, so different models never collide.
Caveat: the DB path hash includes the model name but not the backend. If the same model name is configured on two backends (e.g. an Ollama and an LM Studio entry both named
foo), they share the same index — use distinct model names per backend to avoid collisions.
Selecting a server per invocation
lumen index and lumen search accept --model/-m and --backend/-b
to pick from a multi-server config.yaml. The selection filters the
configured servers to those matching both fields; failover still works
within the filtered subset.
# Index with the Ollama server matching this model name.
lumen index --model ordis/jina-embeddings-v2-base-code .
# Same model name hosted on LM Studio (present in YAML, not in the
# static registry) — accepted because the name is configured.
lumen index --model text-embedding-jina-embeddings-v2-base-code .
# Disambiguate when the same model is configured on two backends.
lumen index --model my-embed --backend lmstudio .
# Pick the first configured Ollama server regardless of model.
lumen search --backend ollama "…"
If --model is not configured in YAML but is a known registry model (and
--backend is unset), Lumen falls back to mutating the default server's
model — preserving lumen index --model all-minilm . for users with no YAML.
Using a custom or unlisted model
If your model is not in the registry above, set LUMEN_EMBED_DIMS to bypass the
registry check. LUMEN_EMBED_CTX is optional and defaults to 8192.
Both variables can also override values for known models — useful when running a model variant with a longer context window or different output dimensions.
LUMEN_BACKEND=lmstudio
LM_STUDIO_HOST=http://localhost:8801
LUMEN_EMBED_MODEL=mlx-community/Qwen3-Embedding-8B-4bit-DWQ
LUMEN_EMBED_DIMS=4096
LUMEN_EMBED_CTX=40960 # optional, defaults to 8192
Controlling what gets indexed
Lumen filters files through six layers: built-in directory and lock file skips →
.gitignore → .lumenignore → .gitattributes (linguist-generated) →
supported file extension. Only files that pass all layers are indexed.
.lumenignore uses .gitignore syntax. Place it in your project root (or
any subdirectory) to exclude files that aren't in .gitignore but are noise for
code search — generated protobuf files, test snapshots, vendored data, etc.
Directories: .git, node_modules, vendor, dist, .cache, .venv,
venv, __pycache__, target, .gradle, _build, deps, .idea,
.vscode, .next, .nuxt, .build, .output, bower_components, .bundle,
.tox, .eggs, testdata, .hg, .svn
Lock files: package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock,
bun.lockb, go.sum, composer.lock, poetry.lock, Pipfile.lock,
Gemfile.lock, Cargo.lock, pubspec.lock, mix.lock, flake.lock,
packages.lock.json
Database location
Index databases are stored outside your project:
~/.local/share/lumen/<hash>/index.db
Where <hash> identifies the Git common directory (or the absolute path for a
non-Git project), indexed scope, embedding model and dimensions, vector
precision, chunking profile, and index version. Worktrees in one repository
share content-addressed file revisions and vectors while retaining independent
project memberships. Vectors use int8 storage by default; set
LUMEN_VECTOR_STORAGE=float32 to opt out. No files are added to your repo.
You can safely delete the entire lumen directory to clear all indexes, or let
Lumen reclaim the space for you:
lumen clean # remove indexes unused for 30 days or whose project is gone
lumen clean --days 7 # tighten the cutoff to a week
lumen clean --days 0 # remove every eligible index except actively locked indexes
An index counts as used every time Lumen opens it (search, indexing, status, or session start), so indexes for projects you still work on are never removed. Indexes with an indexer currently running are always kept.
Git worktrees are detected automatically. A new worktree attaches unchanged path-and-content revisions directly from the repository collection and embeds only missing chunk inputs. Removing an old worktree drops its memberships; shared revisions and vectors remain until their final reference disappears. Legacy per-worktree indexes migrate lazily, reusing unchanged float32 vectors without contacting the embedding backend.
For the complete storage key, sharing rules, status metrics, migration process, and cleanup lifecycle, see Index storage and lifecycle.
CLI Reference
Download the binary from the GitHub releases page or let the plugin install it automatically.
lumen help
Troubleshooting
Ollama not running / "connection refused"
Start Ollama and verify the model is pulled:
ollama serve
ollama pull ordis/jina-embeddings-v2-base-code
Run /lumen:doctor inside Claude Code to confirm connectivity.
In Cursor, Codex, or OpenCode, use the shared doctor skill or call
health_check and index_status directly.
Stale index after large refactor
Run /lumen:reindex inside Claude Code to force a full re-index, or:
lumen index --force .
In Codex, use the bundled reindex skill to refresh the index through the MCP
server, or run the same CLI commands for a clean rebuild. The same shared
reindex skill is available in Cursor and OpenCode as well.
LM Studio: embedding model appears under LLMs instead of Embeddings
LM Studio classifies embedding models by matching the GGUF arch field against
a hardcoded allowlist (bert, nomic-bert). Models built on other
architectures — including Qwen2-based models like nomic-embed-code — are
misclassified as LLMs. This affects lms ls output and the /v1/embeddings
REST endpoint.
Fix (GGUF, v0.3.16+): Open LM Studio → My Models, click the gear icon next to the model, set Override Domain Type → Text Embedding.
macOS / Apple Silicon: MLX format models are significantly faster on Apple Silicon. However, LM Studio removed the domain type override for MLX in v0.3.30+, so MLX embedding models cannot be reclassified. Use the GGUF variant to retain the override option, or switch to Ollama (
ordis/jina-embeddings-v2-base-codeorqwen3-embedding:8b).
Switching embedding models
Set LUMEN_EMBED_MODEL to a model from the supported table above. Each model
gets its own database; the old index is not deleted automatically.
Changing LUMEN_VECTOR_STORAGE, LUMEN_EMBED_DIMS, or LUMEN_MAX_CHUNK_TOKENS
also selects a separate collection. Run lumen clean after the old profile is
no longer in use if you want to reclaim its disk space.
Understanding index size and deduplication
Call index_status for the project. It reports project-local file and chunk
counts alongside collection-wide unique vectors, shared references,
deduplication ratio, vector precision, database size, and currently reclaimable
SQLite pages. See
Index storage and lifecycle for
definitions and examples.
Slow first indexing
The first run embeds every file. Subsequent runs only process changed files (typically a few seconds). For large projects (100k+ lines), first indexing can take several minutes — this is a one-time cost.
Development
git clone https://github.com/ory/lumen.git
cd lumen
# Build locally (CGO required for sqlite-vec)
make build-local
# Run tests
make test
# Run linter
make lint
# Load as a Claude Code plugin from source
make plugin-dev
See CLAUDE.md for architecture details, design decisions, and contribution guidelines, and AGENTS.md for repo-specific agent instructions.
Lumen MCP 질문
Lumen이 제 코드를 클라우드로 전송하나요?
아니요. Lumen은 오픈 소스 임베딩 모델, SQLite 및 사용자의 CPU를 사용하여 완전히 로컬에서 실행되므로 임베딩 데이터가 기기를 벗어나지 않습니다.
Lumen은 토큰 비용을 얼마나 절감하나요?
9개 언어에 대한 9번의 벤치마크 실행 결과, Lumen은 패치 품질을 유지하면서 모든 언어에서 비용을 최대 39%까지 절감했습니다.
Lumen은 어떤 임베딩 백엔드를 지원하나요?
로컬 임베딩 백엔드로 Ollama 또는 LM Studio를 지원합니다.
Lumen은 어떤 언어를 인덱싱할 수 있나요?
Lumen은 Go, Python, TypeScript, JavaScript, Rust, Ruby, Java, PHP, C/C++, C#, Dart, Svelte를 포함한 12개 언어 제품군을 지원합니다.
Lumen은 변경되지 않은 파일의 재인덱싱을 어떻게 방지하나요?
파일 해시를 기반으로 Merkle tree를 구축하여 변경된 파일만 다시 청킹하고 임베딩합니다.