memorix 1.7.1 → 1.7.3

package/docs/CONFIGURATION.md

@@ -47,6 +47,12 @@ 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"
@@ -127,7 +133,7 @@ Used by Memorix background memory intelligence:
 - memory formation
 - summarization
 - deduplication
-- optional reranking
+- optional LLM reranking fallback
 - cleanup assistance
 
 Common keys:
@@ -139,6 +145,9 @@ Common keys:
 
 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`.
 
 ### `[embedding]`
 
@@ -186,6 +195,53 @@ 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`.
 
+### `[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):
+
+```bash
+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:
+
+```toml
+[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

package/docs/DEVELOPMENT.md

@@ -13,9 +13,10 @@ Memorix is a TypeScript project built around:
 
 ## Current Development Baseline
 
-The current release work targets the **1.4 line** while package metadata may still show the last published version until the release commit is cut.
+The current release work targets the **1.7 line** while package metadata may
+still show the last published version until the release commit is cut.
 
-Contributors should assume the following areas are part of the 1.4 release line:
+Contributors should assume the following areas are part of the current release line:
 
 - shared memory across MCP clients, CLI, SDK, dashboard, hooks, and memcode
 - memcode uses Memorix project memory, hooks, `/memory` commands, resumable sessions, and model switching as the bundled terminal agent
@@ -27,6 +28,9 @@ Contributors should assume the following areas are part of the 1.4 release line:
 - dashboard config loading aligned with CLI/TUI status surfaces
 - the existing layered retrieval, retention, attribution, and compact output model
 - source-backed long-term memory with candidate, qualification, approval, archival, supersession, and explicit portable user scope
+- preview-first project maintenance shared across Dashboard, CLI, and MCP
+- the reproducible large-store gate for SDK, HTTP MCP, hooks, persistence, and
+  cold-start retrieval budgets
 
 ---
 

package/docs/PERFORMANCE.md

@@ -75,7 +75,9 @@ On the release development machine used for this check, the healthy HTTP service
 | `MEMORIX_FORMATION_TIMEOUT_MS` | `12000` (12 s) | Raise when LLM-backed formation should outlive slow proxy/provider hops |
 | `MEMORIX_LLM_API_KEY` / `OPENAI_API_KEY` | unset | Enable LLM-backed enrichment, extraction, rerank, or skill generation |
 | `MEMORIX_LLM_TIMEOUT_MS` | `30000` (30 s) | Bound a single LLM-backed extraction/resolve call |
-| `MEMORIX_RERANK_TIMEOUT_MS` | provider default | Bound slow LLM rerank calls |
+| `MEMORIX_RERANK_TIMEOUT_MS` | 30000 | Bound HTTP and LLM rerank calls |
+| `MEMORIX_RERANK_PROVIDER` | `off` | Set `http` to enable optional HTTP rerank |
+| `MEMORIX_RERANK_BASE_URL` | `[memory.llm].base_url` | Compatible `/rerank` API root (path `/rerank` is appended) |
 | `memorix memory search --quality fast` | n/a | Force a fully local retrieval path for a latency-sensitive call |
 | `npm run benchmark:retrieval -- --records 1000 --runs 100` | n/a | Reproduce hot in-process lexical retrieval latency; not an end-to-end claim |
 | `npm run gate:large-store -- --records 40000` | n/a | Exercise SDK, HTTP MCP, hook persistence, cache integrity, and reopen behavior against a large isolated store |
@@ -103,9 +105,16 @@ On the release development machine used for this check, the healthy HTTP service
 temporary Git project with an isolated data directory. It runs with embeddings
 disabled, so it does not use provider credentials or make paid network calls.
 The gate measures steady-state writes, first lexical search, process memory,
-HTTP MCP and hook persistence, and an SDK close/reopen cycle. It also verifies
-that the personal hook candidate remains durable on disk without becoming
-visible to an unbound SDK reader.
+HTTP readiness, MCP initialize/bind/context/search/store, hook capture, and an
+SDK close/reopen cycle. Every network request has a hard timeout, and the
+report fails when an interactive path exceeds its release budget. It also
+verifies that the personal hook candidate remains durable on disk without
+becoming visible to an unbound SDK reader.
+
+Startup hydration uses bounded Orama batches. This keeps HTTP health responsive
+while avoiding a full index rebalance for every persisted observation. The MCP
+search number is intentionally a cold control-plane measurement: it includes
+any lexical hydration the fresh service still owes before its first search.
 
 Results are machine-specific and should be compared on the same OS and Node
 version. The release gate is an integrity and regression check, not a public

package/docs/README.md

@@ -119,11 +119,13 @@ Historical/deep-reference documents may describe older designs. If they conflict
 
 ## Current Product Line
 
-The released product is on the **1.6 line**. The current baseline has:
+The released product is on the **1.7 line**. The current baseline has:
 
 - `memorix setup --agent <agent> --global` is the default agent integration command
 - `memorix serve` is the manual stdio MCP server for external agents
 - `memorix background start` runs the shared HTTP MCP service and dashboard
+- Dashboard maintenance is preview-first, project-scoped, and uses the same
+  cleanup and deduplication planners as CLI and MCP
 - context and CodeGraph commands return bounded task receipts before detailed diagnostics
 - HTTP MCP sessions have a bounded, explicit lifecycle and fail with a reinitialize hint after expiry
 - `memorix integrate --agent <agent>` and `memorix hooks install --agent <agent>` remain manual/fallback generation commands

package/docs/SETUP.md

@@ -498,7 +498,8 @@ What each lane does:
 | Lane | Used by |
 | --- | --- |
 | `[agent]` | model used by memcode while coding |
-| `[memory.llm]` | memory formation, summaries, deduplication, optional rerank |
+| `[memory.llm]` | memory formation, summaries, deduplication, optional LLM rerank fallback |
+| `[rerank]` | optional HTTP rerank against a compatible `/rerank` API |
 | `[embedding]` | semantic/vector search |
 | `[memory]` | memory injection and formation behavior |
 | `[git]` | Git Memory hook and ingestion behavior |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codebuddy/memorix/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Local-first project memory for CodeBuddy Code and other coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/AVIDS2/memorix",
     "source": "github"
   },
