{"id":46300143,"url":"https://github.com/ory/lumen","last_synced_at":"2026-04-26T12:02:15.854Z","repository":{"id":341196361,"uuid":"1168314443","full_name":"ory/lumen","owner":"ory","description":"Reduce Claude Code, Codex, OpenCode wall clock and token use by 50% with open source, local semantic search. Works for small and large codebases and monorepos! Enterprise-ready and fully compliant via Ollama and SQLite-vec.","archived":false,"fork":false,"pushed_at":"2026-04-24T08:01:31.000Z","size":22035,"stargazers_count":168,"open_issues_count":3,"forks_count":15,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-24T09:42:04.082Z","etag":null,"topics":["agentic-coding","claude","claude-ai","claude-code","claude-pl","codex","context","gemini","golang","gpt-5","mcp","mcp-server","plugin"],"latest_commit_sha":null,"homepage":"https://www.ory.com/blog/ory-lumen-semantic-search-claude-code","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ory.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-27T08:45:03.000Z","updated_at":"2026-04-24T08:01:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ory/lumen","commit_stats":null,"previous_names":["aeneasr/agent-index","aeneasr/lumen","ory/lumen"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/ory/lumen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ory%2Flumen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ory%2Flumen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ory%2Flumen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ory%2Flumen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ory","download_url":"https://codeload.github.com/ory/lumen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ory%2Flumen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32296259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","claude","claude-ai","claude-code","claude-pl","codex","context","gemini","golang","gpt-5","mcp","mcp-server","plugin"],"created_at":"2026-03-04T11:00:30.690Z","updated_at":"2026-04-26T12:02:15.848Z","avatar_url":"https://github.com/ory.png","language":"Go","readme":"![Ory Lumen: Semantic code search for AI agents](.github/lumen-banner.png)\n\n[![CI](https://github.com/ory/lumen/actions/workflows/ci.yml/badge.svg)](https://github.com/ory/lumen/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/ory/lumen)](https://goreportcard.com/report/github.com/ory/lumen)\n[![Go Reference](https://pkg.go.dev/badge/github.com/ory/lumen.svg)](https://pkg.go.dev/github.com/ory/lumen)\n[![Coverage Status](https://coveralls.io/repos/github/ory/lumen/badge.svg?branch=main)](https://coveralls.io/github/ory/lumen?branch=main)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\nClaude reads entire files to find what it needs. Lumen gives it a map.\n\nLumen is a 100% local semantic code search engine for AI coding agents. No API\nkeys, no cloud, no external database, just open-source embedding models\n([Ollama](https://ollama.com/) or [LM Studio](https://lmstudio.ai/)), SQLite,\nand your CPU. A single static binary and your own local embedding server.\n\nThe payoff is measurable and reproducible: across 9 benchmark runs on 9\nlanguages and real GitHub bug-fix tasks, Lumen cuts cost in **every single\nlanguage** — up to 39%. Output tokens drop by up to 66%, sessions complete up to\n53% faster, and patch quality is maintained in every task. All verified with a\n[transparent, open-source benchmark framework](docs/BENCHMARKS.md) that you can\nrun yourself.\n\n|                        | With Lumen                    | Baseline (no Lumen)  |\n| ---------------------- | ----------------------------- | -------------------- |\n| Cost (avg, bug-fix)    | **$0.29** (-26%)              | $0.40                |\n| Time (avg, bug-fix)    | **125s** (-28%)               | 174s                 |\n| Output tokens (avg)    | **5,247** (-37%)              | 8,323                |\n| JavaScript (marked)    | **$0.32, 119s** (-33%, -53%)  | $0.48, 255s          |\n| Rust (toml)            | **$0.38, 204s** (-39%, -34%)  | $0.61, 310s          |\n| PHP (monolog)          | **$0.14, 34s** (-27%, -34%)   | $0.19, 52s           |\n| TypeScript (commander) | **$0.14, 56s** (-27%, -33%)   | $0.19, 84s           |\n| Svelte (chat-ui)       | **$0.10, 56s** (-26%, -31%)   | $0.14, 80s           |\n| Patch quality          | **Maintained in all 9 tasks** | —                    |\n\n## Table of contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Demo](#demo)\n- [Quick start](#quick-start)\n- [What you get](#what-you-get)\n- [How it works](#how-it-works)\n- [Benchmarks](#benchmarks)\n- [Supported languages](#supported-languages)\n- [Configuration](#configuration)\n  - [Supported embedding models](#supported-embedding-models)\n- [Controlling what gets indexed](#controlling-what-gets-indexed)\n- [Database location](#database-location)\n- [CLI Reference](#cli-reference)\n- [Troubleshooting](#troubleshooting)\n- [Development](#development)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Demo\n\n\u003cimg src=\"docs/demo/demo.gif\" alt=\"Lumen demo\" width=\"600\"/\u003e\n\n_Claude Code asking about the\n[Prometheus](https://github.com/prometheus/prometheus) codebase. Lumen's\n`semantic_search` finds the relevant code without reading entire files._\n\n## Quick start\n\n**Prerequisites:**\n\n\u003e **Platform support:** Linux, macOS, and Windows. File locking for background\n\u003e indexing coordination uses `flock(2)` on Unix and `LockFileEx` on Windows\n\u003e (via [gofrs/flock](https://github.com/gofrs/flock)).\n\n1. [Ollama](https://ollama.com/) installed and running, then pull the default\n   embedding model:\n   ```bash\n   ollama pull ordis/jina-embeddings-v2-base-code\n   ```\n2. One of:\n   [Claude Code](https://code.claude.com/docs/en/quickstart),\n   [Cursor](https://cursor.com/),\n   [Codex](https://developers.openai.com/codex/cli), or\n   [OpenCode](https://opencode.ai/)\n\n**Note:** Installation differs by platform. Claude Code is installed from a\nplugin marketplace. Codex uses a local MCP server plus native skill discovery.\nOpenCode installs from npm. Cursor packaging is shipped in this repository and\nis ready for Cursor's plugin distribution workflow.\n\n**Install:**\n\n**Claude Code**\n\n```bash\n/plugin marketplace add ory/claude-plugins\n/plugin install lumen@ory\n```\n\nVerify by starting a new Claude session and running `/lumen:doctor`.\n\n**Cursor**\n\nLumen ships a native Cursor plugin bundle in this repository:\n\n- `.cursor-plugin/plugin.json` - plugin manifest\n- `mcp.json` - local `lumen` MCP server wiring\n- `hooks/hooks-cursor.json` - SessionStart hook\n- `skills/` - shared `doctor` and `reindex` skills\n\nUse Cursor's plugin installation or distribution workflow with this bundle.\nDetailed packaging notes: [.cursor-plugin/INSTALL.md](.cursor-plugin/INSTALL.md)\n\nVerify by opening a new Cursor agent session and asking it to use the `doctor`\nskill or the Lumen `semantic_search` tool.\n\n**Codex**\n\nQuick install:\n\n```text\nFetch and follow instructions from https://raw.githubusercontent.com/ory/lumen/refs/heads/main/.codex/INSTALL.md\n```\n\nManual install:\n\n```bash\nCODEX_HOME=\"${CODEX_HOME:-$HOME/.codex}\"\ngit clone https://github.com/ory/lumen.git \"$CODEX_HOME/lumen\"\nmkdir -p \"$HOME/.agents/skills\"\nln -s \"$CODEX_HOME/lumen/skills\" \"$HOME/.agents/skills/lumen\"\ncodex mcp add lumen -- \"$CODEX_HOME/lumen/scripts/run.sh\" stdio\n```\n\nDetailed docs: [.codex/INSTALL.md](.codex/INSTALL.md)\n\nVerify with:\n\n```bash\ncodex mcp get lumen\nls -la \"$HOME/.agents/skills/lumen\"\n```\n\n**OpenCode**\n\nAdd `@ory/lumen-opencode` to the `plugin` array in your `opencode.json`:\n\n```json\n{\n  \"plugin\": [\"@ory/lumen-opencode\"]\n}\n```\n\nDetailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)\n\nVerify with:\n\n```bash\nopencode mcp list\n```\n\n**Updating**\n\n- **Claude Code** - update through Claude's plugin marketplace\n- **Cursor** - refresh or reinstall the bundled plugin through Cursor after\n  updating this repository or the published package\n- **Codex** - `cd \"${CODEX_HOME:-$HOME/.codex}/lumen\" \u0026\u0026 git pull`\n- **OpenCode** - update the version pin in `opencode.json` (e.g.\n  `@ory/lumen-opencode@0.0.29`) and restart OpenCode\n\nOn first Claude Code or Cursor session start, Lumen:\n\n1. Downloads the binary automatically from the\n   [latest GitHub release](https://github.com/ory/lumen/releases)\n2. Indexes your project in the background using Merkle tree change detection\n3. Registers a `semantic_search` MCP tool that the host can use automatically\n\nIn Codex and OpenCode, the same binary download and index seeding happen on the\nfirst `semantic_search` call.\n\nTwo shared skills are also available: `doctor` (health check) and `reindex`\n(forced re-indexing). Claude exposes them as `/lumen:doctor` and\n`/lumen:reindex`; the other hosts discover the same shared skill content\nthrough their native skill systems.\n\nThe same `semantic_search`, `health_check`, and `index_status` MCP tools plus\nthe shared `doctor` and `reindex` skills are exposed through the Codex,\nCursor, and OpenCode surfaces as well. The first `semantic_search` call seeds\nor refreshes the index automatically.\n\n## What you get\n\n- **Semantic vector search** — Claude finds relevant functions, types, and\n  modules by meaning, not keyword matching\n- **Auto-indexing** — indexes on session start, only re-processes changed files\n  via Merkle tree diffing\n- **Incremental updates** — re-indexes only what changed; large codebases\n  re-index in seconds after the first run\n- **12 language families** — Go, Python, TypeScript, JavaScript, Svelte, Rust,\n  Ruby, Java, PHP, C/C++, C#, Dart\n- **Git worktree support** — worktrees share index data automatically; a new\n  worktree seeds from a sibling's index and only re-indexes changed files,\n  turning minutes of embedding into seconds\n- **Zero cloud** — embeddings stay on your machine; no data leaves your network\n- **Ollama and LM Studio** — works with either local embedding backend\n\n## How it works\n\nLumen sits between your codebase and Claude as an MCP server. When a session\nstarts, it walks your project and builds a **Merkle tree** over file hashes:\nonly changed files get re-chunked and re-embedded. Each file is split into\nsemantic chunks (functions, types, methods) using Go's native AST or tree-sitter\ngrammars for other languages. Chunks are embedded and stored in **SQLite +\nsqlite-vec** using cosine-distance KNN for retrieval.\n\n```\nFiles → semantic chunks → vector embeddings → SQLite/sqlite-vec → KNN search\n```\n\nWhen Claude needs to understand code, it calls `semantic_search` instead of\nreading entire files. The index is stored outside your repo\n(`~/.local/share/lumen/\u003chash\u003e/index.db`), keyed by project path and model name —\ndifferent models never share an index.\n\n## Benchmarks\n\nLumen is evaluated using **bench-swe**: a SWE-bench-style harness that runs\nClaude on real GitHub bug-fix tasks and measures cost, time, output tokens, and\npatch quality — with and without Lumen. All results are reproducible: raw JSONL\nstreams, patch diffs, and judge ratings are committed to this repository.\n\n**Key results** — 9 runs across 9 languages, hard difficulty, real GitHub\nissues (`ordis/jina-embeddings-v2-base-code`, Ollama):\n\n| Language   | Cost Reduction | Time Reduction | Output Token Reduction  | Quality        |\n| ---------- | -------------- | -------------- | ----------------------- | -------------- |\n| Rust       | **-39%**       | **-34%**       | **-31%** (18K → 12K)    | Poor (both)    |\n| JavaScript | **-33%**       | **-53%**       | **-66%** (14K → 5K)     | Perfect (both) |\n| TypeScript | **-27%**       | **-33%**       | **-64%** (5K → 1.8K)    | Good (both)    |\n| PHP        | **-27%**       | **-34%**       | **-59%** (1.9K → 0.8K)  | Good (both)    |\n| Ruby       | **-24%**       | **-11%**       | -9% (6.1K → 5.6K)       | Good (both)    |\n| Python     | **-20%**       | **-29%**       | **-36%** (1.7K → 1.1K)  | Perfect (both) |\n| Go         | **-12%**       | -9%            | -10% (11K → 10K)         | Good (both)    |\n| C++        | **-8%**        | -3%            | +42% (feature task)      | Good (both)    |\n| Svelte     | **-26%**       | **-31%**       | **-26%** (4.0K → 3.0K)  | Poor (both)    |\n\n**Cost was reduced in every language tested. Quality was maintained in every\ntask — zero regressions.** JavaScript and TypeScript show the most dramatic\nefficiency gains: same quality fixes in half the time with two-thirds fewer\ntokens. Even on tasks too hard for either approach (Rust, Svelte), Lumen cuts\nthe cost of failure by 26–39%.\n\nSee [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for all 9 per-language deep dives,\njudge rationales, and reproduce instructions.\n\n## Supported languages\n\nSupports **12 language families** with semantic chunking (10 benchmarked):\n\n| Language         | Parser      | Extensions                                | Benchmark status                              |\n| ---------------- | ----------- | ----------------------------------------- | --------------------------------------------- |\n| Go               | Native AST  | `.go`                                     | Benchmarked: -12% cost, Good quality          |\n| Python           | tree-sitter | `.py`                                     | Benchmarked: Perfect quality, -36% tokens     |\n| TypeScript / TSX | tree-sitter | `.ts`, `.tsx`                             | Benchmarked: -64% tokens, -33% time           |\n| JavaScript / JSX | tree-sitter | `.js`, `.jsx`, `.mjs`                     | Benchmarked: -66% tokens, -53% time           |\n| Dart             | tree-sitter | `.dart`                                   | Benchmarked: -76% cost, -82% tokens, -79% time |\n| Rust             | tree-sitter | `.rs`                                     | Benchmarked: -39% cost, -34% time             |\n| Ruby             | tree-sitter | `.rb`                                     | Benchmarked: -24% cost, -11% time             |\n| PHP              | tree-sitter | `.php`                                    | Benchmarked: -59% tokens, -34% time           |\n| C / C++          | tree-sitter | `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp` | Benchmarked: -8% cost (C++ feature task)      |\n| Svelte           | tree-sitter | `.svelte`                                 | Benchmarked: -26% cost, -31% time             |\n| Java             | tree-sitter | `.java`                                   | Supported                                     |\n| C#               | tree-sitter | `.cs`                                     | Supported                                     |\n\nGo uses the native Go AST parser for the most precise chunks. All other\nlanguages use tree-sitter grammars. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md)\nfor all 10 per-language benchmark deep dives.\n\n## Configuration\n\nAll configuration is via environment variables:\n\n| Variable                 | Default                  | Description                                                   |\n| ------------------------ | ------------------------ | ------------------------------------------------------------- |\n| `LUMEN_EMBED_MODEL`      | see note ¹               | Embedding model; use with `LUMEN_EMBED_DIMS` for unlisted models |\n| `LUMEN_BACKEND`          | `ollama`                 | Embedding backend (`ollama` or `lmstudio`)                    |\n| `OLLAMA_HOST`            | `http://localhost:11434` | Ollama server URL                                             |\n| `LM_STUDIO_HOST`         | `http://localhost:1234`  | LM Studio server URL                                          |\n| `LUMEN_MAX_CHUNK_TOKENS` | `512`                    | Max tokens per chunk before splitting                         |\n| `LUMEN_EMBED_DIMS`       | —                        | Override embedding dimensions (required for unlisted models)  |\n| `LUMEN_EMBED_CTX`        | `8192` (unlisted models) | Override context window length                                |\n\n¹ `ordis/jina-embeddings-v2-base-code` (Ollama),\n`nomic-ai/nomic-embed-code-GGUF` (LM Studio)\n\n### Supported embedding models\n\nDimensions and context length are configured automatically per model:\n\n| Model                                | Backend   | Dims | Context | Recommended                                                           |\n| ------------------------------------ | --------- | ---- | ------- | --------------------------------------------------------------------- |\n| `ordis/jina-embeddings-v2-base-code` | Ollama    | 768  | 8192    | **Best default** — lowest cost, no over-retrieval                     |\n| `qwen3-embedding:8b`                 | Ollama    | 4096 | 40960   | **Best quality** — strongest dominance (7/9 wins), very slow indexing |\n| `nomic-ai/nomic-embed-code-GGUF`     | LM Studio | 3584 | 8192    | **Usable** — good quality, but TypeScript over-retrieval raises costs |\n| `qwen3-embedding:4b`                 | Ollama    | 2560 | 40960   | **Not recommended** — highest costs, severe TypeScript over-retrieval |\n| `nomic-embed-text`                   | Ollama    | 768  | 8192    | Untested                                                              |\n| `qwen3-embedding:0.6b`               | Ollama    | 1024 | 32768   | Untested                                                              |\n| `all-minilm`                         | Ollama    | 384  | 512     | Untested                                                              |\n\nSwitching models creates a separate index automatically. The model name is part\nof the database path hash, so different models never collide.\n\n\u003e **Caveat**: the DB path hash includes the model name but not the backend. If\n\u003e the same model name is configured on two backends (e.g. an Ollama and an LM\n\u003e Studio entry both named `foo`), they share the same index — use distinct\n\u003e model names per backend to avoid collisions.\n\n### Selecting a server per invocation\n\n`lumen index` and `lumen search` accept `--model`/`-m` and `--backend`/`-b`\nto pick from a multi-server `config.yaml`. The selection filters the\nconfigured servers to those matching both fields; failover still works\nwithin the filtered subset.\n\n```sh\n# Index with the Ollama server matching this model name.\nlumen index --model ordis/jina-embeddings-v2-base-code .\n\n# Same model name hosted on LM Studio (present in YAML, not in the\n# static registry) — accepted because the name is configured.\nlumen index --model text-embedding-jina-embeddings-v2-base-code .\n\n# Disambiguate when the same model is configured on two backends.\nlumen index --model my-embed --backend lmstudio .\n\n# Pick the first configured Ollama server regardless of model.\nlumen search --backend ollama \"…\"\n```\n\nIf `--model` is not configured in YAML but is a known registry model (and\n`--backend` is unset), Lumen falls back to mutating the default server's\nmodel — preserving `lumen index --model all-minilm .` for users with no YAML.\n\n### Using a custom or unlisted model\n\nIf your model is not in the registry above, set `LUMEN_EMBED_DIMS` to bypass the\nregistry check. `LUMEN_EMBED_CTX` is optional and defaults to `8192`.\n\nBoth variables can also override values for _known_ models — useful when running\na model variant with a longer context window or different output dimensions.\n\n```sh\nLUMEN_BACKEND=lmstudio\nLM_STUDIO_HOST=http://localhost:8801\nLUMEN_EMBED_MODEL=mlx-community/Qwen3-Embedding-8B-4bit-DWQ\nLUMEN_EMBED_DIMS=4096\nLUMEN_EMBED_CTX=40960   # optional, defaults to 8192\n```\n\n## Controlling what gets indexed\n\nLumen filters files through six layers: built-in directory and lock file skips →\n`.gitignore` → `.lumenignore` → `.gitattributes` (`linguist-generated`) →\nsupported file extension. Only files that pass all layers are indexed.\n\n**`.lumenignore`** uses `.gitignore` syntax. Place it in your project root (or\nany subdirectory) to exclude files that aren't in `.gitignore` but are noise for\ncode search — generated protobuf files, test snapshots, vendored data, etc.\n\n\u003cdetails\u003e\n\u003csummary\u003eBuilt-in skips (always excluded)\u003c/summary\u003e\n\n**Directories:** `.git`, `node_modules`, `vendor`, `dist`, `.cache`, `.venv`,\n`venv`, `__pycache__`, `target`, `.gradle`, `_build`, `deps`, `.idea`,\n`.vscode`, `.next`, `.nuxt`, `.build`, `.output`, `bower_components`, `.bundle`,\n`.tox`, `.eggs`, `testdata`, `.hg`, `.svn`\n\n**Lock files:** `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`,\n`bun.lockb`, `go.sum`, `composer.lock`, `poetry.lock`, `Pipfile.lock`,\n`Gemfile.lock`, `Cargo.lock`, `pubspec.lock`, `mix.lock`, `flake.lock`,\n`packages.lock.json`\n\n\u003c/details\u003e\n\n## Database location\n\nIndex databases are stored outside your project:\n\n```\n~/.local/share/lumen/\u003chash\u003e/index.db\n```\n\nWhere `\u003chash\u003e` is derived from the absolute project path, embedding model name,\nand binary version. Different models or Lumen versions automatically get\nseparate indexes. No files are added to your repo, no `.gitignore` modifications\nneeded.\n\nYou can safely delete the entire `lumen` directory to clear all indexes, or use\n`lumen purge` to do it automatically.\n\n**Git worktrees** are detected automatically. When you create a new worktree\n(`git worktree add` or `claude --worktree`), Lumen finds a sibling worktree's\nexisting index and copies it as a seed. The Merkle tree diff then re-indexes\nonly the files that actually differ — typically a handful of files instead of\nthe entire codebase. No configuration needed; it just works.\n\n## CLI Reference\n\nDownload the binary from the\n[GitHub releases page](https://github.com/ory/lumen/releases) or let the plugin\ninstall it automatically.\n\n```bash\nlumen help\n```\n\n## Troubleshooting\n\n**Ollama not running / \"connection refused\"**\n\nStart Ollama and verify the model is pulled:\n\n```bash\nollama serve\nollama pull ordis/jina-embeddings-v2-base-code\n```\n\nRun `/lumen:doctor` inside Claude Code to confirm connectivity.\n\nIn Cursor, Codex, or OpenCode, use the shared `doctor` skill or call\n`health_check` and `index_status` directly.\n\n**Stale index after large refactor**\n\nRun `/lumen:reindex` inside Claude Code to force a full re-index, or:\n\n```bash\nlumen purge \u0026\u0026 lumen index .\n```\n\nIn Codex, use the bundled `reindex` skill to refresh the index through the MCP\nserver, or run the same CLI commands for a clean rebuild. The same shared\n`reindex` skill is available in Cursor and OpenCode as well.\n\n**LM Studio: embedding model appears under LLMs instead of Embeddings**\n\nLM Studio classifies embedding models by matching the GGUF `arch` field against\na hardcoded allowlist (`bert`, `nomic-bert`). Models built on other\narchitectures — including Qwen2-based models like `nomic-embed-code` — are\nmisclassified as LLMs. This affects `lms ls` output and the `/v1/embeddings`\nREST endpoint.\n\n**Fix (GGUF, v0.3.16+):** Open LM Studio → My Models, click the gear icon next\nto the model, set **Override Domain Type** → **Text Embedding**.\n\n\u003e **macOS / Apple Silicon:** MLX format models are significantly faster on Apple\n\u003e Silicon. However, LM Studio removed the domain type override for MLX in\n\u003e v0.3.30+, so MLX embedding models cannot be reclassified. Use the GGUF\n\u003e variant to retain the override option, or switch to Ollama\n\u003e (`ordis/jina-embeddings-v2-base-code` or `qwen3-embedding:8b`).\n\n**Switching embedding models**\n\nSet `LUMEN_EMBED_MODEL` to a model from the supported table above. Each model\ngets its own database; the old index is not deleted automatically.\n\n**Slow first indexing**\n\nThe first run embeds every file. Subsequent runs only process changed files\n(typically a few seconds). For large projects (100k+ lines), first indexing can\ntake several minutes — this is a one-time cost.\n\n## Development\n\n```bash\ngit clone https://github.com/ory/lumen.git\ncd lumen\n\n# Build locally (CGO required for sqlite-vec)\nmake build-local\n\n# Run tests\nmake test\n\n# Run linter\nmake lint\n\n# Load as a Claude Code plugin from source\nmake plugin-dev\n```\n\nSee [CLAUDE.md](CLAUDE.md) for architecture details, design decisions, and\ncontribution guidelines, and [AGENTS.md](AGENTS.md) for repo-specific agent\ninstructions.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fory%2Flumen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fory%2Flumen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fory%2Flumen/lists"}