MESA Core · v0.9.3

Embedding & model providers

v0.9.3 source: docs/configuration.md

This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.

Supported providers at a glance#

RoleProvider valueExample modelDimensionInstall extra
Embeddings · local (default)sentence-transformersBAAI/bge-m3, normalized1024ml
Embeddings · externalopenai_compatibletext-embedding-3-small1536base
Embeddings · Nemotron-3 profileopenai_compatibleNemotron-3, nemotron-qpass-v1 (query/passage)2048base
Extraction / validation LLMopenai_compatibleany chat model your endpoint serves, e.g. gpt-4o-mini—base
Extraction / validation LLMclaudea Claude model—[adapters]
Extraction / validation LLMollamaa model already pulled on a running Ollama—base
Tests onlymockreturns no facts——

Extraction and embeddings are configured separately: choosing claude or ollama for extraction does not set up embeddings. Select MESA_LLM_MODEL and MESA_EMBEDDING_MODEL with explicit provider:model values. Changing provider, model, dimension or normalization starts a new embedding space and needs a reindex or a new storage root.

Representation must stay compatible#

Assertion vectors and query embeddings must share provider/model identity and dimension. The documented local default is local:BAAI/bge-m3 with 1024 dimensions; external text-embedding-3-small requires 1536. A settings edit is not an in-place representation migration. Rebuild/reindex under the documented identity rules.

Configured is not operational#

GET /v4/capability distinguishes runtime availability. A custom embedding provider remains non-operational until a successful embedding call. Expected vector/provider failure returns explicit 503; the runtime does not silently switch models. A combined consumer accepts V4 writes with models off and supports BM25. Enable extraction and embedding providers only when those capabilities are needed.

Bound provider access deliberately#

MESA_EXTERNAL_PROVIDER_ENABLED=false allows local Ollama/OpenAI-compatible endpoints and blocks cloud providers. Set it true and supply keys for cloud providers. It is not a complete air-gap or zero-cost guarantee. Model downloads, local provisioning and other process networking are separate concerns. The v0.9.1 DEV benchmark reports BGE retrieval and device latency under stated conditions; it does not measure cloud-provider token cost.

v0.9.3 operation#

Use MESA_LLM_MODEL=provider:model and MESA_EMBEDDING_MODEL=provider:model. BM25 ingestion/search works with models off. Local Ollama and OpenAI-compatible endpoints are allowed with the external-provider flag off; cloud providers require it on and need keys.

Source reference for this page

The sections of the upstream file that back this page, unchanged. Source section links open the appendix automatically.

Providers and capacity#

MESA_CHUNKING=auto (default) splits new document revisions at Turkish article

headings when at least three occur at line starts. The preamble stays separate;

long articles use the existing paragraph/sentence splitting with a 512-token

limit. All slices preserve the exact source text. Other documents keep the same

plain chunks; MESA_CHUNKING=plain selects that plan for every document. Retrying

a pending upload preserves the plan matching its already admitted chunk texts,

even after restarting or changing this setting. Active revisions are unchanged.

If an admitted prefix fits two different plans, the retry returns 409 without

appending chunks, because the stored text cannot identify the original plan.

MESA_LEGAL_RULES_ENABLED=true enables Turkish legal rule processing. In auto

chunking mode, ordinary article chunks inherit the document's law number from

metadata.law_number or a Kanun Numarası, Kanunun Numarası or Kanun No.

header in the first 3,000 characters. Continuation pieces keep that article's

identity; preambles, GEÇİCİ/EK articles and plain plans receive none. Setting the

switch to false disables automatic identity assignment for new chunks. It also

disables legal processing during search, including citation resolution, the

exact-match slot, decision künye promotion, legal ranking factors and graph

citation parsing. Ordinary lexical, vector and graph retrieval still run.

Search ignores stored legal identities and item snapshots while the switch is

off and omits their legal result annotations; it does not erase them. Stored

identities are immutable on resume. Any 3–5 digit law number is accepted by the

typed identity API; known numbers retain their existing statute code (6098 →

TBK). Unknown law names and inconsistent number/code pairs are rejected.

Numbered queries such as 7201 sayılı Kanunun 21. maddesi use the existing

typed legal candidate lane and ranking factors. Document fallback assertions

keep their document subject, madde relation and chunk object; automatic

article identity changes only the typed columns.

Newly admitted chunks also keep versioned citation, decision-reference, date,

amount, duration and outcome items. Search returns them in

retrieval_provenance.legal_items as {version, items}. Item start/end

offsets refer to the original chunk, including when a result quotes a shorter

extracted fact. Items remain separate from SPO facts and do not enter fusion

scores. Decision references can use the bounded exact-match slot below.

