memorix 1.2.8 → 1.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "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.2.8",
+  "version": "1.2.9",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

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

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "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.2.8",
+  "version": "1.2.9",
   "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.2.8",
+  "version": "1.2.9",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "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.2.8",
+  "version": "1.2.9",
   "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.2.8",
+  "version": "1.2.9",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/src/cli/commands/operator-shared.ts

@@ -110,7 +110,10 @@ export async function getCliProjectContext(options?: CliContextOptions): Promise
   } catch {
     // CLI reads remain available even if optional background maintenance metadata fails.
   }
-  await initObservations(dataDir);
+  await initObservations(dataDir, {
+    embeddingWriteMode: 'deferred',
+    projectRoot: project.rootPath,
+  });
   await initSessionStore(dataDir);
   const teamStore = await initTeamStore(dataDir);
 

package/src/cli/commands/serve-http.ts

@@ -24,6 +24,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { ObservationStore } from '../../store/obs-store.js';
 import { resolveToolProfile } from '../../server/tool-profile.js';
 import { scopeKnowledgeGraphToProject } from '../../memory/graph-scope.js';
+import { projectObservationRetention, summarizeRetentionProjections } from '../../memory/retention.js';
 import { canManageObservation, filterReadableObservations } from '../../memory/visibility.js';
 
 export const DEFAULT_SESSION_TIMEOUT_MS = 30 * 60 * 1000;
