memorix 1.9.5 → 1.9.7

package/src/config/resolved-config.ts

@@ -92,8 +92,8 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
   loadDotenv(projectRoot === null ? undefined : projectRoot ?? undefined, { userHomeDir: homeDir });
 
   const toml = loadTomlConfig({ projectRoot: projectRoot ?? null, homeDir });
-  const yaml = loadYamlConfig(projectRoot ?? null);
-  const legacy = loadFileConfig();
+  const yaml = loadYamlConfig(projectRoot ?? null, { homeDir });
+  const legacy = loadFileConfig(homeDir);
   const embeddingBaseUrl = first(process.env.MEMORIX_EMBEDDING_BASE_URL, toml.embedding?.base_url, yaml.embedding?.baseUrl, legacy.embeddingApi?.baseUrl);
   const openRouterEmbeddingApiKey = isOpenRouterUrl(embeddingBaseUrl) ? process.env.OPENROUTER_API_KEY : undefined;
   const memoryLlmProvider = first(
@@ -117,15 +117,17 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
   const openRouterMemoryLlmApiKey = isOpenRouterMemoryLane(memoryLlmProvider, memoryLlmBaseUrl)
     ? process.env.OPENROUTER_API_KEY
     : undefined;
+  const isAtlasCloud = memoryLlmProvider === 'atlascloud';
   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,
+    // Never borrow another provider's credentials for the Atlas Cloud preset.
+    isAtlasCloud ? process.env.ATLASCLOUD_API_KEY : process.env.OPENAI_API_KEY,
+    isAtlasCloud ? undefined : process.env.ANTHROPIC_API_KEY,
+    isAtlasCloud ? undefined : openRouterMemoryLlmApiKey,
   );
 
   const resolved: ResolvedMemorixConfig = {
@@ -321,6 +323,7 @@ function getEnvSourceNames(): string[] {
     'MEMORIX_CODEGRAPH_EXTERNAL_COMMAND',
     'MEMORIX_CODEGRAPH_EXTERNAL_TIMEOUT_MS',
     'OPENROUTER_API_KEY',
+    'ATLASCLOUD_API_KEY',
   ].filter((name) => process.env[name]);
 }
 

package/src/config/yaml-loader.ts

