memorix 1.2.9 → 1.3.0

package/src/cli/commands/setup.ts

@@ -162,7 +162,9 @@ const OPENCLAW_BUNDLE_AGENTS = new Set<AgentName>(['openclaw']);
 const ANTIGRAVITY_PLUGIN_AGENTS = new Set<AgentName>(['antigravity']);
 const HERMES_PLUGIN_AGENTS = new Set<AgentName>(['hermes']);
 const OMP_PACKAGE_AGENTS = new Set<AgentName>(['omp']);
-const PACKAGE_OWNED_INTEGRATION_AGENTS = new Set<AgentName>(['antigravity', 'openclaw', 'hermes', 'omp']);
+// These hosts have a native package/plugin surface. Their default setup must not
+// create project-local fallback files beside the user's own agent configuration.
+const PACKAGE_OWNED_INTEGRATION_AGENTS = new Set<AgentName>(['codex', 'antigravity', 'openclaw', 'hermes', 'omp']);
 const SUPPORTED_SETUP_AGENTS: AgentName[] = [
   'claude',
   'codex',
@@ -484,6 +486,32 @@ function mergeTomlMcpConfig(existingContent: string | null, generatedContent: st
   return `${parts.join('\n\n')}\n`;
 }
 
+type LegacyArtifactStatus = 'removed' | 'preserved' | 'missing';
+
+export interface CodexLegacyMigrationResult {
+  mcp: LegacyArtifactStatus;
+  projectHooks: LegacyArtifactStatus;
+  pluginFolder: LegacyArtifactStatus;
+}
+
+function getTomlSection(content: string, section: string): string | null {
+  const lines = content.split(/\r?\n/);
+  const header = `[${section}]`;
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start < 0) return null;
+
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim();
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+      end = index;
+      break;
+    }
+  }
+
+  return lines.slice(start + 1, end).join('\n');
+}
+
 function isLegacyCodexMemorixNodeServer(server: MCPServerEntry): boolean {
   if (server.name !== 'memorix' || server.command.trim().toLowerCase() !== 'node') return false;
   const startsMemorixStdio = server.args.some((arg) => arg.trim().toLowerCase() === 'serve');
@@ -494,6 +522,22 @@ function isLegacyCodexMemorixNodeServer(server: MCPServerEntry): boolean {
   return startsMemorixStdio && sourceEntry;
 }
 
+function isOwnedLegacyCodexMcp(content: string): boolean {
+  const section = getTomlSection(content, 'mcp_servers.memorix');
+  if (section === null || getTomlSection(content, 'mcp_servers.memorix.env') !== null) return false;
+
+  const allowedKeys = new Set(['command', 'args', 'type', 'startup_timeout_sec', 'tool_timeout_sec', 'enabled']);
+  for (const rawLine of section.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const key = line.match(/^([A-Za-z0-9_]+)\s*=/)?.[1];
+    if (!key || !allowedKeys.has(key)) return false;
+  }
+
+  const server = new CodexMCPAdapter().parse(content).find((entry) => entry.name === 'memorix');
+  return Boolean(server && isLegacyCodexMemorixNodeServer(server));
+}
+
 /**
  * Codex plugins now own Memorix stdio MCP registration. Remove only the old
  * source-path form emitted by pre-plugin setup, never a user's custom server.
@@ -508,9 +552,7 @@ export async function removeLegacyCodexMemorixMcpConfig(
     return { configPath, removed: false };
   }
 
-  const adapter = new CodexMCPAdapter();
-  const legacyServer = adapter.parse(existingContent).find(isLegacyCodexMemorixNodeServer);
-  if (!legacyServer) return { configPath, removed: false };
+  if (!isOwnedLegacyCodexMcp(existingContent)) return { configPath, removed: false };
 
   let nextContent = removeTomlSection(existingContent, 'mcp_servers.memorix.env');
   nextContent = removeTomlSection(nextContent, 'mcp_servers.memorix');
@@ -518,6 +560,88 @@ export async function removeLegacyCodexMemorixMcpConfig(
   return { configPath, removed: true };
 }
 
+function collectHookCommands(value: unknown, commands: string[]): void {
+  if (Array.isArray(value)) {
+    for (const item of value) collectHookCommands(item, commands);
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    if ((key === 'command' || key === 'commandWindows') && typeof child === 'string') {
+      commands.push(child);
+    } else {
+      collectHookCommands(child, commands);
+    }
+  }
+}
+
+function isOwnedLegacyCodexHooks(content: string): boolean {
+  try {
+    const parsed = JSON.parse(content) as { hooks?: unknown };
+    if (!parsed.hooks || typeof parsed.hooks !== 'object') return false;
+    const commands: string[] = [];
+    collectHookCommands(parsed.hooks, commands);
+    return commands.length > 0
+      && commands.every((command) => /^memorix(?:\.cmd)?\s+hook(?:\s|$)/i.test(command.trim()));
+  } catch {
+    return false;
+  }
+}
+
+async function removeOwnedLegacyCodexPluginFolder(homeDir: string): Promise<LegacyArtifactStatus> {
+  const canonicalPath = path.join(homeDir, 'plugins', 'memorix');
+  const legacyPath = path.join(homeDir, '.codex', 'plugins', 'memorix');
+  if (!existsSync(legacyPath)) return 'missing';
+  if (!existsSync(canonicalPath)) return 'preserved';
+
+  try {
+    const manifest = JSON.parse(await readFile(path.join(legacyPath, '.codex-plugin', 'plugin.json'), 'utf-8')) as Record<string, unknown>;
+    const repository = String(manifest.repository ?? '');
+    if (manifest.name !== 'memorix' || !repository.includes('github.com/AVIDS2/memorix')) return 'preserved';
+    await rm(legacyPath, { recursive: true, force: true });
+    return 'removed';
+  } catch {
+    return 'preserved';
+  }
+}
+
+export async function migrateLegacyCodexIntegration(options: {
+  homeDir?: string;
+  projectRoot?: string;
+} = {}): Promise<CodexLegacyMigrationResult> {
+  const homeDir = options.homeDir ?? homedir();
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const configPath = path.join(homeDir, '.codex', 'config.toml');
+  let mcp: LegacyArtifactStatus = 'missing';
+
+  try {
+    const content = await readFile(configPath, 'utf-8');
+    if (getTomlSection(content, 'mcp_servers.memorix') !== null) {
+      mcp = (await removeLegacyCodexMemorixMcpConfig(configPath)).removed ? 'removed' : 'preserved';
+    }
+  } catch {
+    mcp = 'missing';
+  }
+
+  const hooksPath = path.join(projectRoot, '.codex', 'hooks.json');
+  let projectHooks: LegacyArtifactStatus = 'missing';
+  try {
+    const content = await readFile(hooksPath, 'utf-8');
+    if (isOwnedLegacyCodexHooks(content)) {
+      await rm(hooksPath, { force: true });
+      projectHooks = 'removed';
+    } else {
+      projectHooks = 'preserved';
+    }
+  } catch {
+    projectHooks = 'missing';
+  }
+
+  const pluginFolder = await removeOwnedLegacyCodexPluginFolder(homeDir);
+  return { mcp, projectHooks, pluginFolder };
+}
+
 function mergeYamlMcpConfig(existingContent: string | null, generatedContent: string): string {
   let existing: Record<string, unknown> = {};
   try {
@@ -678,7 +802,9 @@ export async function installPluginPackage(options: PluginInstallOptions): Promi
   }
 
   if (options.agent === 'codex') {
-    const pluginPath = path.join(home, '.codex', 'plugins', 'memorix');
+    // Codex discovers personal plugins from the user marketplace. Keep the
+    // package outside ~/.codex so setup does not look like project/config state.
+    const pluginPath = path.join(home, 'plugins', 'memorix');
     const marketplacePath = path.join(home, '.agents', 'plugins', 'marketplace.json');
     await copyDir(source, pluginPath);
     await stampCodexPluginVersion(pluginPath);
@@ -908,6 +1034,39 @@ function tryInstallClaudePlugin(marketplaceRoot: string): { ok: boolean; message
   };
 }
 
+export type CodexPluginState = 'ready' | 'disabled' | 'missing' | 'unknown';
+
+export function parseCodexPluginState(content: string): CodexPluginState {
+  try {
+    // Some Windows builds emit a one-line diagnostic before the requested JSON.
+    const start = content.indexOf('{');
+    const end = content.lastIndexOf('}');
+    if (start < 0 || end < start) return 'unknown';
+    const parsed = JSON.parse(content.slice(start, end + 1)) as { installed?: unknown };
+    if (!Array.isArray(parsed.installed)) return 'unknown';
+
+    const plugin = parsed.installed.find((entry): entry is Record<string, unknown> => (
+      Boolean(entry)
+      && typeof entry === 'object'
+      && (entry as Record<string, unknown>).pluginId === 'memorix@personal'
+    ));
+    if (!plugin || plugin.installed !== true) return 'missing';
+    return plugin.enabled === true ? 'ready' : 'disabled';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function getCodexPluginState(): CodexPluginState {
+  const result = spawnSync('codex', ['plugin', 'list', '--json'], {
+    encoding: 'utf-8',
+    stdio: 'pipe',
+    shell: process.platform === 'win32',
+  });
+  if (result.status !== 0) return 'unknown';
+  return parseCodexPluginState(result.stdout || '');
+}
+
 export function tryInstallCodexPlugin(): { ok: boolean; message: string } {
   const result = spawnSync('codex', ['plugin', 'add', 'memorix@personal', '--json'], {
     encoding: 'utf-8',
@@ -915,13 +1074,28 @@ export function tryInstallCodexPlugin(): { ok: boolean; message: string } {
     shell: process.platform === 'win32',
   });
 
-  if (result.status === 0) {
-    return { ok: true, message: 'codex: plugin installed from Personal marketplace' };
-  }
-
   const output = `${result.stderr || ''}\n${result.stdout || ''}`.toLowerCase();
-  if (output.includes('already')) {
-    return { ok: true, message: 'codex: plugin already installed from Personal marketplace' };
+  const addFinished = result.status === 0 || output.includes('already');
+  if (addFinished) {
+    const pluginState = getCodexPluginState();
+    if (pluginState === 'ready') {
+      return {
+        ok: true,
+        message: result.status === 0
+          ? 'codex: plugin installed and enabled from Personal marketplace'
+          : 'codex: plugin already installed and enabled from Personal marketplace',
+      };
+    }
+    if (pluginState === 'disabled') {
+      return {
+        ok: false,
+        message: 'codex: Memorix plugin is installed but disabled. Enable it in Codex Plugins before any legacy MCP or project hooks are removed.',
+      };
+    }
+    return {
+      ok: false,
+      message: 'codex: plugin registration finished, but Codex did not confirm an enabled Memorix plugin. Legacy MCP and project hooks were kept unchanged.',
+    };
   }
 
   const detail = (result.stderr || result.stdout || result.error?.message || '').trim();
@@ -1106,7 +1280,9 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
   const hasAntigravityPlugin = plan.actions.includes('antigravity-plugin') && agent === 'antigravity';
   const hasHermesPlugin = plan.actions.includes('hermes-plugin') && agent === 'hermes';
   const hasOmpPackage = plan.actions.includes('omp-package') && agent === 'omp';
-  const wantsMcpConfig = plan.mcp !== 'none' && agent !== 'pi';
+  // Codex's supported default is the user-level plugin. Never create a
+  // project-local .codex/config.toml as an implicit fallback.
+  const wantsMcpConfig = plan.mcp !== 'none' && agent !== 'pi' && !(agent === 'codex' && !global);
 
   if (PLUGIN_PACKAGE_AGENTS.has(agent) && plan.includePlugin && !global) {
     p.log.info(`${agent}: project setup leaves user-level plugins untouched. Run \`memorix setup --agent ${agent} --global\` to install its plugin, skills, and lifecycle hooks.`);
@@ -1115,7 +1291,7 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
   if (hasPluginPackage) {
     const result = await installPluginPackage({
       agent: agent as PluginInstallOptions['agent'],
-      includeHooks: plan.actions.includes('hooks'),
+      includeHooks: plan.includeHooks,
     });
     p.log.success(`${agent}: plugin package -> ${result.pluginPath}`);
     if (result.marketplacePath) {
@@ -1123,17 +1299,16 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
     }
     if (agent === 'codex') {
       const install = tryInstallCodexPlugin();
-      if (install.ok) p.log.success(install.message);
-      else p.log.warn(install.message);
       if (install.ok) {
-        try {
-          const migration = await removeLegacyCodexMemorixMcpConfig();
-          if (migration.removed) {
-            p.log.info(`codex: removed legacy source-path MCP config from ${migration.configPath}`);
-          }
-        } catch {
-          p.log.warn('codex: plugin installed, but the legacy MCP config could not be checked');
-        }
+        p.log.success(install.message);
+        const migration = await migrateLegacyCodexIntegration({ projectRoot: process.cwd() });
+        if (migration.mcp === 'removed') p.log.info('codex: removed the legacy source-path MCP block; the enabled plugin now owns MCP.');
+        if (migration.mcp === 'preserved') p.log.warn('codex: kept a customized legacy Memorix MCP block; remove it manually only after confirming plugin MCP works.');
+        if (migration.projectHooks === 'removed') p.log.info('codex: removed a legacy project-local Memorix hooks.json; plugin hooks now own lifecycle capture.');
+        if (migration.projectHooks === 'preserved') p.log.warn('codex: kept a project .codex/hooks.json because it contains non-Memorix commands.');
+        if (migration.pluginFolder === 'removed') p.log.info('codex: removed the migrated legacy plugin folder under ~/.codex/plugins.');
+      } else {
+        p.log.warn(install.message);
       }
     } else if (agent === 'claude' && result.marketplaceRoot) {
       const install = tryInstallClaudePlugin(result.marketplaceRoot);
@@ -1224,6 +1399,8 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
       const result = await installMcpConfig({ agent: agent as McpConfigAgent, projectRoot: targetRoot, global, mcp });
       p.log.success(`${agent}: MCP config -> ${result.configPath}`);
     }
+  } else if (agent === 'codex' && !global && plan.mcp !== 'none') {
+    p.log.info('codex: project-local .codex config is intentionally untouched. Run `memorix setup --agent codex --global` to install the user-level plugin.');
   }
 
   if (hasPluginPackage) {

package/src/codegraph/auto-context.ts

@@ -388,6 +388,7 @@ export async function buildAutoProjectContext(input: {
       stale: overview.freshness.stale,
     },
     runtimeCautions,
+    ...(input.reader ? { reader: input.reader } : {}),
     ...(input.deliveryTarget ? { deliveryTarget: input.deliveryTarget } : {}),
   });
 
@@ -601,6 +602,16 @@ export function formatAutoProjectContextSummary(context: AutoProjectContext): st
       : '- none yet',
   );
 
+  if (context.workset.durableMemory.length > 0) {
+    lines.push('', 'Durable memory');
+    for (const memory of context.workset.durableMemory.slice(0, 3)) {
+      lines.push(
+        '- ' + memory.kind + ' (' + memory.scope + ', ' + memory.state + '): '
+          + compactContinuationText(memory.summary, 28),
+      );
+    }
+  }
+
   const continuation = context.workset.continuation;
   if (continuation?.previousSession || continuation?.memories.length || continuation?.compactCheckpoint) {
     lines.push('', 'Resume from prior work');

package/src/codegraph/context-pack.ts

@@ -10,6 +10,7 @@ import type {
 } from './types.js';
 import type { CodeGraphStore } from './store.js';
 import { isCodeGraphExcludedPath } from './exclude.js';
+import type { ObservationReader } from '../types.js';
 
 export interface ContextPackMemory {
   id: number;
@@ -276,6 +277,7 @@ export async function attachTaskWorkset(input: {
   semanticCode?: ExternalCodeGraphOutline;
   providerQuality?: CodeGraphProviderQuality;
   runtimeCautions?: WorksetCaution[];
+  reader?: ObservationReader;
 }): Promise<ContextPack> {
   const semanticStartHere = input.semanticCode
     ? [...input.semanticCode.relatedFiles, ...input.semanticCode.entryPoints.map(entry => entry.path)]
@@ -316,6 +318,7 @@ export async function attachTaskWorkset(input: {
       stale: input.pack.warnings.filter(warning => warning.status === 'stale').length,
     },
     runtimeCautions: input.runtimeCautions,
+    ...(input.reader ? { reader: input.reader } : {}),
     deliveryTarget: 'context-pack',
   });
   return { ...input.pack, workset };

package/src/embedding/api-provider.ts

@@ -9,7 +9,7 @@ import { createHash } from 'node:crypto';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import type { EmbeddingProvider } from './provider.js';
+import type { EmbeddingProvider, EmbeddingRequestOptions } from './provider.js';
 
 const CACHE_DIR = process.env.MEMORIX_DATA_DIR || join(homedir(), '.memorix', 'data');
 const CACHE_FILE = join(CACHE_DIR, '.embedding-api-cache.json');
@@ -306,6 +306,10 @@ export interface APIEmbeddingProviderCreateOptions {
    * the provider. This keeps startup/cache hydration off the remote API path.
    */
   allowNetworkProbe?: boolean;
+  /** Bound the one-off remote dimension probe used on a cold API start. */
+  requestTimeoutMs?: number;
+  /** Disable retries for a bounded, best-effort API initialization. */
+  retry?: boolean;
 }
 
 function resolveEnvEmbeddingApiKey(): string | undefined {
@@ -370,7 +374,10 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
       }
     } else {
       if (!allowNetworkProbe) return null;
-      probeDimensions = await APIEmbeddingProvider.probeAPI(config);
+      probeDimensions = await APIEmbeddingProvider.probeAPI(config, {
+        timeoutMs: options.requestTimeoutMs,
+        retry: options.retry,
+      });
       console.error(`[memorix] API embedding: ${config.model} @ ${config.baseUrl} (${probeDimensions}d)`);
       // Persist for next cold start
       saveCachedDims(config, probeDimensions).catch(() => {});
@@ -430,7 +437,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
     return { apiKey, baseUrl, model, requestedDimensions };
   }
 