Disabling the switch prevents new item snapshots and hides existing snapshots

from search results. Existing snapshots remain stored. Purging a document

erases these source quotes too.

An exact law-and-article query puts at most three matching chunks first, in

document order. Other results retain their fused order (or reranked order when

reranking is enabled). The match must exist in the authorized search scope.

A query's docket and decision numbers can also match a decision's own künye:

a stored decision_ref starting within the first 300 characters of chunk zero.

Its first chunk shares the same three-chunk limit with article matches, in

document order. Later quotations do not teach a decision's identity. The map

uses the same tenant, dataset, agent and time scope cache as law names; an

unmatched reference leaves result order unchanged.

The scope cache learns law names from titles and first-chunk law headers of

documents with trusted article identities; it never learns them from another

tenant, dataset, agent or time scope. Names accept case and Turkish ı/i variants,

possessive suffixes, and K. for Kanunu. The longest exact name from that scope

takes precedence over an overlapping ontology alias. Ambiguous store names

shared by different law numbers are ignored. No static law-name table is added.

MESA_RERANK_ENABLED=false keeps the existing fused ranking and does not import

ML packages. Enabling it requires pip install "mesa-memory[ml]"; startup checks

that the package is installed, and the model loads lazily on the first search.

MESA_RERANK_MODEL defaults to BAAI/bge-reranker-v2-m3 (Apache-2.0), with

MESA_RERANK_DEPTH=50 (range 1–50). The scorer uses authorized full chunk texts

after releasing the search connection, in a worker thread, then returns the

requested number of results. Tied scores retain fused order. Results keep their

fusion fields, including rrf_score and final_score, and add rerank_score.

The first search includes model-load latency; subsequent searches reuse it.

Model and external-provider flags default false. Validation defaults to

mode 0; mode 1 or 2 must be set explicitly via MESA_TIER3_MODE. Mode 2

needs distinct A/B validator identities. Extraction and validation are separate.

MESA_EMBEDDING_ENABLED defaults to MESA_MODEL_ENABLED; MESA_EXTRACTION_ENABLED

defaults to false (D46). A combined runtime accepts writes with both off and finds

them through BM25. Disabled VECTOR lanes end SKIPPED; enabling embedding later

backfills them at startup using the same embedding identity. Backfill failures

leave committed records searchable.

MESA_GRAPH_ENABLED defaults to true, independently of the model flags.

Set it to false to avoid opening Kùzu in the runtime and offline rebuild

runner. GRAPH lanes end SKIPPED, BM25 and enabled vector search still work,

search reports graph in degraded_sources, and capability reports no graph.

Enabling it again backfills skipped GRAPH lanes at combined startup. A rebuild

with graph disabled also marks previously completed GRAPH lanes SKIPPED at

cutover so the new generation can be backfilled later. Existing graph files and

retained generations are not erased by changing this flag.

Local identity defaults to BAAI/bge-m3 1024-d normalized (upgraded from

local:magibu/embeddingmagibu-200m 768-d; existing stores created before v0.9.3 must keep

MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m and MESA_EMBEDDING_DIMENSION=768

unless rebuilt); external text-embedding-3-small

requires setting dimension to 1536. Do not enable external flag and keep an

unrelated dimension. Nemotron-3 profile requires 2048 and nemotron-qpass-v1,

with query/passage input types. Provider/model/revision/dimension/normalization

define a fenced embedding space; switch through reindex/rebuild, not live fallback.

Install optional ML/provider SDK extras for the selected backend. With models

disabled semantic generation is intentionally unavailable. MESA_ZERO_COST_MODE

selects local Ollama configuration but preserves validator settings and does

not prove an air gap. RAM budget precedence is explicit MAX_RAM_MB/MAX_MEMORY_BYTES,

cgroups, psutil, then 1 GiB safe fallback; this is not an RSS guarantee.

Queue per-tenant bounds must fit within global bounds. .env.example deliberately

uses smaller sample global and per-tenant bounds than code defaults.

Minimal V4 provider setup#

Start with the disposable root, key and grants from the

quickstart, with the server stopped.

For an external OpenAI-compatible extraction + embedding setup, install

uv sync --locked --python 3.11 --extra adapters (no local ML extra is needed).

Select models supported by your endpoint. The following is an example pairing,

not evidence of a real-provider run:

