Skip to content

Latest commit

 

History

History
669 lines (511 loc) · 24.2 KB

CONFIGURATION.md

File metadata and controls

669 lines (511 loc) · 24.2 KB

Memorix Configuration Guide

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.


Minimal Example

Run:

memorix init

The init wizard lets you choose:

  • Global defaults for personal multi-project workflows
  • Project config for 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 = 3210

Global 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.


Resolution Order

Memorix resolves configuration in this order:

  1. explicit CLI flags
  2. process environment variables
  3. project <git-root>/memorix.toml
  4. global ~/.memorix/config.toml
  5. legacy compatibility files
  6. 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.


Configuration Lanes

[agent]

Used by memcode's interactive coding agent.

Common keys:

  • provider
  • model
  • base_url
  • api_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.

[memory.llm]

Used by Memorix background memory intelligence:

  • memory formation
  • summarization
  • deduplication
  • optional LLM reranking fallback
  • cleanup assistance

Common keys:

  • provider
  • model
  • base_url
  • api_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 memory preset

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 memory preset

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 memory preset

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 custom endpoint

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.

[embedding]

Used by semantic/vector search. This lane is intentionally separate from [agent] and [memory.llm].

Common keys:

  • provider
  • model
  • base_url
  • api_key
  • dimensions

Provider values:

  • off
  • api
  • auto
  • fastembed
  • transformers

If embedding is unavailable, Memorix falls back to BM25/full-text search.

[retrieval]

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 to hybrid and the diagnostics record lance 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.

Large-store retrieval

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.

[rerank]

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) or http
  • model — user-configured model id (no built-in default). Example: rerank-model
  • base_url — API root that serves /rerank, for example https://api.example.com/v1 or http://127.0.0.1:8080. When unset and provider = "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 effective base_url is the same trusted endpoint as [memory.llm].base_url. A different rerank URL requires MEMORIX_RERANK_API_KEY or rerank.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 endpoint

If 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.

Controlled MiniMax media

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_KEY for the global endpoint
  • MINIMAX_CN_API_KEY for 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.

Controlled audio transcription

Audio-to-text is a separate, opt-in derivative lane. Set the matching provider credential outside Git:

  • OPENAI_API_KEY with MEMORIX_TRANSCRIPTION_PROVIDER=openai
  • GROQ_API_KEY with MEMORIX_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.

Controlled PDF text derivation

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.

[memory]

Runtime memory behavior.

Common keys:

  • inject = "minimal" (full, minimal, silent)
  • formation = "active" (active, shadow, fallback)
  • auto_cleanup = true
  • sync_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]

Git-memory and hook behavior.

Common keys:

  • auto_hook = false
  • ingest_on_commit = true
  • max_diff_size = 500
  • skip_merge_commits = true
  • exclude_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.

[codegraph]

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 on PATH)
  • 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]

Server and dashboard behavior.

Common keys:

  • transport = "stdio" — advisory. An explicit memorix serve-http still runs on HTTP and prints a notice; this key documents the intended mode.
  • port = 3211 — default listener port for memorix serve-http when --port is not given.
  • dashboard = true
  • dashboard_port = 3210 — default port for memorix dashboard when --port is not given.

Optional store sync

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 rotate

Use 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.

Reserved sections (parsed, not yet enforced)

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 mcpServers key in memorix.yml was removed: no code ever consumed it, and Memorix is not an MCP aggregator. Unknown keys are ignored, so old files keep loading.

Compatibility

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 status

To create one global file from existing local settings:

memorix config migrate --global

To create a project override file without writing local credentials:

memorix config migrate

memorix status shows the active project, search mode, and resolved configuration lanes with sensitive values redacted.