memorix 1.9.4 → 1.9.6

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/integrations/registry.ts

@@ -72,7 +72,7 @@ export const MEMORIX_INTEGRATIONS: MemorixIntegration[] = [
     status: 'ready',
     install: 'memorix setup --agent grok --global',
     surfaces: ['hooks', 'AGENTS.md'],
-    note: 'Writes ~/.grok/hooks/memorix.json and leaves Grok MCP host-owned; setup does not write config.toml.',
+    note: 'Writes ~/.grok/hooks/memorix.json and leaves Grok MCP host-owned by default. Pass --mcp http to write [mcp_servers.memorix] in Grok config.toml.',
   },
   {
     agent: 'cursor',

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,
+        },
+      }
+      : {}),
   };
 }