memorix 1.2.6 → 1.2.7

package/src/cli/index.ts

@@ -1050,6 +1050,7 @@ const main = defineCommand({
     resume: () => import('./commands/resume.js').then(m => m.default),
     explain: () => import('./commands/explain.js').then(m => m.default),
     codegraph: () => import('./commands/codegraph.js').then(m => m.default),
+    checkpoint: () => import('./commands/checkpoint.js').then(m => m.default),
     knowledge: () => import('./commands/knowledge.js').then(m => m.default),
     reasoning: () => import('./commands/reasoning.js').then(m => m.default),
     retention: () => import('./commands/retention.js').then(m => m.default),
@@ -1118,7 +1119,7 @@ const main = defineCommand({
     // Detect by checking if the first CLI arg matches a registered subcommand name.
     const firstArg = process.argv[2];
     const knownSubs = ['ask', 'search', 'remember', 'recent', 'help', 'workbench', 'memcode', 'config',
-      'init', 'setup', 'integrate', 'memory', 'context', 'resume', 'explain', 'codegraph', 'knowledge', 'reasoning', 'retention', 'formation', 'audit', 'transfer', 'skills', 'identity',
+      'init', 'setup', 'integrate', 'memory', 'context', 'resume', 'explain', 'codegraph', 'checkpoint', 'knowledge', 'reasoning', 'retention', 'formation', 'audit', 'transfer', 'skills', 'identity',
       'session', 'team', 'task', 'message', 'lock', 'handoff', 'poll',
       'receipt',
       'serve', 'serve-http', 'status', 'sync',
@@ -1161,6 +1162,7 @@ const main = defineCommand({
       console.error('  resume     Resume prior work with one bounded project brief');
       console.error('  explain    Explain where Memorix project context comes from');
       console.error('  codegraph  Refresh/status/context-pack for CodeGraph Memory');
+      console.error('  checkpoint Inspect native compact continuity checkpoints');
       console.error('  knowledge  Review source-backed knowledge pages and project workflows');
       console.error('  reasoning  Store/search decision rationale');
       console.error('  retention  Inspect stale/archive status');

package/src/codegraph/auto-context.ts

@@ -2,7 +2,12 @@ import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { truncateToTokenBudget } from '../compact/token-budget.js';
 import { getResolvedConfig } from '../config/resolved-config.js';
-import { buildTaskWorkset, type TaskWorkset, type WorksetCaution } from '../knowledge/workset.js';
+import {
+  buildTaskWorkset,
+  type TaskWorkset,
+  type WorksetCaution,
+  type WorksetContinuation,
+} from '../knowledge/workset.js';
 import type { ContextDeliveryTarget } from '../knowledge/context-assembly.js';
 import { sanitizeCredentials } from '../memory/secret-filter.js';
 import type { ObservationReader, ProjectInfo } from '../types.js';
@@ -23,7 +28,7 @@ import {
 } from './project-context.js';
 import { CodeGraphStore } from './store.js';
 import { isEligibleForAutomaticDelivery } from '../memory/admission.js';
-import { getSessionResumeBrief, type SessionResumeBrief } from '../memory/session.js';
+import { getSessionResumeBrief } from '../memory/session.js';
 import { initSessionStore } from '../store/session-store.js';
 import {
   isContinuationTask,
@@ -56,7 +61,7 @@ export interface AutoProjectContext {
   refresh: AutoContextRefreshResult;
   providerQuality: CodeGraphProviderQuality;
   /** Present only when the caller asked to continue prior work. */
-  continuation?: SessionResumeBrief;
+  continuation?: WorksetContinuation;
   workset: TaskWorkset;
 }
 
@@ -72,6 +77,7 @@ export interface AutoProjectBrief {
 }
 
 const DEFAULT_MAX_AGE_MS = 10 * 60 * 1000;
+const COMPACT_CHECKPOINT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
 function activeProjectObservations(
   observations: ProjectContextObservation[],
@@ -134,6 +140,14 @@ export async function buildAutoProjectContext(input: {
   reader?: ObservationReader;
   /** Auto detects continuation language; always is used by the explicit resume path. */
   continuation?: 'auto' | 'always' | 'never';
+  /**
+   * Suppress a checkpoint already delivered through a host-native channel in
+   * this exact session. Other agents and later sessions remain eligible.
+   */
+  excludeCompactionCheckpointFor?: {
+    sessionId: string;
+    agent: string;
+  };
   /**
    * When supplied, a needed refresh is queued instead of running in this
    * request. MCP and hook callers use this to keep their response path fast.
@@ -294,10 +308,34 @@ export async function buildAutoProjectContext(input: {
   // Project Context is also used by lightweight callers that have not touched
   // session APIs yet. Initialize only when continuation was requested so a
   // normal Workset remains independent of session persistence.
-  let continuation: SessionResumeBrief | undefined;
+  let continuation: WorksetContinuation | undefined;
   if (continuationRequested) {
     await initSessionStore(input.dataDir);
     continuation = await getSessionResumeBrief(input.project.id, task, input.reader);
+    const { CompactionCheckpointStore } = await import('../store/compaction-checkpoint-store.js');
+    const checkpoint = new CompactionCheckpointStore(input.dataDir).findLatestCompleted(
+      input.project.id,
+      input.excludeCompactionCheckpointFor
+        ? { excludeSession: input.excludeCompactionCheckpointFor }
+        : undefined,
+    );
+    const completedAtMs = checkpoint ? Date.parse(checkpoint.completedAt ?? checkpoint.preCapturedAt) : Number.NaN;
+    if (
+      checkpoint
+      && Number.isFinite(completedAtMs)
+      && completedAtMs <= now.getTime()
+      && now.getTime() - completedAtMs <= COMPACT_CHECKPOINT_MAX_AGE_MS
+    ) {
+      continuation.compactCheckpoint = {
+        id: checkpoint.id,
+        agent: checkpoint.agent,
+        captureKind: checkpoint.captureKind === 'native-summary' ? 'native-summary' : 'lifecycle',
+        reason: checkpoint.reason,
+        ...(checkpoint.completedAt ? { completedAt: checkpoint.completedAt } : {}),
+        summary: checkpoint.summary
+          ?? 'The host completed context compaction without exposing a native summary. Reconstruct only what the current task needs from current code and durable evidence.',
+      };
+    }
   }
   const workset = await buildTaskWorkset({
     projectId: input.project.id,
@@ -564,7 +602,7 @@ export function formatAutoProjectContextSummary(context: AutoProjectContext): st
   );
 
   const continuation = context.workset.continuation;
-  if (continuation?.previousSession || continuation?.memories.length) {
+  if (continuation?.previousSession || continuation?.memories.length || continuation?.compactCheckpoint) {
     lines.push('', 'Resume from prior work');
     if (continuation.previousSession) {
       const session = continuation.previousSession;
@@ -584,6 +622,14 @@ export function formatAutoProjectContextSummary(context: AutoProjectContext): st
           + detail,
       );
     }
+    if (continuation.compactCheckpoint) {
+      const checkpoint = continuation.compactCheckpoint;
+      lines.push(
+        '- Recent host compact checkpoint ('
+          + [checkpoint.agent, checkpoint.captureKind, checkpoint.reason].join(', ')
+          + '): ' + compactContinuationText(checkpoint.summary, 36),
+      );
+    }
   }
 
   return lines.join('\n');

package/src/hooks/handler.ts

@@ -340,6 +340,17 @@ async function buildHookProjectContext(
       refresh: 'auto',
       reader: { projectId: canonicalId },
       continuation: 'always',
+      ...(input.sessionId
+        ? {
+            // A native compact recovery is delivered once per host session.
+            // Do not echo that same checkpoint back through the generic
+            // continuation brief on later events from this session.
+            excludeCompactionCheckpointFor: {
+              sessionId: input.sessionId,
+              agent: input.agent,
+            },
+          }
+        : {}),
       enqueueRefresh: () => import('../runtime/lifecycle.js').then(({ enqueueCodegraphRefresh }) => {
         enqueueCodegraphRefresh({
           dataDir,
@@ -365,6 +376,30 @@ async function buildHookProjectContext(
   }
 }
 
+function isCompactSessionStart(input: NormalizedHookInput): boolean {
+  return input.event === 'session_start'
+    && input.sessionStartReason?.trim().toLowerCase() === 'compact';
+}
+
+/**
+ * Consume one host-scoped checkpoint at a delivery point the host actually
+ * supports. This is intentionally best-effort: a local checkpoint failure
+ * must never interfere with the host's native compactor or current turn.
+ */
+async function consumeCompactContinuation(
+  input: NormalizedHookInput,
+  task: string,
+): Promise<string | undefined> {
+  try {
+    const { consumeCompactionWorkset } = await import('../memory/compaction.js');
+    const workset = await consumeCompactionWorkset(input, { task, maxTokens: 420 });
+    return workset?.text;
+  } catch (error) {
+    console.error('[memorix] compact continuation failed:', (error as Error)?.message ?? error);
+    return undefined;
+  }
+}
+
 /**
  * Claude Code ignores SessionStart systemMessage as model context. Its official
  * UserPromptSubmit output accepts additionalContext, so explicit continuation
@@ -375,20 +410,46 @@ async function buildClaudeContinuationPromptContext(input: NormalizedHookInput):
     return undefined;
   }
 
-  const { isContinuationTask } = await import('../codegraph/task-lens.js');
-  if (!isContinuationTask(input.userPrompt)) return undefined;
-
   if (await getHookInjectionMode(input) === 'silent') return undefined;
 
-  const context = await buildHookProjectContext(input, input.userPrompt, 'hook-user-prompt');
-  if (!context?.hasContinuation) return undefined;
+  const compactContinuation = await consumeCompactContinuation(input, input.userPrompt);
+  if (compactContinuation) {
+    return [
+      'Memorix recovered one bounded checkpoint after the host compacted this session.',
+      'Treat it as background context; current code and the user request win.',
+      '',
+      compactContinuation,
+    ].join('\n');
+  }
+
+  const { isContinuationTask, resolveTaskLens } = await import('../codegraph/task-lens.js');
+  const continuationRequested = isContinuationTask(input.userPrompt);
+  if (continuationRequested) {
+    const context = await buildHookProjectContext(input, input.userPrompt, 'hook-user-prompt');
+    if (context?.hasContinuation) {
+      return [
+        'Memorix prepared a bounded prior-work brief for this explicit continuation request.',
+        'Treat it as background context; current code wins. Use it before broad Git or file-history archaeology.',
+        '',
+        context.prompt,
+      ].join('\n');
+    }
+  }
+
+  // Claude Code skills are user-invoked rather than automatically injected.
+  // For the narrow cases where prior project context is materially useful,
+  // provide a small routing nudge instead of silently adding a broad brief to
+  // every prompt. This keeps new feature work quiet while making handoffs and
+  // onboarding naturally discover the one-call Autopilot path.
+  if (continuationRequested || resolveTaskLens(input.userPrompt).id === 'onboarding') {
+    return [
+      'Memorix is available for this handoff or continuation.',
+      'Before broad file or Git exploration, call memorix_project_context with the user\'s actual task.',
+      'If it is not visible yet, use Claude Code tool search for memorix_project_context; use CLI only when MCP discovery is unavailable.',
+    ].join(' ');
+  }
 
-  return [
-    'Memorix prepared a bounded prior-work brief for this explicit continuation request.',
-    'Treat it as background context; current code wins. Use it before broad Git or file-history archaeology.',
-    '',
-    context.prompt,
-  ].join('\n');
+  return undefined;
 }
 
 async function handleSessionStart(input: NormalizedHookInput): Promise<{
@@ -401,6 +462,29 @@ async function handleSessionStart(input: NormalizedHookInput): Promise<{
     return { observation: null, output: { continue: true } };
   }
 
+  // Codex officially supports SessionStart additionalContext. Deliver the
+  // compact checkpoint there, before the generic startup brief can add noise.
+  if (input.agent === 'codex' && isCompactSessionStart(input)) {
+    const compactContinuation = await consumeCompactContinuation(
+      input,
+      'Continue after the host compacted the current session.',
+    );
+    if (compactContinuation) {
+      return {
+        observation: null,
+        output: {
+          continue: true,
+          systemMessage: [
+            'Memorix recovered one bounded checkpoint after the host compacted this session.',
+            'Treat it as background context; current code and the user request win.',
+            '',
+            compactContinuation,
+          ].join('\n'),
+        },
+      };
+    }
+  }
+
   let contextSummary = '';
   if (injectMode === 'full') {
     const context = await buildHookProjectContext(input, 'Continue the current task.', 'hook-session-start');
@@ -706,6 +790,14 @@ export async function runHook(agentOverride?: string, eventOverride?: string): P
   }
 
   const input = normalizeHookInput(payload);
+  try {
+    const { captureCompactionCheckpoint } = await import('../memory/compaction.js');
+    await captureCompactionCheckpoint(input);
+  } catch (checkpointError) {
+    // Host-native compaction is authoritative. Checkpoint persistence is an
+    // additive recovery layer and must never block it.
+    console.error('[memorix] compact checkpoint failed:', (checkpointError as Error)?.message ?? checkpointError);
+  }
   const { observation, output } = await handleHookEvent(input, { deferMaintenance: true });
 
   if (observation) {

package/src/hooks/normalizer.ts

@@ -6,7 +6,7 @@
  * but they all communicate via stdin/stdout JSON.
  */
 
-import type { AgentName, HookEvent, NormalizedHookInput } from './types.js';
+import type { AgentName, HookEvent, NativeCompactionMetadata, NormalizedHookInput } from './types.js';
 
 /**
  * Map agent-specific event names → normalized event names.
@@ -143,6 +143,59 @@ function stringifyValue(value: unknown): string | undefined {
   }
 }
 
+function firstNumber(...values: unknown[]): number | undefined {
+  for (const value of values) {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'string' && value.trim()) {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+  }
+  return undefined;
+}
+
+function normalizeCompactionReason(value: string | undefined): NativeCompactionMetadata['reason'] {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === 'manual' || normalized === 'auto') return normalized;
+  return 'unknown';
+}
+
+/**
+ * Read only documented/explicit compact fields. Unknown host payloads remain
+ * lifecycle markers; we never fabricate a native summary from a transcript.
+ */
+function normalizeCompactionMetadata(
+  payload: Record<string, unknown>,
+  ...records: Array<Record<string, unknown> | undefined>
+): NativeCompactionMetadata | undefined {
+  const nestedSources = records.filter((record): record is Record<string, unknown> => Boolean(record));
+  const sources = [payload, ...nestedSources];
+  const from = (field: string): unknown[] => sources.map((source) => source[field]);
+  const fromNested = (field: string): unknown[] => nestedSources.map((source) => source[field]);
+  const summary = firstString(...from('summary'), ...from('compaction_summary'));
+  // A hook payload's top-level `id` is often a session or transcript ID. Only
+  // use an explicit compact ID at the top level, or an entry ID nested under a
+  // documented compaction object, for idempotency.
+  const sourceKey = firstString(...from('compaction_id'), ...from('entry_id'), ...fromNested('id'));
+  const reasonValue = firstString(...from('trigger'), ...from('reason'), ...from('compaction_reason'));
+  const tokensBefore = firstNumber(...from('tokensBefore'), ...from('tokens_before'));
+  const firstKeptEntryId = firstString(...from('firstKeptEntryId'), ...from('first_kept_entry_id'));
+  const details = sources
+    .map((source) => asRecord(source.details))
+    .find((value): value is Record<string, unknown> => Boolean(value));
+  if (!summary && !sourceKey && !tokensBefore && !firstKeptEntryId && !details && !reasonValue) {
+    return undefined;
+  }
+  return {
+    ...(reasonValue ? { reason: normalizeCompactionReason(reasonValue) } : {}),
+    ...(sourceKey ? { sourceKey } : {}),
+    ...(summary ? { summary } : {}),
+    ...(tokensBefore !== undefined ? { tokensBefore } : {}),
+    ...(firstKeptEntryId ? { firstKeptEntryId } : {}),
+    ...(details ? { details } : {}),
+  };
+}
+
 /**
  * Detect which agent sent this hook event based on payload structure.
  */
@@ -287,6 +340,11 @@ function normalizeClaude(payload: Record<string, unknown>, event: HookEvent): Pa
     result.aiResponse = assistantMessage;
   }
 
+  if (event === 'session_start') {
+    const source = firstString(payload.source, payload.session_start_reason, payload.reason);
+    if (source) result.sessionStartReason = source;
+  }
+
   return result;
 }
 
@@ -463,6 +521,10 @@ function normalizeGemini(payload: Record<string, unknown>, event: HookEvent): Pa
   if (event === 'user_prompt') {
     result.userPrompt = (payload.prompt as string) ?? '';
   }
+  if (event === 'session_start') {
+    const source = firstString(payload.source, payload.session_start_reason, payload.reason);
+    if (source) result.sessionStartReason = source;
+  }
 
   return result;
 }
@@ -514,6 +576,7 @@ function normalizePi(payload: Record<string, unknown>, event: HookEvent): Partia
   const result: Partial<NormalizedHookInput> = {
     sessionId: (payload.session_id as string) ?? (payload.sessionId as string) ?? '',
     cwd: (payload.cwd as string) ?? '',
+    transcriptPath: (payload.transcript_path as string) ?? (payload.transcriptPath as string),
   };
 
   const toolName = (payload.tool_name as string) ?? '';
@@ -537,6 +600,10 @@ function normalizePi(payload: Record<string, unknown>, event: HookEvent): Partia
   if (event === 'post_command') {
     result.command = (payload.command as string) ?? '';
   }
+  if (event === 'session_start') {
+    const source = firstString(payload.source, payload.reason);
+    if (source) result.sessionStartReason = source;
+  }
 
   if (result.toolInput && typeof result.toolInput === 'object') {
     const filePath =
@@ -604,6 +671,10 @@ function normalizeBridgePayload(payload: Record<string, unknown>, event: HookEve
       openclawContext?.message,
     ) ?? stringifyValue(openclawEvent?.message) ?? '';
   }
+  if (event === 'session_start') {
+    const source = firstString(payload.source, bridgePayload?.source, bridgeKwargs?.source, openclawEvent?.reason);
+    if (source) result.sessionStartReason = source;
+  }
 
   return result;
 }
@@ -660,6 +731,18 @@ export function normalizeHookInput(payload: Record<string, unknown>): Normalized
       agentSpecific = { sessionId: '', cwd: '' };
   }
 
+  const openclawEvent = asRecord(payload.openclaw_event);
+  const genericCompaction = event === 'pre_compact' || event === 'post_compact'
+    ? normalizeCompactionMetadata(
+      payload,
+      asRecord(payload.compaction),
+      asRecord(payload.compaction_entry),
+      asRecord(payload.compactionEntry),
+      asRecord(openclawEvent?.compaction),
+      asRecord(openclawEvent?.compaction_entry),
+    )
+    : undefined;
+
   return {
     event,
     agent,
@@ -668,5 +751,6 @@ export function normalizeHookInput(payload: Record<string, unknown>): Normalized
     cwd: agentSpecific.cwd ?? '',
     raw: payload,
     ...agentSpecific,
+    ...(genericCompaction ? { compaction: genericCompaction } : {}),
   };
 }

package/src/hooks/types.ts

@@ -16,6 +16,16 @@ export type HookEvent =
   | 'session_end'
   | 'post_response';
 
+/** Native compact metadata exposed by a host hook or package extension. */
+export interface NativeCompactionMetadata {
+  reason?: 'manual' | 'auto' | 'unknown';
+  sourceKey?: string;
+  summary?: string;
+  tokensBefore?: number;
+  firstKeptEntryId?: string;
+  details?: Record<string, unknown>;
+}
+
 /** Supported agent identifiers */
 export type AgentName =
   | 'claude'
@@ -92,6 +102,12 @@ export interface NormalizedHookInput {
   /** Full transcript path (for pre_compact / session_end) */
   transcriptPath?: string;
 
+  /** Host-provided SessionStart source (for example, `compact` in Codex). */
+  sessionStartReason?: string;
+
+  /** Native compaction metadata when the host makes it available. */
+  compaction?: NativeCompactionMetadata;
+
   /** Raw agent-specific payload (preserved for debugging) */
   raw: Record<string, unknown>;
 }

package/src/knowledge/workset.ts

@@ -91,6 +91,15 @@ export interface WorksetContinuation {
     type: string;
     detail?: string;
   }>;
+  /** Recent host-native compaction evidence, kept distinct from durable memory. */
+  compactCheckpoint?: {
+    id: string;
+    agent: string;
+    captureKind: 'native-summary' | 'lifecycle';
+    reason: 'manual' | 'auto' | 'unknown';
+    completedAt?: string;
+    summary: string;
+  };
 }
 
 export interface TaskWorkset {
@@ -353,7 +362,9 @@ export function renderTaskWorksetPrompt(input: Omit<TaskWorkset, 'prompt' | 'bud
   appendLine(lines, 'Task lens: ' + input.lens, maxTokens, omitted, 'lens');
 
   const hasContinuation = Boolean(
-    input.continuation?.previousSession || (input.continuation?.memories.length ?? 0) > 0,
+    input.continuation?.previousSession
+      || (input.continuation?.memories.length ?? 0) > 0
+      || input.continuation?.compactCheckpoint,
   );
   if (hasContinuation && input.continuation) {
     appendLine(lines, '', maxTokens, omitted, 'continuation-heading');
@@ -395,6 +406,24 @@ export function renderTaskWorksetPrompt(input: Omit<TaskWorkset, 'prompt' | 'bud
         },
       );
     }
+    if (input.continuation.compactCheckpoint) {
+      const checkpoint = input.continuation.compactCheckpoint;
+      const source = `${checkpoint.agent}, ${checkpoint.captureKind}, ${checkpoint.reason}`;
+      appendLine(
+        lines,
+        '- Recent host compact checkpoint (' + source + '): ' + short(checkpoint.summary, 36),
+        maxTokens,
+        omitted,
+        'continuation-compact-checkpoint',
+        selected,
+        {
+          kind: 'continuation',
+          id: 'compact:' + checkpoint.id,
+          reason: 'recent host-native compact lifecycle evidence',
+          trust: 'historical',
+        },
+      );
+    }
   }
 
   if (input.cautions.length > 0 || input.cautionMemory.length > 0) {
@@ -699,7 +728,11 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
     .map(kind => cautions.find(caution => caution.kind === kind)!)
     .slice(0, 6);
   const continuation = input.continuation
-    && (input.continuation.previousSession || input.continuation.memories.length > 0)
+    && (
+      input.continuation.previousSession
+      || input.continuation.memories.length > 0
+      || input.continuation.compactCheckpoint
+    )
     ? {
       ...(input.continuation.previousSession
         ? {
@@ -714,6 +747,14 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
         title: short(memory.title, 20),
         ...(memory.detail ? { detail: short(memory.detail, CONTINUATION_DETAIL_TOKEN_BUDGET) } : {}),
       })),
+      ...(input.continuation.compactCheckpoint
+        ? {
+          compactCheckpoint: {
+            ...input.continuation.compactCheckpoint,
+            summary: short(input.continuation.compactCheckpoint.summary, 44),
+          },
+        }
+        : {}),
     }
     : undefined;
   const base = {