lumen
무엇인가
Lumen은 AI 코딩 에이전트가 코드를 탐색하는 절차를 규율하는 플러그인이다. 규칙 파일에 문장을 적어 두는 대신, 에이전트가 파일을 통째로 읽기 전에 의미 검색 도구를 먼저 호출하도록 MCP 서버와 스킬을 함께 주입한다.
어떻게 동작하나
동작은 MCP 서버와 두 개의 공유 스킬로 나뉜다. 세션 시작 훅이 프로젝트를 순회해 파일 해시 위에 Merkle 트리를 만들고, 변경된 파일만 Go AST 또는 tree-sitter 문법으로 함수·타입·메서드 단위 청크로 쪼개 임베딩한 뒤 SQLite와 sqlite-vec에 저장한다. 호스트에는 semantic_search, health_check, index_status 도구가 등록되고 doctor(상태 점검)와 reindex(강제 재색인) 스킬이 함께 노출된다. Claude Code에서는 /lumen:doctor, /lumen:reindex 슬래시 명령으로 부른다.
무엇과 다른가
CLAUDE.md나 AGENTS.md에 검색 규칙을 손으로 적는 방식과 구조가 다르다. 그쪽은 에이전트에게 먼저 검색하라고 지시만 할 뿐 검색할 대상을 만들어 주지 않는다. Lumen은 정적 바이너리와 로컬 임베딩 서버, 색인 데이터베이스를 함께 배포해 검색 자체를 수행한다. 클라우드 API 키나 외부 데이터베이스 없이 동작하고 임베딩이 네트워크를 떠나지 않는다.
어떻게 쓰나
설치 경로는 호스트마다 다르다. Claude Code는 /plugin marketplace add ory/claude-plugins 뒤 /plugin install lumen@ory로 붙이고 새 세션에서 /lumen:doctor로 확인한다. Codex는 codex plugin marketplace add와 codex plugin add lumen@ory를 쓰고, OpenCode는 opencode.json의 plugin 배열에 @ory/lumen-opencode를 넣는다. Cursor는 저장소에 포함된 .cursor-plugin 번들을 쓴다. 첫 세션에서 바이너리를 내려받고 백그라운드 색인을 시작한다.
전제와 한계
전제는 로컬 임베딩 백엔드다. Ollama를 띄우고 ordis/jina-embeddings-v2-base-code를 미리 받아 두거나 LM Studio를 쓴다. 색인 대상은 Go, Python, TypeScript, JavaScript, Svelte, Rust, Ruby, Java, PHP, C/C++, C#, Dart의 12개 언어 계열이며 그 밖의 파일은 의미 청크로 분해되지 않는다. 플랫폼은 Linux, macOS, Windows를 지원하고 Codex는 CLI 0.147.0 이상이 필요하다. 임베딩 서버가 없으면 검색 도구는 동작하지 않는다.
관련 논문 1
유사 도구
- claude-context코드베이스 전체를 벡터 DB에 인덱싱하고 시맨틱 검색으로 관련 코드만 꺼내 Claude Code 등 코딩 에이전트의 컨텍스트에 넣는 MCP 서버다.
- mempalace대화 기록을 원문 그대로 저장하고 의미 검색으로 꺼내는 로컬 우선 AI 메모리 CLI다. 요약 없이 계층 인덱스로 범위를 좁혀 검색한다.
- mcp-useTypeScript로 MCP 서버와 ChatGPT·Claude용 뷰 앱을 정의하도록 Zod 스키마·도구 등록·React 뷰 바인딩·Inspector 검증 절차를 에이전트에 주입하는 Claude Code 플러그인이다.