memorix 1.2.8 → 1.2.9

package/src/memory/retention.ts

@@ -319,6 +319,40 @@ export interface RetentionExplanation {
   summary: string;
 }
 
+/** Access metadata maintained outside the persisted observation record. */
+export type ObservationAccessMap = ReadonlyMap<number, {
+  accessCount: number;
+  lastAccessedAt: string;
+}>;
+
+/**
+ * One canonical retention result for a persisted observation.
+ *
+ * Consumers should use this projection instead of recreating a local decay
+ * formula. That keeps the UI, HTTP control plane, and archive worker aligned
+ * on the same retention state.
+ */
+export interface RetentionProjection extends RetentionExplanation {
+  relevance: RelevanceScore;
+  /** A backwards-compatible 0-10 display value derived from relevance. */
+  displayScore: number;
+  ageHours: number;
+  accessCount: number;
+  lastAccessedAt: string;
+}
+
+export interface ObservationRetentionProjectionOptions {
+  referenceTime?: Date;
+  accessMap?: ObservationAccessMap;
+}
+
+export interface RetentionProjectionSummary {
+  active: number;
+  stale: number;
+  archiveCandidates: number;
+  immune: number;
+}
+
 /**
  * Produce a structured explanation of why an observation has its current
  * retention posture.  Designed for operator-facing reporting.
@@ -371,27 +405,16 @@ export function explainRetention(
   };
 }
 
-// ── Auto-Archive ────────────────────────────────────────────────────
-
-export interface ArchiveExpiredBatchOptions {
-  projectId: string;
-  afterId?: number;
-  limit?: number;
-  referenceTime?: Date;
-  accessMap?: Map<number, { accessCount: number; lastAccessedAt: string }>;
-  /** Omit only for trusted background maintenance. */
-  reader?: ObservationReader;
-}
-
-export interface ArchiveExpiredBatchResult {
-  archived: number;
-  scanned: number;
-  nextCursor?: number;
-}
-
-function toRetentionDocument(
+/**
+ * Convert a stored observation into the search/retention document shape.
+ *
+ * Observation fields such as concepts are arrays, while the retrieval schema
+ * intentionally stores them as strings. Centralising that conversion prevents
+ * callers from accidentally feeding raw observations into retention helpers.
+ */
+export function toRetentionDocument(
   obs: Observation,
-  accessMap?: Map<number, { accessCount: number; lastAccessedAt: string }>,
+  accessMap?: ObservationAccessMap,
 ): MemorixDocument {
   const access = accessMap?.get(obs.id);
   return {
@@ -418,6 +441,62 @@ function toRetentionDocument(
   };
 }
 
+/** Build the canonical retention result used by every Observation consumer. */
+export function projectObservationRetention(
+  observation: Observation,
+  options: ObservationRetentionProjectionOptions = {},
+): RetentionProjection {
+  const document = toRetentionDocument(observation, options.accessMap);
+  const relevance = calculateRelevance(document, options.referenceTime);
+  const explanation = explainRetention(document, options.referenceTime);
+
+  return {
+    ...explanation,
+    relevance,
+    displayScore: Math.round(Math.min(10, relevance.totalScore * 10) * 100) / 100,
+    ageHours: Math.round(relevance.ageDays * 24 * 10) / 10,
+    accessCount: document.accessCount,
+    lastAccessedAt: document.lastAccessedAt,
+  };
+}
+
+/** Summarise canonical projections without reimplementing retention thresholds. */
+export function summarizeRetentionProjections(
+  projections: readonly Pick<RetentionProjection, 'zone' | 'immune'>[],
+): RetentionProjectionSummary {
+  let active = 0;
+  let stale = 0;
+  let archiveCandidates = 0;
+  let immune = 0;
+
+  for (const projection of projections) {
+    if (projection.zone === 'active') active++;
+    else if (projection.zone === 'stale') stale++;
+    else archiveCandidates++;
+    if (projection.immune) immune++;
+  }
+
+  return { active, stale, archiveCandidates, immune };
+}
+
+// ── Auto-Archive ────────────────────────────────────────────────────
+
+export interface ArchiveExpiredBatchOptions {
+  projectId: string;
+  afterId?: number;
+  limit?: number;
+  referenceTime?: Date;
+  accessMap?: ObservationAccessMap;
+  /** Omit only for trusted background maintenance. */
+  reader?: ObservationReader;
+}
+
+export interface ArchiveExpiredBatchResult {
+  archived: number;
+  scanned: number;
+  nextCursor?: number;
+}
+
 /**
  * Archive one bounded page of a project's active memories. The caller owns the
  * cursor, which makes the operation safe to run from a durable maintenance job.
@@ -438,10 +517,10 @@ export async function archiveExpiredBatch(
   const scanned = hasMore ? page.slice(0, limit) : page;
   const candidateIds = scanned
     .filter((observation) => !options.reader || canManageObservation(observation, options.reader))
-    .filter((observation) => getRetentionZone(
-      toRetentionDocument(observation, options.accessMap),
-      options.referenceTime,
-    ) === 'archive-candidate')
+    .filter((observation) => projectObservationRetention(observation, {
+      accessMap: options.accessMap,
+      referenceTime: options.referenceTime,
+    }).zone === 'archive-candidate')
     .map((observation) => observation.id);
 
   const archived = candidateIds.length === 0
@@ -474,7 +553,7 @@ export async function archiveExpiredBatch(
 export async function archiveExpired(
   projectDir: string,
   referenceTime?: Date,
-  accessMap?: Map<number, { accessCount: number; lastAccessedAt: string }>,
+  accessMap?: ObservationAccessMap,
   projectId?: string,
   reader?: ObservationReader,
 ): Promise<{ archived: number; remaining: number }> {
@@ -512,9 +591,8 @@ export async function archiveExpired(
     const archivedIds: number[] = [];
 
     for (const obs of activeObs) {
-      const doc = toRetentionDocument(obs, accessMap);
-      const zone = getRetentionZone(doc, referenceTime);
-      if (zone === 'archive-candidate') {
+      const retention = projectObservationRetention(obs, { accessMap, referenceTime });
+      if (retention.zone === 'archive-candidate') {
         archivedIds.push(obs.id);
       }
     }

package/src/memory/session.ts

@@ -21,7 +21,18 @@ import { KnowledgeGraphManager } from './graph.js';
 import { redactCredentials, sanitizeCredentials } from './secret-filter.js';
 import { canReadObservation } from './visibility.js';
 
-const PRIORITY_TYPES = new Set(['gotcha', 'decision', 'problem-solution', 'trade-off', 'discovery']);
+// Types eligible for L2 "Key Project Memories" injection. Session requests carry
+// the original goal and change records carry the latest outcome, so both matter
+// when an agent resumes work after a handoff.
+const PRIORITY_TYPES = new Set([
+  'gotcha',
+  'decision',
+  'problem-solution',
+  'trade-off',
+  'discovery',
+  'session-request',
+  'what-changed',
+]);
 const RESUME_TYPES = new Set([
   'gotcha',
   'decision',
@@ -31,7 +42,6 @@ const RESUME_TYPES = new Set([
   'how-it-works',
   'what-changed',
   'reasoning',
-  'session-request',
 ]);
 const TYPE_EMOJI: Record<string, string> = {
   'gotcha': '[DISCOVERY]',
@@ -50,19 +60,24 @@ const TYPE_WEIGHTS: Record<string, number> = {
   'decision': 5.5,
   'problem-solution': 5.25,
   'trade-off': 4.75,
+  'session-request': 4.5,
   'discovery': 4.25,
+  'what-changed': 4,
 };
+// Markers that identify a memory as a demo/scratch artifact rather than real
+// working context. These are TITLE conventions — see isNoiseObservation.
+//
+// Deliberately excluded: 验证 / 兼容 / compat / 交接 / handoff. Those are ordinary
+// engineering vocabulary, not noise signals. Matching them silently dropped real
+// memories: any Chinese note about verification or compatibility, and any handoff
+// note that merely named a handoff tool, disappeared from session context with no
+// diagnostic. A noise filter must not veto the words its users normally write.
 const NOISE_PATTERNS = [
   /\[测试\]/i,
   /\[test\]/i,
-  /验证/i,
-  /兼容/i,
-  /\bcompat(?:ibility)?\b/i,
   /\bdemo\b/i,
   /展示/i,
   /全能力/i,
-  /handoff/i,
-  /交接/i,
   /for_memmcp_test/i,
   /\bbenchmark\b/i,
   /\bsandbox\b/i,
@@ -180,8 +195,13 @@ function isCommandTrace(obs: Observation): boolean {
 }
 
 function isNoiseObservation(obs: Observation): boolean {
-  const text = stringifyObservation(obs, false);
-  return NOISE_PATTERNS.some((pattern) => pattern.test(text)) || isCommandTrace(obs);
+  // Match the title only. Demo/scratch markers are a titling convention, so scanning
+  // the narrative/facts/concepts produced false positives on real memories that merely
+  // *mentioned* one of these words in prose — and because this filter runs before the
+  // PRIORITY_TYPES check and drops the observation outright (not a score penalty), a
+  // single unlucky word in a long narrative made the whole memory unreachable.
+  const title = obs.title ?? '';
+  return NOISE_PATTERNS.some((pattern) => pattern.test(title)) || isCommandTrace(obs);
 }
 
 function isSystemSelfObservation(obs: Observation): boolean {
@@ -321,6 +341,42 @@ export async function getSessionResumeBrief(
   };
 }
 
+const AUTO_RESUME_SUMMARY_LIMIT = 480;
+const AUTO_RESUME_TITLE_LIMIT = 180;
+
+function compactResumeText(text: string, limit: number): string {
+  const normalized = text.replace(/\s+/g, ' ').trim();
+  return normalized.length <= limit ? normalized : `${normalized.slice(0, Math.max(0, limit - 3)).trimEnd()}...`;
+}
+
+/**
+ * Render the bounded automatic delivery form of a resume brief.
+ *
+ * Full session context remains available through getSessionContext() and
+ * individual memory details remain on demand. Automatic session start gets an
+ * index, not a transcript, so it cannot crowd out the new task's context.
+ */
+export function renderSessionResumeCard(brief: SessionResumeBrief): string {
+  if (!brief.previousSession && brief.memories.length === 0) return '';
+
+  const lines = ['## Memorix Resume'];
+  if (brief.previousSession) {
+    const agent = brief.previousSession.agent ? ` (${brief.previousSession.agent})` : '';
+    lines.push(`Previous session: ${brief.previousSession.id}${agent}`);
+    lines.push(compactResumeText(brief.previousSession.summary, AUTO_RESUME_SUMMARY_LIMIT));
+  }
+
+  if (brief.memories.length > 0) {
+    lines.push('', 'Relevant memory references:');
+    for (const memory of brief.memories) {
+      lines.push(`- #${memory.id} [${memory.type}] ${compactResumeText(memory.title, AUTO_RESUME_TITLE_LIMIT)}`);
+    }
+    lines.push('Read a listed memory only when its title is relevant to the current task.');
+  }
+
+  return lines.join('\n');
+}
+
 export function scoreObservationForSessionContext(obs: Observation, projectTokens: string[], now = Date.now()): number {
   let score = TYPE_WEIGHTS[obs.type] ?? 1;
   const text = stringifyObservation(obs);
@@ -384,7 +440,7 @@ export function scoreObservationForSessionContext(obs: Observation, projectToken
  * so the agent can resume work without re-explaining everything.
  */
 export async function startSession(
-  projectDir: string,
+  _projectDir: string,
   projectId: string,
   opts?: { sessionId?: string; agent?: string; reader?: ObservationReader },
 ): Promise<{ session: Session; previousContext: string }> {
@@ -399,8 +455,11 @@ export async function startSession(
     agent: opts?.agent,
   };
 
-  // Load previous context before creating new session
-  const previousContext = await getSessionContext(projectDir, projectId, 3, opts?.reader);
+  // Automatic delivery stays intentionally small. The explicit context tool can
+  // still provide the expanded packet when an agent chooses to inspect it.
+  const previousContext = renderSessionResumeCard(
+    await getSessionResumeBrief(projectId, undefined, opts?.reader),
+  );
 
   // Atomic rollover: complete all active sessions for this project's aliases
   // and insert the new session in a single SQLite transaction.

package/src/runtime/vector-backfill-runner.ts

@@ -0,0 +1,144 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadDotenv } from '../config/dotenv-loader.js';
+import { initProjectRoot } from '../config/yaml-loader.js';
+import { prepareSearchIndex, initObservations } from '../memory/observations.js';
+import { sanitizeCredentials } from '../memory/secret-filter.js';
+import { initObservationStore } from '../store/obs-store.js';
+import { getDeferredCachedVectorHydration } from '../store/orama-store.js';
+import { closeAllDatabases } from '../store/sqlite-db.js';
+import { MaintenanceJobStore, MaintenanceJobWorker } from './maintenance-jobs.js';
+import { createProjectMaintenanceHandler } from './project-maintenance.js';
+
+export interface VectorBackfillRequest {
+  projectId: string;
+  projectRoot: string;
+  dataDir: string;
+}
+
+export interface VectorBackfillLauncherOptions {
+  runnerPath?: string;
+  exists?: (path: string) => boolean;
+  spawn?: typeof spawn;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/** Resolve the standalone worker next to either the library or CLI bundle. */
+export function resolveVectorBackfillRunnerPath(moduleUrl = import.meta.url): string {
+  const moduleDir = path.dirname(fileURLToPath(moduleUrl));
+  const distDir = path.basename(moduleDir) === 'cli'
+    ? path.dirname(moduleDir)
+    : path.basename(moduleDir) === 'runtime' && path.basename(path.dirname(moduleDir)) === 'src'
+      ? path.join(path.dirname(path.dirname(moduleDir)), 'dist')
+      : moduleDir;
+  return path.join(distDir, 'vector-backfill-runner.js');
+}
+
+/** Parse the internal request passed from a short-lived CLI process. */
+export function parseVectorBackfillRequest(raw: string): VectorBackfillRequest {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error('Vector backfill runner received invalid JSON input');
+  }
+
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    !isNonEmptyString((value as VectorBackfillRequest).projectId) ||
+    !isNonEmptyString((value as VectorBackfillRequest).projectRoot) ||
+    !isNonEmptyString((value as VectorBackfillRequest).dataDir) ||
+    !path.isAbsolute((value as VectorBackfillRequest).projectRoot) ||
+    !path.isAbsolute((value as VectorBackfillRequest).dataDir)
+  ) {
+    throw new Error('Vector backfill runner received an invalid request');
+  }
+
+  return {
+    projectId: (value as VectorBackfillRequest).projectId,
+    projectRoot: (value as VectorBackfillRequest).projectRoot,
+    dataDir: (value as VectorBackfillRequest).dataDir,
+  };
+}
+
+/**
+ * Start a detached one-shot worker. The caller has already persisted the
+ * observation and durable vector job, so failure to start is recoverable by a
+ * later MCP or control-plane session.
+ */
+export function launchDetachedVectorBackfill(
+  request: VectorBackfillRequest,
+  options: VectorBackfillLauncherOptions = {},
+): boolean {
+  const runnerPath = options.runnerPath ?? resolveVectorBackfillRunnerPath();
+  const exists = options.exists ?? existsSync;
+  if (!exists(runnerPath)) return false;
+
+  try {
+    const child = (options.spawn ?? spawn)(process.execPath, [runnerPath], {
+      cwd: request.projectRoot,
+      detached: true,
+      stdio: 'ignore',
+      // The request contains only local project metadata, never credentials.
+      // Environment transport avoids a live stdin pipe keeping the CLI alive.
+      env: { ...process.env, MEMORIX_VECTOR_BACKFILL_REQUEST: JSON.stringify(request) },
+      windowsHide: true,
+    }) as ChildProcess;
+    child.once?.('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run one durable vector-backfill job without sharing the CLI event loop. */
+export async function executeVectorBackfill(request: VectorBackfillRequest) {
+  initProjectRoot(request.projectRoot);
+  loadDotenv(request.projectRoot);
+  await initObservationStore(request.dataDir);
+  await initObservations(request.dataDir);
+  await prepareSearchIndex();
+  await getDeferredCachedVectorHydration()?.catch(() => {});
+
+  const worker = new MaintenanceJobWorker(
+    new MaintenanceJobStore(request.dataDir),
+    createProjectMaintenanceHandler(request.projectId, request.dataDir, request.projectRoot),
+    { projectId: request.projectId, kinds: ['vector-backfill'] },
+  );
+  return worker.runOnce();
+}
+
+async function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { raw += chunk; });
+    process.stdin.once('error', reject);
+    process.stdin.once('end', () => resolve(raw));
+  });
+}
+
+export async function main(): Promise<void> {
+  try {
+    const raw = process.env.MEMORIX_VECTOR_BACKFILL_REQUEST ?? await readStdin();
+    await executeVectorBackfill(parseVectorBackfillRequest(raw));
+  } catch (error) {
+    const detail = sanitizeCredentials(error instanceof Error ? error.message : String(error));
+    process.stderr.write(`[memorix] vector backfill worker failed: ${detail}\n`);
+    process.exitCode = 1;
+  } finally {
+    closeAllDatabases();
+  }
+}
+
+if (process.argv[1] && process.argv[1].endsWith('vector-backfill-runner.js')) {
+  void main();
+}

package/src/search/intent-detector.ts

@@ -12,7 +12,7 @@ import type { ObservationType } from '../types.js';
 
 // ─── Types ───
 
-export type QueryIntent = 'why' | 'when' | 'how' | 'what_changed' | 'problem' | 'general';
+export type QueryIntent = 'why' | 'when' | 'how' | 'what_changed' | 'problem' | 'state' | 'general';
 
 export interface IntentResult {
   /** Detected intent category */
@@ -39,6 +39,30 @@ interface IntentPattern {
 }
 
 const INTENT_PATTERNS: IntentPattern[] = [
+  {
+    // Resumption queries — "where were we", "what's left". Weighted just above the
+    // others because these are asked at handoff time, when returning the current
+    // state matters more than returning the best semantic match.
+    intent: 'state',
+    patterns: [
+      /\bprogress\b/i,
+      /\bstatus\b/i,
+      /\bremaining\b/i,
+      /\bnext steps?\b/i,
+      /\bwhere (?:did|are) we\b/i,
+      /\bpick(?:ing)? up\b/i,
+      /\bresume\b/i,
+      /\bto-?do\b/i,
+      /进度/,
+      /做到哪/,
+      /下一步/,
+      /待办/,
+      /剩下/,
+      /继续/,
+      /接着做/,
+    ],
+    weight: 1.1,
+  },
   {
     intent: 'why',
     patterns: [
@@ -139,6 +163,12 @@ const INTENT_PATTERNS: IntentPattern[] = [
 // ─── Type Boost Maps ───
 
 const INTENT_TYPE_BOOSTS: Record<QueryIntent, Partial<Record<ObservationType, number>>> = {
+  state: {
+    'session-request': 2.5,
+    'what-changed': 2.0,
+    'discovery': 1.5,
+    'problem-solution': 1.2,
+  },
   why: {
     'decision': 3.0,
     'why-it-exists': 3.0,
@@ -198,6 +228,14 @@ const INTENT_SOURCE_BOOSTS: Partial<Record<QueryIntent, Partial<Record<'agent' |
 };
 
 const INTENT_FIELD_BOOSTS: Partial<Record<QueryIntent, Record<string, number>>> = {
+  state: {
+    title: 3,           // State notes are titled by topic — the title carries the signal
+    entityName: 1.5,
+    narrative: 2,
+    facts: 2.5,         // Progress lines usually live in facts
+    concepts: 1,
+    filesModified: 0.5,
+  },
   why: {
     title: 2,
     entityName: 1.5,

package/src/server.ts

@@ -3637,7 +3637,7 @@ export async function createMemorixServer(
   /**
    * memorix_session_start — Start a new coding session
    *
-   * Creates a session record and returns context from previous sessions.
+   * Creates a session record and returns a compact continuation card.
    * This is the entry point for session-aware memory management.
    */
   server.registerTool(
@@ -3645,10 +3645,10 @@ export async function createMemorixServer(
     {
       title: 'Start Session',
       description:
-        'Start a new coding session. Returns context from previous sessions so you can resume work seamlessly. ' +
-        'Call this at the beginning of a session to track activity and get injected context. ' +
+        'Start a new coding session. Returns a compact continuation card with the latest handoff and a few memory references. ' +
+        'Call this at the beginning of a session to track activity; retrieve a referenced memory only when it is relevant. ' +
         'Any previous active session for this project will be auto-closed. ' +
-        'By default this is lightweight: it binds the project, opens a session, and injects context only. ' +
+        'By default this is lightweight: it binds the project, opens a session, and avoids dumping full history into the new context. ' +
         'Coordination identity is opt-in via `joinTeam: true` or a separate `team_manage` join call.\n\n' +
         'IMPORTANT for HTTP/control-plane mode: pass `projectRoot` with the absolute path to your ' +
         'workspace root (e.g., the directory open in your IDE). Memorix uses this to detect the git ' +
@@ -3851,7 +3851,7 @@ export async function createMemorixServer(
       } catch { /* mini-skills not available yet — skip */ }
 
       if (result.previousContext) {
-        lines.push('---', '[TASK] **Context from previous sessions:**', '', result.previousContext);
+        lines.push('---', '[TASK] **Continuation card:**', '', result.previousContext);
       } else {
         lines.push('No previous session context found. This appears to be a fresh project.');
       }