@@ -125,9 +125,17 @@ export interface MemorixYamlConfig {
 
 // ─── Loader ──────────────────────────────────────────────────────────
 
-// Per-project config cache — keyed by resolved projectRoot string.
-// null key = user-level-only config (no project root).
-const configCache = new Map<string | null, MemorixYamlConfig>();
+interface LoadYamlOptions {
+  homeDir?: string;
+}
+
+// Cache entries are scoped by both the user home and project root so test and
+// long-lived multi-project callers cannot reuse another configuration scope.
+const configCache = new Map<string, MemorixYamlConfig>();
+
+function cacheKey(homeDir: string, projectRoot: string | null): string {
+  return `${homeDir}\0${projectRoot ?? ''}`;
+}
 /** Stored project root — set once by server init, used by all no-arg loadYamlConfig() calls */
 let globalProjectRoot: string | null = null;
 
@@ -142,7 +150,7 @@ let globalProjectRoot: string | null = null;
 export function initProjectRoot(root: string): void {
   globalProjectRoot = root;
   // Invalidate this project's cache entry so file changes are picked up
-  configCache.delete(root);
+  configCache.delete(cacheKey(homedir(), root));
 }
 
 /**
@@ -157,16 +165,18 @@ export function clearProjectRoot(): void {
  * Load memorix.yml from project root and/or user home.
  * Project-level overrides user-level (shallow merge per top-level key).
  */
-export function loadYamlConfig(projectRoot?: string | null): MemorixYamlConfig {
+export function loadYamlConfig(projectRoot?: string | null, options: LoadYamlOptions = {}): MemorixYamlConfig {
+  const homeDir = options.homeDir ?? homedir();
   // When null is explicitly passed, skip global fallback (user-level config only).
   // When undefined (no arg), fall back to globally-initialized project root.
   const resolvedRoot = projectRoot === null ? null : (projectRoot ?? globalProjectRoot ?? null);
+  const key = cacheKey(homeDir, resolvedRoot);
 
   // Per-project cache hit
-  const cached = configCache.get(resolvedRoot ?? null);
+  const cached = configCache.get(key);
   if (cached) return cached;
 
-  const userYaml = getGlobalYamlPath(homedir());
+  const userYaml = getGlobalYamlPath(homeDir);
   const projectYaml = resolvedRoot ? getProjectYamlPath(resolvedRoot) : null;
 
   let userConfig: MemorixYamlConfig = {};
@@ -205,7 +215,7 @@ export function loadYamlConfig(projectRoot?: string | null): MemorixYamlConfig {
     server: { ...userConfig.server, ...projectConfig.server },
     team: { ...userConfig.team, ...projectConfig.team },
   };
-  configCache.set(resolvedRoot ?? null, merged);
+  configCache.set(key, merged);
 
   return merged;
 }
@@ -214,9 +224,9 @@ export function loadYamlConfig(projectRoot?: string | null): MemorixYamlConfig {
  * Reset cached YAML config (for testing or project switching).
  * Invalidates all cached entries, or a specific projectRoot if provided.
  */
-export function resetYamlConfigCache(projectRoot?: string | null): void {
+export function resetYamlConfigCache(projectRoot?: string | null, homeDir = homedir()): void {
   if (projectRoot !== undefined) {
-    configCache.delete(projectRoot ?? null);
+    configCache.delete(cacheKey(homeDir, projectRoot ?? null));
   } else {
     configCache.clear();
   }

package/src/embedding/api-provider.ts

@@ -99,7 +99,8 @@ function evictOldest(): void {
   if (old) cachePayloadBytes -= payloadBytes(old);
 }
 
-function evictToFit(incomingBytes: number, incomingDims: number): void {
+function evictToFit(incomingBytes: number, incomingDims: number): boolean {
+  if (incomingBytes > maxCachePayloadBytes()) return false;
   const limit = maxEntriesForDimensions(incomingDims);
   while (
     cache.size > 0 &&
@@ -107,6 +108,7 @@ function evictToFit(incomingBytes: number, incomingDims: number): void {
   ) {
     evictOldest();
   }
+  return true;
 }
 
 function isNumberArray(value: unknown): value is number[] {
@@ -139,7 +141,7 @@ function cacheInsert(hash: string, value: number[], dirty: boolean): void {
     cachePayloadBytes -= payloadBytes(existing);
     cache.delete(hash);
   }
-  evictToFit(incoming, value.length || cacheDimensions || DEFAULT_ASSUMED_DIMENSIONS);
+  if (!evictToFit(incoming, value.length || cacheDimensions || DEFAULT_ASSUMED_DIMENSIONS)) return;
   cache.set(hash, value);
   cachePayloadBytes += incoming;
   if (dirty) diskCacheDirty = true;

package/src/embedding/fastembed-provider.ts

@@ -30,6 +30,9 @@ const CACHE_FILE = join(CACHE_DIR, '.embedding-cache.json');
 // In-memory cache keyed by text hash → embedding
 const cache = new Map<string, number[]>();
 const MAX_CACHE_SIZE = 5000;
+const DEFAULT_CACHE_PAYLOAD_BYTES = 64 * 1024 * 1024;
+const MAX_CACHE_FILE_BYTES = 128 * 1024 * 1024;
+let cachePayloadBytes = 0;
 let diskCacheDirty = false;
 
 function textHash(text: string): string {
@@ -39,14 +42,53 @@ function textHash(text: string): string {
 async function loadDiskCache(): Promise<void> {
   try {
     const raw = await readFile(CACHE_FILE, 'utf-8');
-    const entries: [string, number[]][] = JSON.parse(raw);
-    for (const [k, v] of entries) cache.set(k, v);
-    console.error(`[memorix] Loaded ${entries.length} cached embeddings from disk`);
+    if (Buffer.byteLength(raw, 'utf8') > MAX_CACHE_FILE_BYTES) {
+      console.error('[memorix] FastEmbed cache exceeds the disk load limit; starting with an empty cache');
+      return;
+    }
+    const entries: unknown = JSON.parse(raw);
+    if (!Array.isArray(entries)) return;
+    for (const entry of entries) {
+      if (!Array.isArray(entry) || typeof entry[0] !== 'string' || !isVector(entry[1])) continue;
+      cacheSet(entry[0], entry[1], false);
+    }
+    console.error(`[memorix] Loaded ${cache.size} cached embeddings from disk`);
   } catch {
     // No cache file or corrupt — start fresh
   }
 }
 
+function isVector(value: unknown): value is number[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'number');
+}
+
+function maxCachePayloadBytes(): number {
+  const raw = Number.parseInt(process.env.MEMORIX_EMBEDDING_CACHE_MAX_BYTES ?? '', 10);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_CACHE_PAYLOAD_BYTES;
+}
+
+function cacheSet(hash: string, value: number[], markDirty = true): void {
+  const incomingBytes = value.length * 8;
+  if (incomingBytes > maxCachePayloadBytes()) return;
+  const existing = cache.get(hash);
+  if (existing) cachePayloadBytes -= existing.length * 8;
+  else {
+    while (
+      cache.size >= MAX_CACHE_SIZE
+      || cachePayloadBytes + incomingBytes > maxCachePayloadBytes()
+    ) {
+      const firstKey = cache.keys().next().value;
+      if (firstKey === undefined) break;
+      const old = cache.get(firstKey);
+      cache.delete(firstKey);
+      if (old) cachePayloadBytes -= old.length * 8;
+    }
+  }
+  cache.set(hash, value);
+  cachePayloadBytes += incomingBytes;
+  if (markDirty) diskCacheDirty = true;
+}
+
 async function saveDiskCache(): Promise<void> {
   if (!diskCacheDirty) return;
   try {
@@ -109,7 +151,7 @@ export class FastEmbedProvider implements EmbeddingProvider {
     if (result.length !== this.dimensions) {
       throw new Error(`Expected ${this.dimensions}d embedding, got ${result.length}d`);
     }
-    this.cacheSet(hash, result);
+    cacheSet(hash, result);
     return result;
   }
 
@@ -139,7 +181,7 @@ export class FastEmbedProvider implements EmbeddingProvider {
           const originalIdx = uncachedIndices[batchIdx];
           const plain = Array.from(vec) as number[];
           results[originalIdx] = plain;
-          this.cacheSet(textHash(uncachedTexts[batchIdx]), plain);
+          cacheSet(textHash(uncachedTexts[batchIdx]), plain);
           batchIdx++;
         }
       }
@@ -150,13 +192,4 @@ export class FastEmbedProvider implements EmbeddingProvider {
     return results;
   }
 
-  private cacheSet(hash: string, value: number[]): void {
-    // Evict oldest entries if cache is full
-    if (cache.size >= MAX_CACHE_SIZE) {
-      const firstKey = cache.keys().next().value;
-      if (firstKey !== undefined) cache.delete(firstKey);
-    }
-    cache.set(hash, value);
-    diskCacheDirty = true;
-  }
 }

package/src/embedding/transformers-provider.ts

@@ -23,10 +23,22 @@ import {
   type EmbeddingOptions,
   type EmbeddingProvider,
 } from './provider.js';
+import { createHash } from 'node:crypto';
 
 // In-memory LRU cache
 const cache = new Map<string, number[]>();
 const MAX_CACHE_SIZE = 5000;
+const DEFAULT_CACHE_PAYLOAD_BYTES = 64 * 1024 * 1024;
+let cachePayloadBytes = 0;
+
+function cacheKey(text: string): string {
+    return createHash('sha256').update(text).digest('hex');
+}
+
+function maxCachePayloadBytes(): number {
+    const raw = Number.parseInt(process.env.MEMORIX_EMBEDDING_CACHE_MAX_BYTES ?? '', 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_CACHE_PAYLOAD_BYTES;
+}
 
 export class TransformersProvider implements EmbeddingProvider {
     readonly name = 'transformers-minilm';
@@ -68,7 +80,7 @@ export class TransformersProvider implements EmbeddingProvider {
 
     async embed(text: string): Promise<number[]> {
         // Check cache first
-        const cached = cache.get(text);
+        const cached = cache.get(cacheKey(text));
         if (cached) return cached;
 
         const output = await this.extractor(text, {
@@ -82,7 +94,7 @@ export class TransformersProvider implements EmbeddingProvider {
             throw new Error(`Expected ${this.dimensions}d embedding, got ${result.length}d`);
         }
 
-        this.cacheSet(text, result);
+        this.cacheSet(cacheKey(text), result);
         return result;
     }
 
@@ -93,7 +105,7 @@ export class TransformersProvider implements EmbeddingProvider {
 
         // Check cache for each text
         for (let i = 0; i < texts.length; i++) {
-            const cached = cache.get(texts[i]);
+            const cached = cache.get(cacheKey(texts[i]));
             if (cached) {
                 results[i] = cached;
             } else {
@@ -114,7 +126,7 @@ export class TransformersProvider implements EmbeddingProvider {
                 const vec = Array.from(allVecs[i]) as number[];
                 const originalIdx = uncachedIndices[i];
                 results[originalIdx] = vec;
-                this.cacheSet(uncachedTexts[i], vec);
+                this.cacheSet(cacheKey(uncachedTexts[i]), vec);
             }
         }
 
@@ -122,10 +134,20 @@ export class TransformersProvider implements EmbeddingProvider {
     }
 
     private cacheSet(key: string, value: number[]): void {
-        if (cache.size >= MAX_CACHE_SIZE) {
-            const firstKey = cache.keys().next().value;
-            if (firstKey !== undefined) cache.delete(firstKey);
+        const incomingBytes = value.length * 8;
+        if (incomingBytes > maxCachePayloadBytes()) return;
+        const existing = cache.get(key);
+        if (existing) cachePayloadBytes -= existing.length * 8;
+        else {
+            while (cache.size >= MAX_CACHE_SIZE || cachePayloadBytes + incomingBytes > maxCachePayloadBytes()) {
+                const firstKey = cache.keys().next().value;
+                if (firstKey === undefined) break;
+                const old = cache.get(firstKey);
+                cache.delete(firstKey);
+                if (old) cachePayloadBytes -= old.length * 8;
+            }
         }
         cache.set(key, value);
+        cachePayloadBytes += incomingBytes;
     }
 }

package/src/evaluation/memory-quality-gate.ts

@@ -0,0 +1,90 @@
+/** Deterministic, model-free quality gate for cross-session memory delivery. */
+
+export interface MemoryQualitySample {
+  id: string;
+  expectedIds: string[];
+  shownIds: string[];
+  leakedProjectRows?: number;
+  staleRowsShown?: number;
+  shouldAbstain?: boolean;
+  tokens: number;
+  tokenBudget: number;
+  latencyMs: number;
+  rssBytes?: number;
+}
+
+export interface MemoryQualityGateScore {
+  cases: number;
+  recallAtK: number;
+  precisionAtK: number;
+  scopeIsolation: number;
+  staleRejection: number;
+  abstentionAccuracy: number;
+  overBudgetCases: number;
+  latencyP50Ms: number;
+  latencyP95Ms: number;
+  peakRssBytes: number;
+  passed: boolean;
+  failures: string[];
+}
+
+function rate(numerator: number, denominator: number): number {
+  return denominator === 0 ? 1 : numerator / denominator;
+}
+
+function percentile(values: number[], p: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.max(0, index)];
+}
+
+export function scoreMemoryQualityGate(samples: MemoryQualitySample[]): MemoryQualityGateScore {
+  let recalls = 0;
+  let precisionNumerator = 0;
+  let precisionDenominator = 0;
+  let isolated = 0;
+  let staleRejected = 0;
+  let abstentionCorrect = 0;
+  let overBudgetCases = 0;
+  const latencies = samples.map(sample => sample.latencyMs);
+  const failures: string[] = [];
+
+  for (const sample of samples) {
+    const expected = new Set(sample.expectedIds);
+    const shown = new Set(sample.shownIds);
+    if ([...expected].every(id => shown.has(id))) recalls++;
+    precisionNumerator += [...shown].filter(id => expected.has(id)).length;
+    precisionDenominator += shown.size;
+    if (!sample.leakedProjectRows) isolated++;
+    if (!sample.staleRowsShown) staleRejected++;
+    const abstained = shown.size === 0;
+    if (Boolean(sample.shouldAbstain) === abstained) abstentionCorrect++;
+    if (sample.tokens > sample.tokenBudget) overBudgetCases++;
+    if (sample.shouldAbstain && !abstained) failures.push(`${sample.id}: failed to abstain`);
+    if (!sample.shouldAbstain && ![...expected].every(id => shown.has(id))) failures.push(`${sample.id}: expected memory missing`);
+    if (sample.leakedProjectRows) failures.push(`${sample.id}: cross-project leakage`);
+    if (sample.staleRowsShown) failures.push(`${sample.id}: stale memory surfaced`);
+  }
+
+  const score: MemoryQualityGateScore = {
+    cases: samples.length,
+    recallAtK: rate(recalls, samples.length),
+    precisionAtK: rate(precisionNumerator, precisionDenominator),
+    scopeIsolation: rate(isolated, samples.length),
+    staleRejection: rate(staleRejected, samples.length),
+    abstentionAccuracy: rate(abstentionCorrect, samples.length),
+    overBudgetCases,
+    latencyP50Ms: percentile(latencies, 50),
+    latencyP95Ms: percentile(latencies, 95),
+    peakRssBytes: Math.max(0, ...samples.map(sample => sample.rssBytes ?? 0)),
+    passed: false,
+    failures,
+  };
+  score.passed = score.recallAtK === 1
+    && score.scopeIsolation === 1
+    && score.staleRejection === 1
+    && score.abstentionAccuracy === 1
+    && score.overBudgetCases === 0;
+  return score;
+}

package/src/hooks/official-skills.ts

@@ -40,6 +40,7 @@ export const OFFICIAL_MEMORIX_SKILLS: OfficialMemorixSkill[] = [
       '| Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |',
       '| Check source and freshness for a memory | `memorix_evidence` | `memorix evidence list|get|events` |',
       '| Record whether a memory helped, conflicted, or was corrected | `memorix_feedback` | `memorix feedback record|show|audit` |',
+      '| Track task requirements, decisions, verification, and outcome | `memorix_continuity` | `memorix continuity start|record|show|close` |',
       '| Inspect or import controlled media | `memorix_media` | `memorix media import|attach|list|show|status` |',
       '| Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |',
       '| Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |',
@@ -63,6 +64,7 @@ export const OFFICIAL_MEMORIX_SKILLS: OfficialMemorixSkill[] = [
       '3. Use stale or unbound memory only as a warning or search lead.',
       '4. Store durable decisions, fixes, and gotchas after the project state changes.',
       '5. Resolve completed or obsolete memories so future briefs stay small.',
+      '6. For multi-step work, start a continuity ledger and pass its taskId back to memorix_project_context.',
       '',
       '## Store Rules',
       '',

package/src/knowledge/context-assembly.ts

@@ -12,6 +12,7 @@ export type ContextDeliveryTarget =
 
 export type ContextCandidateKind =
   | 'task'
+  | 'continuity'
   | 'continuation'
   | 'current-fact'
   | 'code-state'

package/src/knowledge/context-receipt.ts

@@ -1,5 +1,6 @@
 import type { CodeGraphProviderQuality } from '../codegraph/types.js';
 import type { TaskWorkset } from './workset.js';
+import type { TaskContinuityLedger } from './task-continuity.js';
 
 /**
  * A small machine-readable counterpart to the agent-facing Workset prompt.
@@ -18,6 +19,11 @@ export interface BoundedContextReceipt {
     snapshotId?: string;
   };
   loadout?: TaskWorkset['agentLoadout'];
+  continuity?: {
+    taskId: string;
+    status: TaskContinuityLedger['status'];
+    outcome: TaskContinuityLedger['outcome'];
+  };
 }
 
 export function buildBoundedContextReceipt(input: {
@@ -37,5 +43,14 @@ export function buildBoundedContextReceipt(input: {
       ...(input.workset.provenance.snapshotId ? { snapshotId: input.workset.provenance.snapshotId } : {}),
     },
     ...(input.workset.agentLoadout ? { loadout: input.workset.agentLoadout } : {}),
+    ...(input.workset.continuity
+      ? {
+        continuity: {
+          taskId: input.workset.continuity.taskId,
+          status: input.workset.continuity.status,
+          outcome: input.workset.continuity.outcome,
+        },
+      }
+      : {}),
   };
 }