bash
mkdir -p "$HOME/mesa-doc-demos"
export MESA_STORAGE_ROOT="$(mktemp -d "$HOME/mesa-doc-demos/v4-XXXXXX")"
export MESA_PRINCIPAL_ID=docs-principal
export MESA_API_KEY="$(.venv/bin/mesa-v4-admin issue-key --principal docs-principal)"
.venv/bin/mesa-v4-admin grant-role --principal docs-principal --tenant docs-tenant --role OWNER
.venv/bin/mesa-v4-admin grant-agent --principal docs-principal --agent docs-agent --permission SESSION_CREATE
export MESA_RUNTIME_PROFILE=combined
export MESA_LOAD_DOTENV=false
export MESA_MODEL_ENABLED=true
export MESA_EXTERNAL_PROVIDER_ENABLED=true
export MESA_TIER3_MODE=0
export MESA_LLM_MODEL=openai:gpt-4o-mini
export MESA_LLM_API_KEY="${OPENAI_API_KEY:?Supply the provider key privately first}"
export MESA_EMBEDDING_MODEL=openai:text-embedding-3-small
export MESA_EMBEDDING_BASE_URL=https://api.openai.com/v1
export MESA_EMBEDDING_API_KEY="$MESA_LLM_API_KEY"
export MESA_EMBEDDING_DIMENSION=1536
export MESA_EMBEDDING_NORMALIZED=true
export MESA_EMBEDDING_VERSION=v1

A root without active vector artifacts adopts a changed embedding identity at

startup and backfills skipped VECTOR lanes. A root with active vectors requires

an explicit rebuild before changing identity. Keep MESA_API_KEY (MESA access) separate

from MESA_LLM_API_KEY / MESA_EMBEDDING_API_KEY (provider access). Modes 1/2 need

the validator A or A/B settings from the table below. Extraction is configured

separately and mode 0 still calls it.

AdapterFactory parses provider:model (ollama, openai, openai_compatible,

anthropic, mock). Embeddings support local sentence-transformers (ml extra) or

OpenAI-compatible endpoints (adapters extra); Claude/Ollama extraction does not

automatically configure embeddings. Native Ollama extraction requires a running

endpoint and an already available model; MESA does not provision it.

Select embeddings with MESA_EMBEDDING_MODEL=provider:model: local:...,

ollama:qwen3-embedding:4b, openai:text-embedding-3-small, or

openai_compatible:nvidia/nemotron-3-embed-1b. The second colon stays in the

model name. MESA_EMBEDDING_BASE_URL overrides the endpoint; Ollama otherwise

uses <MESA_OLLAMA_URL>/v1 and needs no key for a local server.

Local model servers and external providers (D31)#

An endpoint is considered local when its scheme is http or https and its host is localhost, 127.0.0.1, ::1, or host.docker.internal.

  • With MESA_EXTERNAL_PROVIDER_ENABLED=false (default):
  • ollama and openai_compatible (for both LLM extraction and embedding) are allowed on local endpoints (e.g. Ollama on 127.0.0.1:11434, or vLLM on 127.0.0.1:8001/v1; MESA itself uses port 8000) and forbidden on non-local/remote endpoints.
  • openai_compatible on a local endpoint requires no API key (the client sends local automatically).
  • External cloud providers (openai, claude, anthropic, hosted) remain strictly forbidden regardless of endpoint URL.
  • With MESA_EXTERNAL_PROVIDER_ENABLED=true:
  • Remote and cloud provider endpoints are allowed. Cloud providers and remote

openai_compatible endpoints require configured API keys (MESA_LLM_API_KEY,

MESA_EMBEDDING_API_KEY); local openai_compatible endpoints still default

to local, and Ollama keeps its existing key-free behavior.

Missing optional packages (P5-01)#

If an optional provider or model extra is selected but not installed, server startup halts with a clear one-line installation command:

  • Ollama LLM, Ollama embedding, or OpenAI-compatible embedding:

pip install mesa-memory

  • Local transformer embedding (sentence-transformers):

pip install "mesa-memory[ml]"

Endpoint/key settings retain the MESA_LLM_BASE_URL / MESA_LLM_API_KEY fallbacks for those providers.

With embedding enabled and MESA_EMBEDDING_DIMENSION unset, the server and

rebuild runner embed one probe at startup and use its length for storage and

admission. Probe failure stops startup and names the model and URL. Setting the

dimension explicitly skips the probe; embedding disabled with no dimension

keeps 1024 and makes no embedding requests. The removed embedding provider,

external-model and local-model variables stop runtime startup with the

replacement setting. Nemotron still requires MESA_EMBEDDING_VERSION=nemotron-qpass-v1

and 2048 dimensions (explicit or detected).

The built-in mock adapter returns no extracted facts; it is not a source-backed

V4 demo. Contract tests inject deterministic fact and embedding providers

explicitly. Models-disabled startup, deterministic V4 tests and real-provider

V4 runs are different verification levels. V3 raw-memory processing requires

embeddings too; models-disabled boot does not demonstrate insert/search success.