Memorix uses TOML as its main configuration model:
- global defaults:
~/.memorix/config.toml - project overrides:
<git-root>/memorix.toml
The project file is loaded only after Memorix has resolved the real project root
from .git. Config files do not decide project identity.
Legacy memorix.yml, .env, and ~/.memorix/config.json files are still read
for compatibility, but new setup flows and docs use TOML.
Run:
memorix initThe init wizard lets you choose:
Global defaultsfor personal multi-project workflowsProject configfor repo-specific overrides
Example ~/.memorix/config.toml:
[agent]
provider = "deepseek"
model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"
api_key = "..."
[memory.llm]
provider = "openai"
model = "qwen3.5-flash"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_key = "..."
[embedding]
provider = "api"
model = "text-embedding-v4"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_key = "..."
# Optional HTTP rerank. Off unless provider = "http".
# [rerank]
# provider = "http"
# model = "rerank-model"
# base_url = "https://api.example.com/v1"
[memory]
inject = "minimal"
formation = "active"
auto_cleanup = true
sync_advisory = true
[git]
auto_hook = false
ingest_on_commit = true
max_diff_size = 500
skip_merge_commits = true
exclude_patterns = ["*.lock", "dist/**"]
noise_keywords = ["format", "typo"]
[codegraph]
exclude_patterns = ["vendor/**", "third_party/**", "generated/**"]
max_file_bytes = 2097152
# Optional: use an already-indexed local CodeGraph only when it is healthy.
external_context = "auto"
# external_command = "C:\\tools\\codegraph.cmd"
external_timeout_ms = 3000
[server]
transport = "stdio"
dashboard = true
dashboard_port = 3210Global config.toml is local to your machine and is the normal place to keep
provider credentials. Project memorix.toml should be treated as repo config:
override models, switches, and behavior there, but do not commit credentials.
Memorix resolves configuration in this order:
- explicit CLI flags
- process environment variables
- project
<git-root>/memorix.toml - global
~/.memorix/config.toml - legacy compatibility files
- built-in defaults
Environment variables stay available for CI, MCP launchers, and temporary shell overrides. They are not the default user-facing setup path.
For the HTTP control plane, MEMORIX_HTTP_MAX_BODY_BYTES bounds JSON request
bodies at 10 MiB by default and accepts values up to 64 MiB. Keep the default
unless a trusted local client needs larger payloads; this limit is not an
authentication boundary. MEMORIX_HTTP_AUTH_TOKEN enables Bearer-token
authentication for every endpoint except /health. Non-loopback binds are
refused unless this token is set or the operator explicitly sets
MEMORIX_HTTP_ALLOW_UNAUTHENTICATED_BIND=1 behind a private network or
authenticated reverse proxy.
If you want the simplest setup, configure ~/.memorix/config.toml once and stop
there. Add <git-root>/memorix.toml only when a repository needs different
models, memory behavior, or server defaults.
Used by memcode's interactive coding agent.
Common keys:
providermodelbase_urlapi_key
This lane follows memcode's agent runtime behavior. /model, /login, and
agent auth storage still own interactive model switching and login state.
When [agent] is omitted, memcode falls back to [memory.llm] defaults without
changing its interactive model commands.
Used by Memorix background memory intelligence:
- memory formation
- summarization
- deduplication
- optional LLM reranking fallback
- cleanup assistance
Common keys:
providermodelbase_urlapi_key
For OpenAI-compatible providers such as DashScope, DeepSeek-compatible gateways,
or internal model gateways, use provider = "openai" and set base_url.
Memorix uses an explicit provider path as-is: for example,
https://ark.cn-beijing.volces.com/api/v3 remains /api/v3. Only a bare host
without a versioned path receives the convenience suffix /v1.
Atlas Cloud is also available as a memory LLM preset in memorix init and the
configuration TUI:
[memory.llm]
provider = "atlascloud"
model = "deepseek-ai/deepseek-v3.2"The preset uses https://api.atlascloud.ai/v1 and the existing OpenAI-compatible
chat completion transport. Set ATLASCLOUD_API_KEY or MEMORIX_LLM_API_KEY in
your environment, or store api_key in your private global config. Do not put
credentials in project TOML. Explicit model and base_url overrides still
apply; model IDs must be available in your Atlas Cloud account. The Atlas preset
does not fall back to OpenAI, Anthropic, or OpenRouter environment keys.
This is opt-in background memory processing and may incur API charges. Setting
ATLASCLOUD_API_KEY alone does not enable it. Embeddings and memcode's model
registry are unchanged.
Requesty is available as a memory LLM preset in memorix init and the
configuration TUI:
[memory.llm]
provider = "requesty"
model = "openai/gpt-4o-mini"The preset uses https://router.requesty.ai/v1 and the existing
OpenAI-compatible chat completion transport. Set REQUESTY_API_KEY or
MEMORIX_LLM_API_KEY; the preset does not fall back to OpenAI, Anthropic, or
OpenRouter environment keys. Model IDs use the vendor/model form, for example
anthropic/claude-sonnet-4-5. To keep traffic in the EU, set
base_url = "https://router.eu.requesty.ai/v1". Get a key at
https://app.requesty.ai/api-keys.
API Route is available in memorix init and the
configuration TUI as an optional memory LLM preset:
[memory.llm]
provider = "apiroute"
model = "deepseek-v4.1-flash"The preset uses https://global.api-route.com/v1 and the existing
OpenAI-compatible chat completion transport. Set API_ROUTE_API_KEY or
MEMORIX_LLM_API_KEY, or store api_key in your private global config. Keep
credentials out of project TOML. Explicit model and base_url overrides
still apply; use IDs from the endpoint's /v1/models catalog without adding
an extra vendor prefix.
API_ROUTE_API_KEY is used only when this memory preset is selected, and the
preset does not borrow OpenAI, Anthropic, OpenRouter, Requesty, or Atlas Cloud
keys. Setting the key alone does not enable paid background memory processing.
Embeddings and memcode's model registry are unchanged. Image analysis requires
explicitly selecting a vision-capable model; the default is for text memory.
Cheaper Inference is available in memorix init
and the configuration TUI as an optional memory LLM preset:
[memory.llm]
provider = "cheaperinference"
model = "gpt-5.4-mini"The preset uses https://api.cheaperinference.com/v1 and the existing
OpenAI-compatible chat completion transport. Set CHEAPER_INFERENCE_API_KEY or
MEMORIX_LLM_API_KEY, or store api_key in your private global config. Keep
credentials out of project TOML. Explicit model and base_url overrides
still apply; use IDs from the endpoint's /v1/models catalog without adding
an extra vendor prefix.
CHEAPER_INFERENCE_API_KEY is used only when this memory preset is selected,
and the preset does not borrow OpenAI, Anthropic, OpenRouter, Requesty, API
Route, or Atlas Cloud keys. Setting the key alone does not enable paid
background memory processing. Embeddings and memcode's model registry are
unchanged. Image analysis requires explicitly selecting a vision-capable model;
the default is for text memory.
Runcrate serves open-weight models through an
OpenAI-compatible API and is available in memorix init and the configuration
TUI as an optional memory LLM preset:
[memory.llm]
provider = "runcrate"
model = "deepseek-ai/DeepSeek-V4.1-Flash"The preset uses https://api.runcrate.ai/v1 and the existing
OpenAI-compatible chat completion transport. Set RUNCRATE_API_KEY or
MEMORIX_LLM_API_KEY, or store api_key in your private global config. Keep
credentials out of project TOML. Explicit model and base_url overrides
still apply; model IDs use the vendor/model form from the endpoint's
/v1/models catalog, for example zai-org/GLM-5.3 or Qwen/Qwen3.6-35B-A3B.
Get a key at https://runcrate.ai/dashboard/api-keys.
RUNCRATE_API_KEY is used only when this memory preset is selected, and the
preset does not borrow OpenAI, Anthropic, OpenRouter, Requesty, API Route,
Cheaper Inference, or Atlas Cloud keys. Setting the key alone does not enable
paid background memory processing. Embeddings and memcode's model registry are
unchanged. Image analysis requires explicitly selecting a vision-capable model
such as moonshotai/Kimi-K3; the default is for text memory.
OrcaRouter works through the generic OpenAI-compatible gateway path. Keep the
provider label as openai, set its base URL, and use an explicit model ID:
[memory.llm]
provider = "openai"
base_url = "https://api.orcarouter.ai/v1"
model = "openai/gpt-4o-mini"
[agent]
provider = "openai"
base_url = "https://api.orcarouter.ai/v1"
model = "openai/gpt-4o-mini"Use orcarouter/auto only when per-request routing is intended. For memory
formation, structured output, and embeddings, a fixed namespaced model is more
reproducible. Set MEMORIX_LLM_API_KEY and, when using an embedding model
through the same gateway, set MEMORIX_EMBEDDING_API_KEY independently.
When the provider is unavailable, Memorix keeps the durable local write and
falls back to its documented heuristic/BM25 paths; it does not treat a remote
provider outage as a storage failure.
Used by semantic/vector search. This lane is intentionally separate from
[agent] and [memory.llm].
Common keys:
providermodelbase_urlapi_keydimensions
Provider values:
offapiautofastembedtransformers
If embedding is unavailable, Memorix falls back to BM25/full-text search.
Chooses the ranker after a query is embedded. Project memorix.toml overrides ~/.memorix/config.toml, same as [embedding]. Invalid values are ignored.
[retrieval]
cjk = "vector"
ascii = "hybrid"vector: rank by the Lance neighbor order and dedupe by memory id. Recency and the affinity tie-break still apply afterwards. If the Lance table has no vectors, search falls back tohybridand the diagnostics recordlance vector index empty; hybrid search used.hybrid: the existing Orama hybrid ranker.
cjk applies when more than 30% of the query characters are CJK. Everything else uses ascii. Defaults are cjk = "vector" and ascii = "hybrid". MEMORIX_RETRIEVAL_CJK and MEMORIX_RETRIEVAL_ASCII override the files.
When an embeddings host answers GET /api/version with an Ollama version string, Memorix rewrites that origin's /v1/embeddings requests to /api/embed and sends keep_alive: "5m" unless the request already sets one. The port is irrelevant. Leave base_url on /v1; a native /api/embed base URL does not match the OpenAI parser. Hosts that do not serve Ollama's version endpoint stay on /v1/embeddings.
transformers is no longer installed by default; install
@huggingface/transformers explicitly in the project or global prefix where
Memorix runs if you choose that provider. fastembed remains a supported local
provider and is likewise not installed by default.
OpenRouter embeddings can use the official OpenRouter environment variable:
[embedding]
provider = "api"
model = "qwen/qwen3-embedding-8b"
base_url = "https://openrouter.ai/api/v1"Then set OPENROUTER_API_KEY in your shell, user environment, or .env. You
can still set MEMORIX_EMBEDDING_API_KEY when you want an explicit embedding
key override; it takes priority over OPENROUTER_API_KEY.
When base_url points at OpenRouter and no model is configured, Memorix
defaults to qwen/qwen3-embedding-8b (4096 dimensions) instead of the
OpenAI-only default. The equivalent env-var form is
MEMORIX_EMBEDDING=api, MEMORIX_EMBEDDING_BASE_URL=https://openrouter.ai/api/v1,
MEMORIX_EMBEDDING_MODEL=qwen/qwen3-embedding-8b.
Requesty embeddings work the same way with
base_url = "https://router.requesty.ai/v1". Memorix then accepts
REQUESTY_API_KEY for the embedding endpoint and, when no model is
configured, defaults to openai/text-embedding-3-small.
Memorix does not cap the number of durable observations to make search fast. For a large store, the runtime keeps the complete records in SQLite and uses derived indexes for bounded candidate retrieval. The optional LanceDB package is installed with the package's optional dependencies and loaded only at runtime; if its native binary is unavailable, SQLite FTS5 and the Orama fallback continue to work.
MEMORIX_ORAMA_HYDRATION_THRESHOLD=10000 # working-set switch, not a quota
MEMORIX_SEMANTIC_INDEX=auto # auto | off | orama
MEMORIX_SEMANTIC_INDEX_THRESHOLD=10000 # train ANN index after this many vectors
MEMORIX_SEMANTIC_INDEX=auto enables the local LanceDB shadow index when the
optional native package is available. It stores vector IDs and filter metadata,
while full memory text remains in SQLite. The semantic index uses HNSW with
scalar quantization after its threshold is reached; before that, its table is
still searchable without a training step. The derived index can be deleted and
recreated by the background vector backfill without affecting durable memories.
Optional HTTP rerank for thorough search. Off by default.
When provider = "http", Memorix POSTs a Cohere-compatible
{model, query, documents} body to {base_url}/rerank (or an explicit
/rerank path). Any compatible endpoint works — hosted APIs, TEI, vLLM,
or a local gateway. Memorix sends the configured model string unchanged.
Common keys:
provider—off(default) orhttpmodel— user-configured model id (no built-in default). Example:rerank-modelbase_url— API root that serves/rerank, for examplehttps://api.example.com/v1orhttp://127.0.0.1:8080. When unset andprovider = "http", Memorix inherits[memory.llm].base_url.api_key— bearer token. When unset, inherits the memory LLM key (MEMORIX_LLM_API_KEY,MEMORIX_API_KEY, or[memory.llm].api_key) only if the effectivebase_urlis the same trusted endpoint as[memory.llm].base_url. A different rerank URL requiresMEMORIX_RERANK_API_KEYorrerank.api_key.
Environment overrides (highest priority after CLI flags):
MEMORIX_RERANK_PROVIDER=http
MEMORIX_RERANK_MODEL=rerank-model
MEMORIX_RERANK_BASE_URL=https://api.example.com/v1
# MEMORIX_RERANK_API_KEY= # required when base_url is not the memory LLM endpointIf the memory LLM lane already points at the same gateway, you can enable rerank with:
[rerank]
provider = "http"
model = "rerank-model"or set MEMORIX_RERANK_PROVIDER=http and MEMORIX_RERANK_MODEL=....
Timeout is MEMORIX_RERANK_TIMEOUT_MS (default 30000). Thorough search
with at least 3 candidates uses HTTP rerank when configured. On HTTP miss
or timeout, Memorix keeps the original order and does not fall through to
LLM rerank. LLM rerank remains available when HTTP rerank is off, on the
existing thorough/heavy/ambiguous gate.
Image analysis (visual description for ingested images) runs on the LLM lane
through an OpenAI-compatible vision endpoint, so it can also use OpenRouter
with a multimodal model — for example qwen/qwen3-vl-8b-instruct via
MEMORIX_LLM_BASE_URL=https://openrouter.ai/api/v1 and
MEMORIX_LLM_MODEL=qwen/qwen3-vl-8b-instruct.
MiniMax generation is separate from the text embedding lane. Set one of these outside Git only when you deliberately use image or video generation:
MINIMAX_API_KEYfor the global endpointMINIMAX_CN_API_KEYfor the China endpoint- optional
MINIMAX_REGION=global|cn - optional image/video model and endpoint overrides for self-managed routing
The CLI is the normal generation path. memorix_media can import, attach, and
inspect assets through MCP, but MCP generation is off by default. Set
MEMORIX_MCP_MEDIA_GENERATION=1 only after you intentionally allow an agent to
create provider-billed output. The default OpenRouter text embedder remains
text-only; Memorix produces a media vector only when a provider explicitly
declares compatibility with that media modality.
Controlled assets default to a 100 MiB import limit. Vision analysis has a separate 20 MiB cap so a large local file can remain a usable asset without creating an oversized chat-completions request.
Audio-to-text is a separate, opt-in derivative lane. Set the matching provider credential outside Git:
OPENAI_API_KEYwithMEMORIX_TRANSCRIPTION_PROVIDER=openaiGROQ_API_KEYwithMEMORIX_TRANSCRIPTION_PROVIDER=groq- optional
MEMORIX_TRANSCRIPTION_MODEL=<provider model>
The conservative source limit is 25 MiB. The CLI is enabled when a credential
is present; MCP-originated transcription remains disabled unless
MEMORIX_MCP_MEDIA_TRANSCRIPTION=1 is set after reviewing provider billing.
PDF text extraction is a separate, opt-in derivative lane with no provider
credentials. memorix media derive-pdf --asset <asset-id> parses the managed
PDF locally (bundled PDF.js via unpdf, system fonts disabled) and stores a
bounded text derivative with page and character limits (--maxPages,
--maxChars). The MCP memorix_media tool accepts derive-pdf with the same
bounds, and the derived text only enters normal memory when explicitly
attached.
Runtime memory behavior.
Common keys:
inject = "minimal"(full,minimal,silent)formation = "active"(active,shadow,fallback)auto_cleanup = truesync_advisory = true
The same values are available in legacy YAML under behavior.*. Existing
~/.memorix/config.json behavior settings are retained only as a fallback for
older installs.
Git-memory and hook behavior.
Common keys:
auto_hook = falseingest_on_commit = truemax_diff_size = 500skip_merge_commits = trueexclude_patterns = ["*.lock", "dist/**"]noise_keywords = ["format", "typo"](literal phrases, case-insensitive)
Project identity is still resolved from the real .git root. A project
memorix.toml is an override file under that root; it does not create or rename
the Memorix project ID.
Code State, CodeGraph Memory, and Project Context scan/provider settings.
Common keys:
exclude_patterns = ["vendor/**", "third_party/**", "generated/**"]max_file_bytes = 2097152(2 MiB per source file by default)auto_refresh = "auto"("always"or"never"can force or disable built-in Code Memory scans)external_context = "auto"("off"keeps the built-in Lite provider only)external_command = "C:\\tools\\codegraph.cmd"(optional path when CodeGraph is not onPATH)external_timeout_ms = 3000(bounded local semantic-query timeout; values are clamped to 5 seconds)
Legacy YAML uses codegraph.excludePatterns, codegraph.maxFileBytes,
codegraph.externalContext, codegraph.externalCommand, and
codegraph.externalTimeoutMs for the same settings.
These patterns extend Memorix's built-in CodeGraph excludes (node_modules,
build outputs, worktrees, and similar generated directories). Matching paths are
skipped during CodeGraph indexing and hidden from Project Context / Context Pack
suggested reads. Files larger than max_file_bytes are also skipped so a
generated or minified source file cannot monopolize an incremental scan. Raise
the limit only for a repository where that file is intentional source.
Built-in CodeGraph keeps the latest two completed snapshots, removes stale
symbols and dependent edges after a successful refresh, and reclaims SQLite WAL
and free pages when derived data was removed. auto_refresh = "never" is useful
for large BM25-only stores that do not need code indexing; memorix codegraph
refresh remains available for an explicit scan.
external_context = "auto" is deliberately conservative. Memorix checks for
an already-initialized local .codegraph index and uses it only when its status
matches the current project and has no pending changes. It never runs
codegraph init, index, or sync, and it never sends repository content to
a remote service. A valid external response contributes only a small semantic
outline to the current task Workset; raw code is neither copied into the
Workset nor persisted as Memorix knowledge. See
1.2 Provider Quality for the complete contract.
Server and dashboard behavior.
Common keys:
transport = "stdio"— advisory. An explicitmemorix serve-httpstill runs on HTTP and prints a notice; this key documents the intended mode.port = 3211— default listener port formemorix serve-httpwhen--portis not given.dashboard = truedashboard_port = 3210— default port formemorix dashboardwhen--portis not given.
Store sync is disabled unless MEMORIX_SYNC_PROVIDER is explicitly set. It
replicates approved project-visible observation events, never the live SQLite
file or its -wal / -shm companions. The local SQLite store remains the
canonical read/write store. Default scope is the current Git project. Pass
--scope user to relay every local project through a separate user-global
named per-user namespace. Set the same stable value on that user's devices;
the value is required so operators sharing one remote cannot silently share a
default namespace.
MEMORIX_SYNC_PROVIDER=fs|github|s3|postgres
MEMORIX_SYNC_USER_NAMESPACE=your-stable-user-id # required with --scope user
The filesystem relay needs MEMORIX_SYNC_FS_ROOT. The GitHub relay needs a
private relay repository and token:
MEMORIX_SYNC_GITHUB_REPO=owner/repository
MEMORIX_SYNC_GITHUB_TOKEN=...
MEMORIX_SYNC_GITHUB_BRANCH=memorix-sync # optional
For S3-compatible storage, set the usual bucket/endpoint/credentials/region variables and optionally put all Memorix objects below a shared-bucket prefix:
MEMORIX_SYNC_S3_BUCKET=...
MEMORIX_SYNC_S3_ENDPOINT=...
MEMORIX_SYNC_S3_ACCESS_KEY_ID=...
MEMORIX_SYNC_S3_SECRET_ACCESS_KEY=...
MEMORIX_SYNC_S3_REGION=auto
MEMORIX_SYNC_S3_PREFIX=memorix # optional, relative key prefix
S3-compatible and Postgres details are documented in the multi-device sync plan and acceptance contract. Credentials are read from the process environment and are never written to project config or sync event bodies. A copied data directory must be rotated before it can publish:
memorix sync store device rotateUse memorix sync store status --json first. It reports the current project
namespace, eligible/excluded records, pending outbox work, and conflicts without
creating a remote branch or uploading anything.
These sections exist so future releases do not need a config format change. Today no runtime behavior reads them; set them only as forward-looking notes.
[team](enabled,workspace_collection) — coordination defaults.[hooks](native_memcode,external_agents) — hook bootstrap policy.- The former
mcpServerskey inmemorix.ymlwas removed: no code ever consumed it, and Memorix is not an MCP aggregator. Unknown keys are ignored, so old files keep loading.
These files are still read when TOML is absent or incomplete:
- legacy project
memorix.yml - legacy user
~/.memorix/memorix.yml - project
.env - user
~/.memorix/.env - legacy
~/.memorix/config.json
New commands should create TOML. Existing users do not need to migrate immediately.
Useful commands:
memorix config path
memorix config get agent.model
memorix statusTo create one global file from existing local settings:
memorix config migrate --globalTo create a project override file without writing local credentials:
memorix config migratememorix status shows the active project, search mode, and resolved
configuration lanes with sensitive values redacted.