@@ -760,20 +761,7 @@ export default defineCommand({
           await initGraphStore(statsDataDir);
           const graph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
 
-          const observations = await loadDashboardProjectObservations(statsDataDir, statsProjectId, 'active') as Array<{
-            type?: string;
-            id?: number;
-            title?: string;
-            entityName?: string;
-            createdAt?: string;
-            source?: string;
-            commitHash?: string;
-            filesModified?: string[];
-            relatedEntities?: string[];
-            status?: string;
-            importance?: number;
-            accessCount?: number;
-          }>;
+          const observations = await loadDashboardProjectObservations(statsDataDir, statsProjectId, 'active');
           const statsStore = await getDashboardObservationStore(statsDataDir);
           const nextId = await statsStore.loadIdCounter();
           const typeCounts: Record<string, number> = {};
@@ -811,20 +799,17 @@ export default defineCommand({
             filesModified: o.filesModified,
           }));
 
-          let retentionSummary = { active: 0, stale: 0, archive: 0, immune: 0 };
-          for (const obs of observations) {
-            const age = now - new Date(obs.createdAt || now).getTime();
-            const ageHours = age / (1000 * 60 * 60);
-            const importance = obs.importance ?? 5;
-            const accessCount = obs.accessCount ?? 0;
-            const lambda = 0.01;
-            const score = Math.min(importance * Math.exp(-lambda * ageHours) + Math.min(accessCount * 0.5, 3), 10);
-            const isImmune = importance >= 8 || obs.type === 'gotcha' || obs.type === 'decision';
-            if (isImmune) retentionSummary.immune++;
-            if (score >= 3) retentionSummary.active++;
-            else if (score >= 1) retentionSummary.stale++;
-            else retentionSummary.archive++;
-          }
+          const retention = summarizeRetentionProjections(
+            observations
+              .filter((observation) => observation.type !== 'probe')
+              .map((observation) => projectObservationRetention(observation, { referenceTime: new Date(now) })),
+          );
+          const retentionSummary = {
+            active: retention.active,
+            stale: retention.stale,
+            archive: retention.archiveCandidates,
+            immune: retention.immune,
+          };
 
           const sorted = [...observations].filter(o => o.type !== 'probe').sort((a, b) => (b.id || 0) - (a.id || 0)).slice(0, 10);
 
@@ -959,26 +944,38 @@ export default defineCommand({
 
         if (apiPath === '/retention') {
           const { projectId: retProjectId, dataDir: retDataDir } = await resolveRequestProject(url);
-          const observations = await loadDashboardProjectObservations(retDataDir, retProjectId, 'active') as Array<{ id?: number; title?: string; type?: string; importance?: number; accessCount?: number; lastAccessedAt?: string; createdAt?: string; entityName?: string }>;
-          const now = Date.now();
-          const scored = observations.map(obs => {
-            const age = now - new Date(obs.createdAt || now).getTime();
-            const ageHours = age / (1000 * 60 * 60);
-            const importance = obs.importance ?? 5;
-            const accessCount = obs.accessCount ?? 0;
-            const lambda = 0.01;
-            const decayScore = importance * Math.exp(-lambda * ageHours);
-            const accessBonus = Math.min(accessCount * 0.5, 3);
-            const score = Math.min(decayScore + accessBonus, 10);
-            const isImmune = importance >= 8 || obs.type === 'gotcha' || obs.type === 'decision';
-            return { id: obs.id, title: obs.title, type: obs.type, entityName: obs.entityName, score: Math.round(score * 100) / 100, isImmune, ageHours: Math.round(ageHours * 10) / 10, accessCount };
+          const observations = await loadDashboardProjectObservations(retDataDir, retProjectId, 'active');
+          const referenceTime = new Date();
+          const rows = observations
+            .filter((observation) => observation.type !== 'probe')
+            .map((observation) => ({
+              observation,
+              retention: projectObservationRetention(observation, { referenceTime }),
+            }))
+            .sort((a, b) => b.retention.displayScore - a.retention.displayScore);
+          const summary = summarizeRetentionProjections(rows.map((row) => row.retention));
+          const items = rows.map(({ observation, retention }) => ({
+            id: observation.id,
+            title: observation.title,
+            type: observation.type,
+            entityName: observation.entityName,
+            score: retention.displayScore,
+            isImmune: retention.immune,
+            zone: retention.zone,
+            ageHours: retention.ageHours,
+            accessCount: retention.accessCount,
+            effectiveRetentionDays: retention.effectiveRetentionDays,
+            immunityReason: retention.immunityReason,
+          }));
+          sendJson({
+            summary: {
+              active: summary.active,
+              stale: summary.stale,
+              archive: summary.archiveCandidates,
+              immune: summary.immune,
+            },
+            items,
           });
-          scored.sort((a, b) => b.score - a.score);
-          const activeCount = scored.filter(s => s.score >= 3).length;
-          const staleCount = scored.filter(s => s.score < 3 && s.score >= 1).length;
-          const archiveCount = scored.filter(s => s.score < 1).length;
-          const immuneCount = scored.filter(s => s.isImmune).length;
-          sendJson({ summary: { active: activeCount, stale: staleCount, archive: archiveCount, immune: immuneCount }, items: scored });
           return;
         }
 

package/src/dashboard/server.ts

@@ -23,6 +23,7 @@ import { resetDotenv } from '../config/dotenv-loader.js';
 import { initProjectRoot } from '../config/yaml-loader.js';
 import { clearProjectRoot } from '../config/yaml-loader.js';
 import { scopeKnowledgeGraphToProject } from '../memory/graph-scope.js';
+import { projectObservationRetention, summarizeRetentionProjections } from '../memory/retention.js';
 import { canManageObservation, filterReadableObservations } from '../memory/visibility.js';
 import type { Observation } from '../types.js';
 
@@ -249,7 +250,7 @@ async function handleApi(
                 const observations = filterDashboardObservations(
                     await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }),
                     effectiveProjectId,
-                ) as Array<{ type?: string; id?: number; createdAt?: string; title?: string; entityName?: string; relatedEntities?: string[]; status?: string }>;
+                );
                 const nextId = await getObservationStore().loadIdCounter();
 
                 // Project-scoped graph counts (must match /api/graph and /api/export)
@@ -290,21 +291,18 @@ async function handleApi(
                     filesModified: (o as any).filesModified,
                 }));
 
-                // Retention summary
-                let retentionSummary = { active: 0, stale: 0, archive: 0, immune: 0 };
-                for (const obs of observations) {
-                    const age = now - new Date((obs as any).createdAt || now).getTime();
-                    const ageHours = age / (1000 * 60 * 60);
-                    const importance = (obs as any).importance ?? 5;
-                    const accessCount = (obs as any).accessCount ?? 0;
-                    const lambda = 0.01;
-                    const score = Math.min(importance * Math.exp(-lambda * ageHours) + Math.min(accessCount * 0.5, 3), 10);
-                    const isImmune = importance >= 8 || obs.type === 'gotcha' || obs.type === 'decision';
-                    if (isImmune) retentionSummary.immune++;
-                    if (score >= 3) retentionSummary.active++;
-                    else if (score >= 1) retentionSummary.stale++;
-                    else retentionSummary.archive++;
-                }
+                const retentionReferenceTime = new Date(now);
+                const retention = summarizeRetentionProjections(
+                    observations
+                        .filter((observation) => observation.type !== 'probe')
+                        .map((observation) => projectObservationRetention(observation, { referenceTime: retentionReferenceTime })),
+                );
+                const retentionSummary = {
+                    active: retention.active,
+                    stale: retention.stale,
+                    archive: retention.archiveCandidates,
+                    immune: retention.immune,
+                };
 
                 // Recent observations (last 10, exclude probe)
                 const sorted = [...observations].filter(o => o.type !== 'probe')
@@ -399,56 +397,38 @@ async function handleApi(
                 const observations = filterDashboardObservations(
                     await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }),
                     effectiveProjectId,
-                ) as Array<{
-                    id?: number;
-                    title?: string;
-                    type?: string;
-                    importance?: number;
-                    accessCount?: number;
-                    lastAccessedAt?: string;
-                    createdAt?: string;
-                    entityName?: string;
-                }>;
-
-                const now = Date.now();
-                // Exclude probe from retention display -- not durable knowledge
-                const scored = observations.filter(obs => obs.type !== 'probe').map((obs) => {
-                    const age = now - new Date(obs.createdAt || now).getTime();
-                    const ageHours = age / (1000 * 60 * 60);
-                    const importance = obs.importance ?? 5;
-                    const accessCount = obs.accessCount ?? 0;
-
-                    // Exponential decay: score = importance * e^(-λt) + access_bonus
-                    const lambda = 0.01;
-                    const decayScore = importance * Math.exp(-lambda * ageHours);
-                    const accessBonus = Math.min(accessCount * 0.5, 3);
-                    const score = Math.min(decayScore + accessBonus, 10);
-
-                    // Immune if importance >= 8 or type is 'gotcha' or 'decision'
-                    const isImmune = importance >= 8 || obs.type === 'gotcha' || obs.type === 'decision';
-
-                    return {
-                        id: obs.id,
-                        title: obs.title,
-                        type: obs.type,
-                        entityName: obs.entityName,
-                        score: Math.round(score * 100) / 100,
-                        isImmune,
-                        ageHours: Math.round(ageHours * 10) / 10,
-                        accessCount,
-                    };
-                });
-
-                // Sort by score descending
-                scored.sort((a, b) => b.score - a.score);
+                );
 
