Embedding Options
What should I run, on my platform, and what will it cost me? This page answers that question in one read. It is a capability matrix and a set of pointers, not a restatement of the full reference — see Configuration: Embedder sidecar for every flag, environment variable, and resolution-order detail.
liminis-context-graph needs an external embedding backend reachable at startup. It talks to
that backend over the OpenAI-compatible POST /v1/embeddings contract, selected with either
--embedder-uds <path> (Unix domain socket) or --embedder-http <url> (HTTP).
Capability matrix
Section titled “Capability matrix”| Option | Platform(s) | Install | Setup / model cost | Dimension | Flag | Offline? | Dimension auto-probe? | Unreachable at startup | Verification |
|---|---|---|---|---|---|---|---|---|---|
| Swift CoreML sidecar | macOS 26+ | Xcode command-line tools; build from native/local-inference/ | ~500 MB disk for the BGE-base-en-v1.5 CoreML model, downloaded on first setup; no per-call cost | 768 (fixed, BGE-base-en-v1.5) | --embedder-uds (or no flag — auto-detected at /tmp/liminis-inference.sock) | Yes, fully local | Yes | Fail-fast (socket-service mode) or bounded retry-and-degrade (--mcp-stdio) — see Embedder sidecar | Verified — the swift test suite, and verify-embedding-parity.py (cosine parity vs. the PyTorch reference, run manually — not yet wired into CI) |
| Infinity (Python, sentence-transformers-based) | Linux, macOS, Windows | Install and run Infinity yourself; no download bundled with this repo | Depends on the model you load; Infinity itself is free/open-source, no per-call cost | Varies (model-chosen) | --embedder-http | Yes, fully local | Yes | Fail-fast or retry-and-degrade, same as above | Not independently verified in this repo — relies on the generic OpenAI-compatible contract. Listed as an unauthenticated-compatible server in Configuration |
| Ollama | Linux, macOS, Windows | Install Ollama, pull an embedding model (e.g. nomic-embed-text) | Model download only (varies by model, typically a few hundred MB); no per-call cost | Varies (model-chosen) | --embedder-http | Yes, fully local | Yes | Fail-fast or retry-and-degrade, same as above | Not independently verified in this repo — relies on the generic OpenAI-compatible contract. Listed with a concrete recipe in Configuration: MCP client config recipes |
| vLLM / text-embeddings-inference (TEI) | Linux (GPU recommended); macOS/Windows via Docker | Install vLLM or TEI, load a model | Model download (varies); no per-call cost; GPU strongly recommended for throughput | Varies (model-chosen) | --embedder-http | Yes, fully local | Yes | Fail-fast or retry-and-degrade, same as above | Not independently verified in this repo — relies on the generic OpenAI-compatible contract. Listed in Configuration: MCP client config recipes |
Hosted OpenAI-compatible provider (e.g. OpenAI /v1/embeddings) | Any (network required) | An API key; no local install | No download; per-call pricing set by the provider | Model-chosen (e.g. 1536 for text-embedding-3-small) | --embedder-http + LCG_EMBEDDING_API_KEY (or OPENAI_API_KEY) | No — requires network | Yes | Fail-fast — an auth rejection (401/403) is always fatal and is not bypassable via LCG_EMBEDDING_DIM | OpenAI’s own /v1/embeddings is the concrete, verified case — see Configuration: HTTP transport. Other self-described OpenAI-compatible hosted providers are not verified beyond this. |
Every non-macOS, non-OpenAI-hosted row above is caveated deliberately: none of them has been
run against a live instance and tested end-to-end in this repository. Their rows exist because
the wire contract they claim to speak matches what OaiEmbedder sends and expects — not
because this repo has executed an integration test against them. Treat that as “should work,
matches the documented shape,” not “verified working here.”
Any OpenAI-compatible endpoint is a valid target
Section titled “Any OpenAI-compatible endpoint is a valid target”The rows above are examples, not an exhaustive list. Any server that accepts
POST /v1/embeddings with an OpenAI-shaped {input, model} request and returns an
OpenAI-shaped {data: [{embedding}]} response is a valid --embedder-http target. This is
the actual extension point — if your preferred embedding server speaks that contract, point
--embedder-http at it and it will work, whether or not it’s named above. See
ADR 0006 and
ADR 0016 for the wire contract itself.
No bundled cross-platform option
Section titled “No bundled cross-platform option”If you are on Linux or Windows: there is currently no bundled, zero-setup embedder for your
platform. The Swift CoreML sidecar is macOS-only (it depends on CoreML and, for extraction,
Apple Foundation Models — neither exists on other platforms). You must run one of the external
options above (or any other OpenAI-compatible server) yourself and point
liminis-context-graph at it with --embedder-http.
This isn’t an oversight: a native, in-process, cross-platform Rust embedder was evaluated and
rejected. See
docs/spikes/native-embedder-2026-05.md
for the full spike — candle was a NO-GO, ort was GO-with-caveats, and neither was
ever built into production. Out-of-process, over the same wire contract as every other row in
the matrix above, remains the supported path on every platform.
Switching embedders on an existing workspace is not a drop-in swap
Section titled “Switching embedders on an existing workspace is not a drop-in swap”The embedding dimension is fixed into the graph’s LadybugDB schema (FLOAT[dim]) at
database-creation time. liminis-context-graph auto-probes the dimension of whatever embedder
you configure at startup; LCG_EMBEDDING_DIM can override a probe failure, but it cannot
resolve a genuine mismatch between a newly-configured embedder’s dimension and vectors already
stored under the old one.
If you switch to a different-dimension embedder against a workspace that already has content
in its .lcg/ database, that is not something you can just reconfigure and restart into — see
Configuration: Switching an existing workspace’s embedder
for the remedy (full re-ingest, or knowledge_recover with rebuild_from_workspace_wal).
Even a same-dimension model swap invalidates stored vectors. Changing the embedding
model — even to one that happens to produce the same dimension — means your existing vectors
were computed by a different model and are no longer comparable to freshly-embedded ones.
Issue #440 added model-identity
stamping and mismatch detection for exactly this case (knowledge_status’s
embedding_model_status field, and the embeddings_recompute_failed /
embeddings_recompute_skipped_no_text counters) — see
Operations: knowledge_status health fields
for the full mechanics.
Embedding is not extraction
Section titled “Embedding is not extraction”This page is about embedding — the --embedder-uds/--embedder-http flags above. It has
nothing to do with extraction, the separate process of turning text into entities and
relationships, configured independently via
--extractor-uds/--extractor-http/ANTHROPIC_API_KEY. On macOS, the same sidecar process
can happen to serve both endpoints (/v1/embeddings for embedding, /v1/chat/completions for
extraction), which makes the two easy to conflate — but they are selected, resolved, and can
fail independently of each other. See
Configuration: Extractor: local or hosted for
full extraction configuration guidance.
The macOS socket path is not shared with the Electron app
Section titled “The macOS socket path is not shared with the Electron app”liminis-context-graph’s own default UDS auto-discovery path is
/tmp/liminis-inference.sock — a single, well-known, machine-wide path. The Electron
liminis app does not use that path: it launches its own sidecar process bound to a
separate, per-workspace socket at <workspaceRoot>/.liminis/local-inference.sock.
These are two different sockets serving two different processes’ sidecars — never one shared
socket. A liminis-context-graph binary started by hand does not see, and cannot reach, the
sidecar the Electron app started for its own workspace, and vice versa. If you run a manual
CLI session alongside the app, expect to start (or point at) your own sidecar rather than
assuming the app’s is reachable at the well-known path.
Documents liminis-context-graph v0.19.1.