memorix 1.2.6 → 1.2.8

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 = {

package/src/memory/compaction.ts

@@ -0,0 +1,165 @@
+import type { CompactionCheckpoint } from '../types.js';
+import type { NormalizedHookInput } from '../hooks/types.js';
+import { countTextTokens, truncateToTokenBudget } from '../compact/token-budget.js';
+import { sanitizeCredentials } from './secret-filter.js';
+import { CompactionCheckpointStore } from '../store/compaction-checkpoint-store.js';
+
+const DEFAULT_WORKSET_BUDGET = 420;
+const MIN_WORKSET_BUDGET = 48;
+
+export interface CompactionWorkset {
+  checkpointId: string;
+  text: string;
+  tokens: number;
+}
+
+export interface BuildCompactionWorksetOptions {
+  task?: string;
+  maxTokens?: number;
+}
+
+function normalizeBudget(value: number | undefined): number {
+  if (!Number.isFinite(value) || value == null) return DEFAULT_WORKSET_BUDGET;
+  return Math.max(MIN_WORKSET_BUDGET, Math.min(2_000, Math.floor(value)));
+}
+
+function sourceLabel(checkpoint: CompactionCheckpoint): string {
+  if (checkpoint.captureKind === 'native-summary') return 'native host summary';
+  if (checkpoint.captureKind === 'preflight') return 'pre-compact lifecycle marker';
+  return 'host lifecycle marker';
+}
+
+/**
+ * Render a small, source-aware continuation packet. It never replays a full
+ * transcript and never promotes a native summary into durable knowledge.
+ */
+export function buildCompactionWorkset(
+  checkpoint: CompactionCheckpoint,
+  options: BuildCompactionWorksetOptions = {},
+): CompactionWorkset {
+  const budget = normalizeBudget(options.maxTokens);
+  const task = options.task?.trim()
+    ? truncateToTokenBudget(sanitizeCredentials(options.task.trim()), Math.max(8, Math.floor(budget * 0.25)))
+    : '';
+  const headerLines = [
+    '## Compact Continuation',
+    `- Host: ${checkpoint.agent} (${sourceLabel(checkpoint)})`,
+    `- Trigger: ${checkpoint.reason}`,
+    task ? `- Task now: ${task}` : '',
+    '- Current code remains authoritative.',
+  ].filter(Boolean);
+  const header = `${headerLines.join('\n')}\n\n`;
+  const fallback = checkpoint.captureKind === 'native-summary'
+    ? ''
+    : 'The host did not expose a native compact summary. Reconstruct only what the current task needs from current code and Memorix evidence.';
+  const source = sanitizeCredentials(checkpoint.summary?.trim() || fallback);
+  const available = Math.max(0, budget - countTextTokens(header) - 4);
+  let excerpt = source ? truncateToTokenBudget(source, available) : '';
+  let text = `${header}${excerpt ? `### Host checkpoint\n${excerpt}` : ''}`.trim();
+  while (excerpt && countTextTokens(text) > budget) {
+    const nextExcerptBudget = Math.max(1, Math.floor(countTextTokens(excerpt) * 0.8));
+    excerpt = truncateToTokenBudget(excerpt, nextExcerptBudget);
+    text = `${header}${excerpt ? `### Host checkpoint\n${excerpt}` : ''}`.trim();
+  }
+  if (countTextTokens(text) > budget) text = truncateToTokenBudget(text, budget);
+  return {
+    checkpointId: checkpoint.id,
+    text,
+    tokens: countTextTokens(text),
+  };
+}
+
+function sourceEvent(input: NormalizedHookInput): string {
+  const raw = input.raw;
+  const event = raw.hook_event_name ?? raw.event ?? raw.type;
+  return typeof event === 'string' && event ? event : input.event;
+}
+
+/**
+ * Persist only the host lifecycle evidence available in a normalized hook.
+ * The caller owns error handling so an unavailable local DB never blocks a
+ * host-native compaction.
+ */
+export async function captureCompactionCheckpoint(
+  input: NormalizedHookInput,
+): Promise<CompactionCheckpoint | null> {
+  const isCompactResume = input.event === 'session_start'
+    && input.sessionStartReason?.trim().toLowerCase() === 'compact';
+  if (input.event !== 'pre_compact' && input.event !== 'post_compact' && !isCompactResume) return null;
+  if (!input.sessionId || !input.cwd) return null;
+
+  const [
+    { detectProject },
+    { getProjectDataDir },
+    { initAliasRegistry, registerAlias },
+  ] = await Promise.all([
+    import('../project/detector.js'),
+    import('../store/persistence.js'),
+    import('../project/aliases.js'),
+  ]);
+  const project = detectProject(input.cwd);
+  if (!project) return null;
+  const dataDir = await getProjectDataDir(project.id);
+  initAliasRegistry(dataDir);
+  const projectId = await registerAlias(project);
+  const store = new CompactionCheckpointStore(dataDir);
+
+  if (input.event === 'pre_compact') {
+    return store.recordPreflight({
+      projectId,
+      sessionId: input.sessionId,
+      agent: input.agent,
+      reason: input.compaction?.reason,
+      sourceEvent: sourceEvent(input),
+      transcriptAvailable: Boolean(input.transcriptPath),
+      capturedAt: input.timestamp,
+    });
+  }
+
+  return store.complete({
+    projectId,
+    sessionId: input.sessionId,
+    agent: input.agent,
+    reason: input.compaction?.reason,
+    sourceEvent: sourceEvent(input),
+    sourceKey: input.compaction?.sourceKey,
+    summary: input.compaction?.summary,
+    tokensBefore: input.compaction?.tokensBefore,
+    firstKeptEntryId: input.compaction?.firstKeptEntryId,
+    details: input.compaction?.details,
+    completedAt: input.timestamp,
+  });
+}
+
+/**
+ * Take the latest undelivered compact checkpoint for an exact host session.
+ * Delivery is opt-in at adapter boundaries; this helper never injects content
+ * into a host by itself.
+ */
+export async function consumeCompactionWorkset(
+  input: NormalizedHookInput,
+  options: BuildCompactionWorksetOptions = {},
+): Promise<CompactionWorkset | null> {
+  if (!input.sessionId || !input.cwd) return null;
+  const [
+    { detectProject },
+    { getProjectDataDir },
+    { initAliasRegistry, registerAlias },
+  ] = await Promise.all([
+    import('../project/detector.js'),
+    import('../store/persistence.js'),
+    import('../project/aliases.js'),
+  ]);
+  const project = detectProject(input.cwd);
+  if (!project) return null;
+  const dataDir = await getProjectDataDir(project.id);
+  initAliasRegistry(dataDir);
+  const projectId = await registerAlias(project);
+  const store = new CompactionCheckpointStore(dataDir);
+  const checkpoint = store.findUndelivered(projectId, input.sessionId, input.agent);
+  if (!checkpoint) return null;
+  const workset = buildCompactionWorkset(checkpoint, options);
+  if (!workset.text) return null;
+  store.markDelivered(checkpoint.id);
+  return workset;
+}