-  "version": "1.7.1",
+  "version": "1.7.3",
   "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.7.1",
+      "version": "1.7.3",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/commands/config-migrate.ts

@@ -69,6 +69,13 @@ export function serializeResolvedConfigToToml(
     dimensions: config.embedding.dimensions,
   });
 
+  writeSection(lines, 'rerank', {
+    provider: config.rerank.provider,
+    model: config.rerank.model,
+    base_url: config.rerank.baseUrl,
+    api_key: includeSecrets ? config.rerank.apiKey : undefined,
+  });
+
   writeSection(lines, 'memory', {
     inject: config.memory.inject,
     formation: config.memory.formation,

package/src/cli/commands/doctor.ts

@@ -517,7 +517,11 @@ export default defineCommand({
       if (isLLMEnabled()) {
         const config = getLLMConfig();
         lines.push(ok(`Provider: ${config?.provider}/${config?.model}`));
-        lines.push(info('Capabilities: fact extraction, auto-dedup, LLM rerank'));
+        const { isNeuralRerankEnabled } = await import('../../rerank/index.js');
+        const rerankCap = isNeuralRerankEnabled()
+          ? 'HTTP rerank'
+          : 'LLM rerank';
+        lines.push(info(`Capabilities: fact extraction, auto-dedup, ${rerankCap}`));
         report.llm = { enabled: true, provider: config?.provider, model: config?.model };
       } else {
         lines.push(info('LLM mode: off (heuristic dedup only)'));

package/src/cli/commands/init.ts

@@ -183,6 +183,12 @@ export default defineCommand({
       envLines.push('');
     }
 
+    envLines.push('# Optional HTTP rerank (Cohere-compatible POST {base_url}/rerank)');
+    envLines.push('# MEMORIX_RERANK_PROVIDER=http');
+    envLines.push('# MEMORIX_RERANK_MODEL=rerank-model');
+    envLines.push('# MEMORIX_RERANK_BASE_URL=https://api.example.com/v1');
+    envLines.push('# MEMORIX_RERANK_API_KEY=  # required when BASE_URL is not the memory LLM endpoint');
+    envLines.push('');
     envLines.push('# Optional memory LLM simple key (does not apply to embedding or agent lanes)');
     envLines.push('# MEMORIX_API_KEY=sk-your-key-here');
     envLines.push('');
@@ -310,6 +316,17 @@ export function buildInitTomlConfig(options: {
   }
   lines.push('');
 
+  lines.push('[rerank]');
+  lines.push('# Optional HTTP rerank against any Cohere-compatible /rerank API.');
+  lines.push('# provider = "http"');
+  lines.push('# model = "rerank-model"');
+  lines.push('# base_url inherits [memory.llm] when unset.');
+  if (isGlobal) {
+    lines.push('# Bearer inherits the memory LLM key only when that endpoint matches.');
+    lines.push('# A different rerank URL needs MEMORIX_RERANK_API_KEY.');
+  }
+  lines.push('');
+
   lines.push('[git]');
   lines.push(`auto_hook = ${options.gitAutoHook}`);
   lines.push('ingest_on_commit = true');

package/src/cli/commands/status.ts

@@ -104,6 +104,7 @@ export default defineCommand({
       diagLines.push(`  Agent lane:      ${formatLane(agent.provider, agent.model, agent.baseUrl, agent.apiKey)}`);
       diagLines.push(`  Memory LLM lane: ${formatLane(resolved.memory.llm.provider, resolved.memory.llm.model, resolved.memory.llm.baseUrl, resolved.memory.llm.apiKey)}`);
       diagLines.push(`  Embedding lane:  ${formatLane(resolved.embedding.provider, resolved.embedding.model, resolved.embedding.baseUrl, resolved.embedding.apiKey)}`);
+      diagLines.push(`  Rerank lane:     ${formatLane(resolved.rerank.provider, resolved.rerank.model, resolved.rerank.baseUrl, resolved.rerank.apiKey)}`);
       diagLines.push(`  Memory behavior: inject=${resolved.memory.inject ?? 'default'}, formation=${resolved.memory.formation ?? 'default'}, autoCleanup=${resolved.memory.autoCleanup ?? 'default'}`);
       diagLines.push(`  Git behavior:    autoHook=${resolved.git.autoHook ?? 'default'}, ingestOnCommit=${resolved.git.ingestOnCommit ?? 'default'}, maxDiffSize=${resolved.git.maxDiffSize ?? 'default'}, skipMergeCommits=${resolved.git.skipMergeCommits ?? 'default'}`);
       diagLines.push(`  Server:          transport=${resolved.server.transport ?? 'default'}, dashboard=${resolved.server.dashboard ?? 'default'}, dashboardPort=${resolved.server.dashboardPort ?? 'default'}`);
@@ -141,6 +142,7 @@ export default defineCommand({
           agent: summarizeLane(agent.provider, agent.model, agent.baseUrl, agent.apiKey),
           memoryLlm: summarizeLane(resolved.memory.llm.provider, resolved.memory.llm.model, resolved.memory.llm.baseUrl, resolved.memory.llm.apiKey),
           embedding: summarizeLane(resolved.embedding.provider, resolved.embedding.model, resolved.embedding.baseUrl, resolved.embedding.apiKey),
+          rerank: summarizeLane(resolved.rerank.provider, resolved.rerank.model, resolved.rerank.baseUrl, resolved.rerank.apiKey),
         },
         memory: {
           inject: resolved.memory.inject ?? 'default',

package/src/config/resolved-config.ts

@@ -9,8 +9,8 @@ import {
   getProjectYamlPath,
 } from './config-paths.js';
 import { loadFileConfig } from './legacy-loader.js';
-import { loadTomlConfig } from './toml-loader.js';
-import { loadYamlConfig } from './yaml-loader.js';
+import { loadTomlConfig, type MemorixTomlConfig } from './toml-loader.js';
+import { loadYamlConfig, type MemorixYamlConfig } from './yaml-loader.js';
 import { loadDotenv } from './dotenv-loader.js';
 
 export interface ResolvedLaneOptions {
@@ -44,6 +44,14 @@ export interface ResolvedMemorixConfig {
     apiKey?: string;
     dimensions?: number;
   };
+  rerank: {
+    provider: 'off' | 'http';
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    /** False when a Memory LLM key exists and the rerank URL is a different host without a dedicated key. */
+    canSendRequest: boolean;
+  };
   git: {
     autoHook?: boolean;
     ingestOnCommit?: boolean;
@@ -109,6 +117,16 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
   const openRouterMemoryLlmApiKey = isOpenRouterMemoryLane(memoryLlmProvider, memoryLlmBaseUrl)
     ? process.env.OPENROUTER_API_KEY
     : undefined;
+  const memoryLlmApiKey = first(
+    process.env.MEMORIX_LLM_API_KEY,
+    process.env.MEMORIX_API_KEY,
+    toml.memory?.llm?.api_key,
+    yaml.llm?.apiKey,
+    legacy.llm?.apiKey,
+    process.env.OPENAI_API_KEY,
+    process.env.ANTHROPIC_API_KEY,
+    openRouterMemoryLlmApiKey,
+  );
 
   const resolved: ResolvedMemorixConfig = {
     agent: {
@@ -150,16 +168,7 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
         provider: memoryLlmProvider,
         model: memoryLlmModel,
         baseUrl: memoryLlmBaseUrl,
-        apiKey: first(
-          process.env.MEMORIX_LLM_API_KEY,
-          process.env.MEMORIX_API_KEY,
-          toml.memory?.llm?.api_key,
-          yaml.llm?.apiKey,
-          legacy.llm?.apiKey,
-          process.env.OPENAI_API_KEY,
-          process.env.ANTHROPIC_API_KEY,
-          openRouterMemoryLlmApiKey,
-        ),
+        apiKey: memoryLlmApiKey,
       },
     },
     embedding: {
@@ -169,6 +178,12 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
       apiKey: first(process.env.MEMORIX_EMBEDDING_API_KEY, toml.embedding?.api_key, yaml.embedding?.apiKey, legacy.embeddingApi?.apiKey, openRouterEmbeddingApiKey),
       dimensions: firstNumber(parseNumber(process.env.MEMORIX_EMBEDDING_DIMENSIONS), toml.embedding?.dimensions, yaml.embedding?.dimensions, legacy.embeddingApi?.dimensions),
     },
+    rerank: resolveRerankLane({
+      toml,
+      yaml,
+      memoryLlmApiKey,
+      memoryLlmBaseUrl,
+    }),
     git: {
       autoHook: firstBool(toml.git?.auto_hook, yaml.git?.autoHook),
       ingestOnCommit: firstBool(toml.git?.ingest_on_commit, yaml.git?.ingestOnCommit),
@@ -244,6 +259,10 @@ export function getResolvedEmbeddingLane(options: ResolvedLaneOptions = {}): Res
   return getResolvedConfig(options).embedding;
 }
 
+export function getResolvedRerankLane(options: ResolvedLaneOptions = {}): ResolvedMemorixConfig['rerank'] {
+  return getResolvedConfig(options).rerank;
+}
+
 export function resetResolvedConfigCache(): void {
   // Kept as a public test helper. File-level caches live in individual loaders.
 }
@@ -294,6 +313,10 @@ function getEnvSourceNames(): string[] {
     'MEMORIX_EMBEDDING_BASE_URL',
     'MEMORIX_EMBEDDING_MODEL',
     'MEMORIX_EMBEDDING_DIMENSIONS',
+    'MEMORIX_RERANK_PROVIDER',
+    'MEMORIX_RERANK_MODEL',
+    'MEMORIX_RERANK_BASE_URL',
+    'MEMORIX_RERANK_API_KEY',
     'MEMORIX_CODEGRAPH_EXTERNAL_CONTEXT',
     'MEMORIX_CODEGRAPH_EXTERNAL_COMMAND',
     'MEMORIX_CODEGRAPH_EXTERNAL_TIMEOUT_MS',
@@ -320,3 +343,78 @@ function normalizeExternalContext(value: string | undefined): 'auto' | 'off' | u
   if (normalized === 'auto' || normalized === 'off') return normalized;
   return undefined;
 }
+
+function normalizeRerankProvider(value: string | undefined): 'off' | 'http' {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === 'http') return 'http';
+  return 'off';
+}
+
+function resolveRerankLane(args: {
+  toml: MemorixTomlConfig;
+  yaml: MemorixYamlConfig;
+  memoryLlmApiKey?: string;
+  memoryLlmBaseUrl?: string;
+}): ResolvedMemorixConfig['rerank'] {
+  const provider = normalizeRerankProvider(first(
+    process.env.MEMORIX_RERANK_PROVIDER,
+    args.toml.rerank?.provider,
+    args.yaml.rerank?.provider,
+    'off',
+  ));
+  const model = first(
+    process.env.MEMORIX_RERANK_MODEL,
+    args.toml.rerank?.model,
+    args.yaml.rerank?.model,
+  );
+  const explicitBaseUrl = first(
+    process.env.MEMORIX_RERANK_BASE_URL,
+    args.toml.rerank?.base_url,
+    args.yaml.rerank?.baseUrl,
+  );
+  const baseUrl = provider === 'http'
+    ? first(explicitBaseUrl, args.memoryLlmBaseUrl)
+    : explicitBaseUrl;
+  const dedicatedApiKey = first(
+    process.env.MEMORIX_RERANK_API_KEY,
+    args.toml.rerank?.api_key,
+    args.yaml.rerank?.apiKey,
+  );
+  const sameEndpoint = provider === 'http' && sameTrustedEndpoint(baseUrl, args.memoryLlmBaseUrl);
+  const inheritedApiKey = sameEndpoint ? args.memoryLlmApiKey : undefined;
+  const apiKey = first(dedicatedApiKey, inheritedApiKey);
+  const canSendRequest = provider === 'http' && Boolean(baseUrl)
+    && (Boolean(apiKey) || !args.memoryLlmApiKey || sameEndpoint);
+
+  return { provider, model, baseUrl, apiKey, canSendRequest };
+}
+
+/**
+ * True when two API roots are the same host+path after trailing-slash
+ * and optional `/rerank` normalization. Used so a Memory LLM bearer is
+ * never sent to a different rerank provider.
+ */
+function sameTrustedEndpoint(left?: string, right?: string): boolean {
+  const a = normalizeTrustedEndpoint(left);
+  const b = normalizeTrustedEndpoint(right);
+  return Boolean(a && b && a === b);
+}
+
+function normalizeTrustedEndpoint(value?: string): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  try {
+    const url = new URL(trimmed);
+    const protocol = url.protocol.toLowerCase();
+    const hostname = url.hostname.toLowerCase();
+    const port = url.port;
+    let pathname = url.pathname.replace(/\/+$/, '');
+    if (pathname.toLowerCase().endsWith('/rerank')) {
+      pathname = pathname.slice(0, -'/rerank'.length).replace(/\/+$/, '');
+    }
+    return `${protocol}//${hostname}${port ? `:${port}` : ''}${pathname}`;
+  } catch {
+    const fallback = trimmed.replace(/\/+$/, '').replace(/\/rerank$/i, '').replace(/\/+$/, '');
+    return fallback.toLowerCase() || undefined;
+  }
+}

package/src/config/toml-loader.ts

@@ -28,6 +28,13 @@ export interface MemorixTomlConfig {
     api_key?: string;
     dimensions?: number;
   };
+  /** Optional HTTP rerank against a compatible /rerank API. */
+  rerank?: {
+    provider?: 'off' | 'http' | string;
+    model?: string;
+    base_url?: string;
+    api_key?: string;
+  };
   hooks?: {
     native_memcode?: boolean;
     external_agents?: boolean;
@@ -97,6 +104,7 @@ function mergeTomlConfig(base: MemorixTomlConfig, override: MemorixTomlConfig):
       llm: { ...base.memory?.llm, ...override.memory?.llm },
     },
     embedding: { ...base.embedding, ...override.embedding },
+    rerank: { ...base.rerank, ...override.rerank },
     hooks: { ...base.hooks, ...override.hooks },
     git: { ...base.git, ...override.git },
     codegraph: { ...base.codegraph, ...override.codegraph },

package/src/config/yaml-loader.ts

@@ -48,6 +48,14 @@ export interface MemorixYamlConfig {
     dimensions?: number;
   };
 
+  /** Remote neural rerank (HTTP only) */
+  rerank?: {
+    provider?: 'off' | 'http' | string;
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+  };
+
   /** Git-Memory pipeline configuration */
   git?: {
     /** Auto-install post-commit hook on first run (default: false) */
@@ -190,6 +198,7 @@ export function loadYamlConfig(projectRoot?: string | null): MemorixYamlConfig {
     llm: { ...userConfig.llm, ...projectConfig.llm },
     agent: { ...userConfig.agent, ...projectConfig.agent },
     embedding: { ...userConfig.embedding, ...projectConfig.embedding },
+    rerank: { ...userConfig.rerank, ...projectConfig.rerank },
     git: { ...userConfig.git, ...projectConfig.git },
     codegraph: { ...userConfig.codegraph, ...projectConfig.codegraph },
     behavior: { ...userConfig.behavior, ...projectConfig.behavior },

package/src/llm/provider.ts

@@ -31,6 +31,36 @@ const LLM_TIMEOUT_MIN_MS = 1_000;
 const LLM_TIMEOUT_MAX_MS = 300_000;
 const MAX_LLM_RESPONSE_BYTES = 2 * 1024 * 1024;
 
+const OPENAI_API_VERSION_SEGMENT = /^v\d+(?:[a-z][a-z0-9-]*)?$/i;
+
+/**
+ * Normalize an OpenAI-compatible API root without rewriting an explicit
+ * provider version such as `/api/v3` or `/v1beta`.
+ *
+ * Bare hosts keep the historical convenience of receiving `/v1`. Once a
+ * caller supplies a versioned path, that path is authoritative.
+ */
+export function normalizeOpenAICompatibleBaseUrl(baseUrl: string): string {
+  const base = baseUrl.trim().replace(/\/+$/, '');
+  if (!base) return base;
+
+  let pathname = '';
+  try {
+    pathname = new URL(base).pathname.replace(/\/+$/, '');
+  } catch {
+    pathname = base.split(/[?#]/, 1)[0].replace(/\/+$/, '');
+  }
+
+  const lastSegment = pathname.split('/').filter(Boolean).at(-1);
+  if (lastSegment && OPENAI_API_VERSION_SEGMENT.test(lastSegment)) {
+    return base;
+  }
+
+  const queryOrHash = base.match(/[?#].*$/)?.[0] ?? '';
+  const pathWithoutQuery = base.slice(0, base.length - queryOrHash.length).replace(/\/+$/, '');
+  return `${pathWithoutQuery}/v1${queryOrHash}`;
+}
+
 /**
  * Parse and validate MEMORIX_LLM_TIMEOUT_MS environment variable.
  * - Must be a valid integer in the range 1000–300000ms.
@@ -259,9 +289,7 @@ async function callOpenAICompatible(
   signal?: AbortSignal,
 ): Promise<LLMResponse> {
   const config = currentConfig!;
-  // Auto-fix: append /v1 if baseUrl doesn't end with it (common user mistake)
-  let base = config.baseUrl!.replace(/\/+$/, '');
-  if (!base.endsWith('/v1')) base += '/v1';
+  const base = normalizeOpenAICompatibleBaseUrl(config.baseUrl!);
   const url = `${base}/chat/completions`;
 
   const fetchSignal = signal
@@ -387,8 +415,7 @@ async function callOpenAIWithTools(
   signal?: AbortSignal,
 ): Promise<LLMToolResponse> {
   const config = currentConfig!;
-  let base = config.baseUrl!.replace(/\/+$/, '');
-  if (!base.endsWith('/v1')) base += '/v1';
+  const base = normalizeOpenAICompatibleBaseUrl(config.baseUrl!);
   const url = `${base}/chat/completions`;
 
   // Convert ChatMessage[] to OpenAI format
@@ -603,8 +630,7 @@ async function* callOpenAIWithToolsStream(
   tools: ToolDefinition[],
 ): AsyncGenerator<LLMStreamEvent, void, undefined> {
   const config = currentConfig!;
-  let base = config.baseUrl!.replace(/\/+$/, '');
-  if (!base.endsWith('/v1')) base += '/v1';
+  const base = normalizeOpenAICompatibleBaseUrl(config.baseUrl!);
   const url = `${base}/chat/completions`;
 
   const openaiMessages: Array<Record<string, unknown>> = messages.map((msg) => {

package/src/multimodal/image-loader.ts

@@ -6,7 +6,11 @@
  */
 
 import { getLLMApiKey, getLLMBaseUrl, getLLMModel } from '../config.js';
-import { isLLMEnabled, getLLMConfig } from '../llm/provider.js';
+import {
+  isLLMEnabled,
+  getLLMConfig,
+  normalizeOpenAICompatibleBaseUrl,
+} from '../llm/provider.js';
 import { sanitizeCredentials } from '../memory/secret-filter.js';
 import {
   decodeBase64ImagePayload,
@@ -55,8 +59,7 @@ async function callVisionLLM(
     throw new Error('No LLM API key configured for image analysis.');
   }
 
-  let baseUrl = getLLMBaseUrl('https://api.openai.com/v1').replace(/\/+$/, '');
-  if (!baseUrl.endsWith('/v1')) baseUrl += '/v1';
+  const baseUrl = normalizeOpenAICompatibleBaseUrl(getLLMBaseUrl('https://api.openai.com/v1'));
   const model = getLLMModel('gpt-4o');
 
   const response = await fetch(`${baseUrl}/chat/completions`, {