-                const activeCount = scored.filter((s) => s.score >= 3).length;
-                const staleCount = scored.filter((s) => s.score < 3 && s.score >= 1).length;
-                const archiveCount = scored.filter((s) => s.score < 1).length;
-                const immuneCount = scored.filter((s) => s.isImmune).length;
+                const referenceTime = new Date();
+                const rows = observations
+                    .filter((observation) => observation.type !== 'probe')
+                    .map((observation) => ({
+                        observation,
+                        retention: projectObservationRetention(observation, { referenceTime }),
+                    }))
+                    .sort((a, b) => b.retention.displayScore - a.retention.displayScore);
+                const summary = summarizeRetentionProjections(rows.map((row) => row.retention));
+                const scored = rows.map(({ observation, retention }) => ({
+                    id: observation.id,
+                    title: observation.title,
+                    type: observation.type,
+                    entityName: observation.entityName,
+                    score: retention.displayScore,
+                    isImmune: retention.immune,
+                    zone: retention.zone,
+                    ageHours: retention.ageHours,
+                    accessCount: retention.accessCount,
+                    effectiveRetentionDays: retention.effectiveRetentionDays,
+                    immunityReason: retention.immunityReason,
+                }));
 
                 sendJson(res, {
-                    summary: { active: activeCount, stale: staleCount, archive: archiveCount, immune: immuneCount },
+                    summary: {
+                        active: summary.active,
+                        stale: summary.stale,
+                        archive: summary.archiveCandidates,
+                        immune: summary.immune,
+                    },
                     items: scored,
                 });
                 break;

package/src/memory/observations.ts

@@ -49,6 +49,17 @@ let observations: Observation[] = [];
 let nextId = 1;
 let projectDir: string | null = null;
 let searchIndexPrepared = false;
+export type ObservationEmbeddingWriteMode = 'background' | 'deferred';
+
+export interface ObservationRuntimeOptions {
+  /** Defer remote/local embedding to a detached worker for short-lived CLI writes. */
+  embeddingWriteMode?: ObservationEmbeddingWriteMode;
+  /** Git root used by the detached vector worker. */
+  projectRoot?: string;
+}
+
+let embeddingWriteMode: ObservationEmbeddingWriteMode = 'background';
+let embeddingWorkerProjectRoot: string | undefined;
 
 // ── Vector-missing tracking ──────────────────────────────────────
 // Tracks observation IDs whose async embedding write failed or was skipped.