-  private static async probeAPI(config: APIEmbeddingConfig): Promise<number> {
+  private static async probeAPI(config: APIEmbeddingConfig, options?: EmbeddingRequestOptions): Promise<number> {
     const body: Record<string, unknown> = {
       model: config.model,
       input: 'dimension probe',
@@ -443,6 +450,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
       `${config.baseUrl}/embeddings`,
       config.apiKey,
       body,
+      options,
     );
 
     if (response.data.length === 0 || !response.data[0].embedding) {
@@ -452,7 +460,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
     return response.data[0].embedding.length;
   }
 
-  async embed(text: string): Promise<number[]> {
+  async embed(text: string, options?: EmbeddingRequestOptions): Promise<number[]> {
     const normalized = normalizeText(text);
     const hash = textHash(normalized, this.cacheKeyNamespace);
 
@@ -477,6 +485,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
         `${this.config.baseUrl}/embeddings`,
         this.config.apiKey,
         body,
+        options,
       );
       const embedding = response.data[0].embedding;
       if (embedding.length !== this.dimensions) {
@@ -521,7 +530,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
     return embedding;
   }
 
-  async embedBatch(texts: string[]): Promise<number[][]> {
+  async embedBatch(texts: string[], options?: EmbeddingRequestOptions): Promise<number[][]> {
     await ensureDiskCacheLoaded();
     const normalizedTexts = texts.map(normalizeText);
     const results: number[][] = new Array(texts.length);
@@ -562,6 +571,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
           `${this.config.baseUrl}/embeddings`,
           this.config.apiKey,
           body,
+          options,
         );
 
         this.trackUsage(response);
@@ -638,10 +648,14 @@ async function fetchWithRetry(
   url: string,
   apiKey: string,
   body: Record<string, unknown>,
+  options: EmbeddingRequestOptions = {},
   attempt = 0,
 ): Promise<EmbeddingAPIResponse> {
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 10_000);
+  const timeoutMs = typeof options.timeoutMs === 'number' && Number.isFinite(options.timeoutMs)
+    ? Math.max(100, Math.min(Math.floor(options.timeoutMs), 60_000))
+    : 10_000;
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
   let response: Response;
   try {
     response = await fetch(url, {
@@ -656,7 +670,7 @@ async function fetchWithRetry(
   } catch (err: unknown) {
     clearTimeout(timeout);
     if (err instanceof Error && err.name === 'AbortError') {
-      throw new Error(`Embedding API timeout after 10s: ${url}`);
+      throw new Error(`Embedding API timeout after ${timeoutMs}ms: ${url}`);
     }
     throw err;
   }
@@ -666,13 +680,13 @@ async function fetchWithRetry(
     return response.json() as Promise<EmbeddingAPIResponse>;
   }
 
-  if ((response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
+  if (options.retry !== false && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
     const delay = BASE_DELAY_MS * Math.pow(2, attempt);
     const retryAfter = response.headers.get('retry-after');
     const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : delay;
     console.error(`[memorix] Embedding API ${response.status}, retry ${attempt + 1}/${MAX_RETRIES} in ${waitMs}ms`);
     await new Promise(resolve => setTimeout(resolve, waitMs));
-    return fetchWithRetry(url, apiKey, body, attempt + 1);
+    return fetchWithRetry(url, apiKey, body, options, attempt + 1);
   }
 
   const errorText = await response.text().catch(() => 'unknown error');

package/src/embedding/provider.ts

@@ -27,15 +27,22 @@
  * Architecture inspired by Mem0's multi-provider embedding design.
  */
 
+export interface EmbeddingRequestOptions {
+  /** Bound one remote embedding request without changing the provider default. */
+  timeoutMs?: number;
+  /** Disable provider retries for latency-sensitive best-effort work. */
+  retry?: boolean;
+}
+
 export interface EmbeddingProvider {
   /** Provider name for logging/cache keys */
   readonly name: string;
   /** Vector dimensions (e.g., 384 for bge-small) */
   readonly dimensions: number;
   /** Generate embedding for a single text */
-  embed(text: string): Promise<number[]>;
+  embed(text: string, options?: EmbeddingRequestOptions): Promise<number[]>;
   /** Generate embeddings for multiple texts (batch) */
-  embedBatch(texts: string[]): Promise<number[][]>;
+  embedBatch(texts: string[], options?: EmbeddingRequestOptions): Promise<number[][]>;
   /** Return already-persisted embeddings without generating new vectors. */
   getCachedEmbeddings?(texts: string[]): Promise<(number[] | null)[]>;
 }
@@ -43,6 +50,10 @@ export interface EmbeddingProvider {
 export interface GetEmbeddingProviderOptions {
   /** Avoid remote API dimension probes while preparing a startup index. */
   allowNetworkProbe?: boolean;
+  /** Bound a remote API dimension probe for a latency-sensitive caller. */
+  requestTimeoutMs?: number;
+  /** Disable retries while resolving a best-effort provider. */
+  retry?: boolean;
 }
 
 /** Singleton provider instance (null = not available) */
@@ -205,9 +216,9 @@ function wrapProvider(candidate: EmbeddingProvider): EmbeddingProvider {
   return {
     name: candidate.name,
     dimensions: candidate.dimensions,
-    async embed(text: string): Promise<number[]> {
+    async embed(text: string, options?: EmbeddingRequestOptions): Promise<number[]> {
       try {
-        return await candidate.embed(text);
+        return await candidate.embed(text, options);
       } catch (error) {
         if (kind === 'api' && getEmbeddingMode() === 'auto' && isTemporaryEmbeddingFailure(error)) {
           warnOnce('[memorix] API embedding temporarily unavailable — switching to local fallback provider');
@@ -215,7 +226,7 @@ function wrapProvider(candidate: EmbeddingProvider): EmbeddingProvider {
           if (fallback) {
             provider = wrapProvider(fallback);
             warnOnce(`[memorix] Embedding fallback activated: ${provider.name} (${provider.dimensions}d)`);
-            return provider.embed(text);
+            return provider.embed(text, options);
           }
         }
 
@@ -225,9 +236,9 @@ function wrapProvider(candidate: EmbeddingProvider): EmbeddingProvider {
         throw error;
       }
     },
-    async embedBatch(texts: string[]): Promise<number[][]> {
+    async embedBatch(texts: string[], options?: EmbeddingRequestOptions): Promise<number[][]> {
       try {
-        return await candidate.embedBatch(texts);
+        return await candidate.embedBatch(texts, options);
       } catch (error) {
         if (kind === 'api' && getEmbeddingMode() === 'auto' && isTemporaryEmbeddingFailure(error)) {
           warnOnce('[memorix] API embedding temporarily unavailable — switching to local fallback provider');
@@ -235,7 +246,7 @@ function wrapProvider(candidate: EmbeddingProvider): EmbeddingProvider {
           if (fallback) {
             provider = wrapProvider(fallback);
             warnOnce(`[memorix] Embedding fallback activated: ${provider.name} (${provider.dimensions}d)`);
-            return provider.embedBatch(texts);
+            return provider.embedBatch(texts, options);
           }
         }
 
@@ -331,7 +342,7 @@ export async function getEmbeddingProvider(
 
     // API mode: remote embedding via OpenAI-compatible endpoint
     if (mode === 'api') {
-      const initialized = await createAPIProvider();
+      const initialized = await createAPIProvider(options);
       if (!initialized) return null;
       provider = wrapProvider(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
@@ -340,7 +351,7 @@ export async function getEmbeddingProvider(
 
     // Auto mode: try configured API first, then local fallbacks
     if (hasAPIEmbeddingConfig()) {
-      const initialized = await createAPIProvider();
+      const initialized = await createAPIProvider(options);
       if (initialized) {
         provider = wrapProvider(initialized);
         warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);

package/src/hooks/installers/index.ts

@@ -1247,6 +1247,8 @@ function getAgentRulesContent(agent?: AgentName, scope: 'project' | 'global' = '
     '- Include \x60filesModified\x60 when relevant',
     '- Use \x60topicKey\x60 for topics that evolve over time (prevents duplicates)',
     '- For "why" decisions, use \x60memorix_store_reasoning\x60',
+    '- For a stable fact, reusable procedure, or completed episode that merits deliberate long-term review, include \x60longTerm\x60 in \x60memorix_store\x60 with the appropriate kind and normally \x60scope: "project"\x60. It creates a candidate only: do not use it for routine updates, do not make project-derived evidence portable user memory, and do not assume it enters context until an operator qualifies and approves it through \x60memorix memory long-term\x60.',
+    '- A \x60user\x60 + \x60portable\x60 durable memory delivered in a task brief is intentionally available across projects. When it matches the task, use it as reusable background even if its origin differs; do not treat it as a current-project fact. Expand it only when needed with \x60memorix_detail\x60 using its \x60durable:<id>\x60 reference and a specific purpose.',
     '',
     "**Don't store:** greetings, simple file reads, trivial commands (ls, pwd, git status).",
     '',

package/src/knowledge/context-assembly.ts

@@ -18,6 +18,7 @@ export type ContextCandidateKind =
   | 'semantic-code'
   | 'start-here'
   | 'memory'
+  | 'durable-memory'
   | 'claim'
   | 'knowledge-page'
   | 'workflow'
@@ -43,7 +44,7 @@ export interface ContextReceiptOmission {
 }
 
 export interface ContextReceipt {
-  version: '1.2.4';
+  version: '1.3';
   target: ContextDeliveryTarget;
   elapsedMs: number;
   budget: {