@@ -106,7 +117,10 @@ function vectorBackfillError(error: unknown): string {
   return sanitizeCredentials(normalizeEmbeddingFailure(error).message).slice(0, 1_000);
 }
 
-function queueVectorBackfill(projectId: string): void {
+function queueVectorBackfill(
+  projectId: string,
+  options: { detachedWorker?: boolean; projectRoot?: string } = {},
+): void {
   const dataDir = projectDir;
   if (!dataDir) return;
   void import('../runtime/maintenance-jobs.js')
@@ -117,6 +131,19 @@ function queueVectorBackfill(projectId: string): void {
         dedupeKey: 'vector-backfill',
         payload: { limit: 12 },
       });
+      if (options.detachedWorker && options.projectRoot) {
+        void import('../runtime/vector-backfill-runner.js')
+          .then(({ launchDetachedVectorBackfill }) => {
+            launchDetachedVectorBackfill({
+              projectId,
+              projectRoot: options.projectRoot!,
+              dataDir,
+            });
+          })
+          .catch(() => {
+            // The durable queue remains available to a later MCP session.
+          });
+      }
     })
     .catch(() => {
       // Memory writes remain durable even when the optional maintenance queue is unavailable.
@@ -199,7 +226,12 @@ async function upgradeVectorSchemaAfterFirstEmbedding(embedding: number[]): Prom
  * Initialize the observations manager with a project directory.
  * Auto-initializes the ObservationStore if not already set.
  */
-export async function initObservations(dir: string): Promise<void> {
+export async function initObservations(
+  dir: string,
+  options: ObservationRuntimeOptions = {},
+): Promise<void> {
+  embeddingWriteMode = options.embeddingWriteMode ?? 'background';
+  embeddingWorkerProjectRoot = options.projectRoot;
   if (projectDir === dir) return;
   await initObservationStore(dir);
   const store = getObservationStore();
@@ -210,6 +242,70 @@ export async function initObservations(dir: string): Promise<void> {
   vectorSchemaUpgradePromise = null;
 }
 
+function scheduleObservationEmbedding(input: {
+  observationId: number;
+  projectId: string;
+  searchableText: string;
+  doc: MemorixDocument;
+}): void {
+  const { observationId, projectId, searchableText, doc } = input;
+  vectorMissingIds.add(observationId);
+
+  // A network fetch keeps Node's event loop alive even when its Promise is not
+  // awaited. One-shot CLI commands therefore persist first and let a detached
+  // worker consume the same durable queue.
+  if (embeddingWriteMode === 'deferred') {
+    if (isEmbeddingExplicitlyDisabled()) {
+      vectorMissingIds.delete(observationId);
+      return;
+    }
+    queueVectorBackfill(projectId, {
+      detachedWorker: true,
+      projectRoot: embeddingWorkerProjectRoot,
+    });
+    return;
+  }
+
+  void generateEmbedding(searchableText).then(async (embedding) => {
+    if (embedding) {
+      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
+        await upgradeVectorSchemaAfterFirstEmbedding(embedding);
+      }
+      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
+        const vectorDimensions = getVectorDimensions();
+        console.error(
+          `[memorix] Embedding dimension mismatch for obs-${observationId}: provider returned ${embedding.length}d, index expects ${vectorDimensions ?? 'unknown'}d (kept in backfill queue)`,
+        );
+        queueVectorBackfill(projectId);
+        return;
+      }
+      try {
+        await removeObservation(makeOramaObservationId(projectId, observationId));
+        await insertObservation(Object.assign({}, doc, { embedding }));
+        vectorMissingIds.delete(observationId);
+      } catch {
+        console.error(`[memorix] Embedding index update failed for obs-${observationId} (kept in backfill queue)`);
+        queueVectorBackfill(projectId);
+      }
+    } else if (isEmbeddingExplicitlyDisabled()) {
+      vectorMissingIds.delete(observationId);
+    } else {
+      queueVectorBackfill(projectId);
+      logEmbeddingFailureOnce(
+        'provider-unavailable',
+        `[memorix] Embedding provider unavailable (using BM25 until embedding recovers; queued obs-${observationId} for retry)`,
+      );
+    }
+  }).catch((err) => {
+    queueVectorBackfill(projectId);
+    const failure = normalizeEmbeddingFailure(err);
+    logEmbeddingFailureOnce(
+      failure.key,
+      `[memorix] Async embedding failed (using BM25 until embedding recovers; queued obs-${observationId} for retry): ${failure.message}`,
+    );
+  });
+}
+
 /**
  * Check cross-process freshness and reload if another process has written.
  *
@@ -507,49 +603,11 @@ export async function storeObservation(input: {
     queueClaimDerivation(observation);
   }
 
-  // Generate embedding async (fire-and-forget) — never blocks MCP response
-  // Track in vectorMissingIds until embedding is successfully written.
-  const obsId = observation.id;
-  vectorMissingIds.add(obsId);
-  const searchableText = [input.title, input.narrative, ...(input.facts ?? [])].join(' ');
-  generateEmbedding(searchableText).then(async (embedding) => {
-    if (embedding) {
-      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
-        await upgradeVectorSchemaAfterFirstEmbedding(embedding);
-      }
-      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
-        const vectorDimensions = getVectorDimensions();
-        console.error(
-          `[memorix] Embedding dimension mismatch for obs-${obsId}: provider returned ${embedding.length}d, index expects ${vectorDimensions ?? 'unknown'}d (kept in backfill queue)`,
-        );
-        queueVectorBackfill(input.projectId);
-        return;
-      }
-      try {
-        const { removeObservation: removeObs } = await import('../store/orama-store.js');
-        await removeObs(makeOramaObservationId(input.projectId, obsId));
-        await insertObservation(Object.assign({}, doc, { embedding }));
-        vectorMissingIds.delete(obsId);
-      } catch {
-        console.error(`[memorix] Embedding index update failed for obs-${obsId} (kept in backfill queue)`);
-        queueVectorBackfill(input.projectId);
-      }
-    } else if (isEmbeddingExplicitlyDisabled()) {
-      vectorMissingIds.delete(obsId);
-    } else {
-      queueVectorBackfill(input.projectId);
-      logEmbeddingFailureOnce(
-        'provider-unavailable',
-        `[memorix] Embedding provider unavailable (using BM25 until embedding recovers; queued obs-${obsId} for retry)`,
-      );
-    }
-  }).catch((err) => {
-    queueVectorBackfill(input.projectId);
-    const failure = normalizeEmbeddingFailure(err);
-    logEmbeddingFailureOnce(
-      failure.key,
-      `[memorix] Async embedding failed (using BM25 until embedding recovers; queued obs-${obsId} for retry): ${failure.message}`,
-    );
+  scheduleObservationEmbedding({
+    observationId: observation.id,
+    projectId: input.projectId,
+    searchableText: [input.title, input.narrative, ...(input.facts ?? [])].join(' '),
+    doc,
   });
 
   return { observation, upserted: false };
@@ -678,40 +736,11 @@ async function upsertObservation(
     queueClaimDerivation(existing);
   }
 
-  // Generate embedding async (fire-and-forget) — never blocks MCP response
-  const searchableText = [input.title, input.narrative, ...(input.facts ?? [])].join(' ');
-  const obsId = existing.id;
-  vectorMissingIds.add(obsId);
-  generateEmbedding(searchableText).then(async (embedding) => {
-    if (embedding) {
-      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
-        await upgradeVectorSchemaAfterFirstEmbedding(embedding);
-      }
-      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
-        queueVectorBackfill(existing.projectId);
-        return;
-      }
-      try {
-        const { removeObservation: removeObs } = await import('../store/orama-store.js');
-        await removeObs(makeOramaObservationId(existing.projectId, obsId));
-        await insertObservation(Object.assign({}, doc, { embedding }));
-        vectorMissingIds.delete(obsId);
-      } catch {
-        // Embedding index update failed — observation still persisted without vector
-        queueVectorBackfill(existing.projectId);
-      }
-    } else if (isEmbeddingExplicitlyDisabled()) {
-      vectorMissingIds.delete(obsId);
-    } else {
-      queueVectorBackfill(existing.projectId);
-    }
-  }).catch((err) => {
-    queueVectorBackfill(existing.projectId);
-    const failure = normalizeEmbeddingFailure(err);
-    logEmbeddingFailureOnce(
-      failure.key,
-      `[memorix] Async embedding failed (using BM25 until embedding recovers; queued obs-${obsId} for retry): ${failure.message}`,
-    );
+  scheduleObservationEmbedding({
+    observationId: existing.id,
+    projectId: existing.projectId,
+    searchableText: [input.title, input.narrative, ...(input.facts ?? [])].join(' '),
+    doc,
   });
 
   return existing;