memorix 1.5.0 → 1.6.0

package/src/cli/commands/context.ts

@@ -7,6 +7,9 @@ import {
 } from '../../codegraph/auto-context.js';
 import { getAllObservations } from '../../memory/observations.js';
 import { filterReadableObservations } from '../../memory/visibility.js';
+import { buildBoundedContextReceipt } from '../../knowledge/context-receipt.js';
+import { WORKFLOW_AGENT_TARGETS } from '../../knowledge/workflows.js';
+import type { AgentTarget } from '../../types.js';
 import { emitError, emitResult, getCliProjectContext } from './operator-shared.js';
 
 function coerceRefreshMode(input?: string): AutoContextRefreshMode {
@@ -15,6 +18,13 @@ function coerceRefreshMode(input?: string): AutoContextRefreshMode {
   throw new Error('refresh must be one of: auto, always, never');
 }
 
+function coerceAgentTarget(input?: string): AgentTarget | undefined {
+  const value = input?.trim().toLowerCase();
+  if (!value) return undefined;
+  if (WORKFLOW_AGENT_TARGETS.includes(value as AgentTarget)) return value as AgentTarget;
+  throw new Error('agent must be one of: ' + WORKFLOW_AGENT_TARGETS.join(', '));
+}
+
 export default defineCommand({
   meta: {
     name: 'context',
@@ -29,10 +39,12 @@ export default defineCommand({
     },
     resume: { type: 'boolean', description: 'Always include the bounded prior-work projection' },
     refresh: { type: 'string', description: 'Project scan policy: auto, always, or never' },
+    agent: { type: 'string', description: 'Optional target agent for compatible workflow selection' },
     json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+    briefJson: { type: 'boolean', description: 'Emit only the bounded agent brief and receipt JSON' },
   },
   run: async ({ args }) => {
-    const asJson = !!args.json;
+    const asJson = !!args.json || !!args.briefJson;
     const task = (args.task as string | undefined)?.trim()
       || (args.input as string | undefined)?.trim()
       || undefined;
@@ -44,13 +56,13 @@ export default defineCommand({
         dataDir,
         observations: filterReadableObservations(getAllObservations(), reader),
         task,
+        agent: coerceAgentTarget(args.agent as string | undefined),
         refresh: coerceRefreshMode(args.refresh as string | undefined),
         reader,
         ...(args.resume ? { continuation: 'always' as const } : {}),
       });
 
-      emitResult(
-        {
+      const detailed = {
           project,
           lens: context.lens,
           brief: buildAutoProjectBrief(context),
@@ -61,7 +73,11 @@ export default defineCommand({
           workset: context.workset,
           ...(context.task ? { task: context.task } : {}),
           ...(context.continuation ? { continuation: context.continuation } : {}),
-        },
+      };
+      emitResult(
+        args.briefJson
+          ? buildBoundedContextReceipt({ workset: context.workset, providerQuality: context.providerQuality })
+          : detailed,
         formatAutoProjectContextPrompt(context),
         asJson,
       );

package/src/cli/commands/resume.ts

@@ -13,7 +13,9 @@ export default defineCommand({
   args: {
     task: { type: 'positional', description: 'Current continuation task', required: false },
     refresh: { type: 'string', description: 'Project scan policy: auto, always, or never' },
+    agent: { type: 'string', description: 'Optional target agent for compatible workflow selection' },
     json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+    briefJson: { type: 'boolean', description: 'Emit only the bounded agent brief and receipt JSON' },
   },
   async run({ args }) {
     await contextCommand.run?.({
@@ -21,7 +23,9 @@ export default defineCommand({
         _: [],
         input: args.task,
         refresh: args.refresh,
+        agent: args.agent,
         json: args.json,
+        briefJson: args.briefJson,
         resume: true,
       },
       rawArgs: [],

package/src/codegraph/auto-context.ts

@@ -10,7 +10,7 @@ import {
 } 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';
+import type { AgentTarget, ObservationReader, ProjectInfo } from '../types.js';
 import { backfillMissingObservationCodeRefs, type CodeRefBackfillResult } from './binder.js';
 import { collectCurrentProjectFacts, formatGitFact, type CurrentProjectFacts } from './current-facts.js';
 import { refreshProjectLite } from './lite-provider.js';
@@ -189,6 +189,8 @@ export async function buildAutoProjectContext(input: {
   dataDir: string;
   observations: ProjectContextObservation[];
   task?: string;
+  /** Explicit host target for task-compatible workflow selection. */
+  agent?: AgentTarget;
   refresh?: AutoContextRefreshMode;
   maxAgeMs?: number;
   now?: Date;
@@ -426,6 +428,7 @@ export async function buildAutoProjectContext(input: {
     projectId: input.project.id,
     dataDir: input.dataDir,
     ...(task ? { task } : {}),
+    ...(input.agent ? { agent: input.agent } : {}),
     lens: lens.id,
     startHere,
     ...(alwaysOn.profile.length > 0 || alwaysOn.state || alwaysOn.durable.length > 0

package/src/codegraph/context-pack.ts

@@ -10,7 +10,7 @@ import type {
 } from './types.js';
 import type { CodeGraphStore } from './store.js';
 import { isCodeGraphExcludedPath } from './exclude.js';
-import type { ObservationReader } from '../types.js';
+import type { AgentTarget, ObservationReader } from '../types.js';
 
 export interface ContextPackMemory {
   id: number;
@@ -278,6 +278,7 @@ export async function attachTaskWorkset(input: {
   providerQuality?: CodeGraphProviderQuality;
   runtimeCautions?: WorksetCaution[];
   reader?: ObservationReader;
+  agent?: AgentTarget;
 }): Promise<ContextPack> {
   const semanticStartHere = input.semanticCode
     ? [...input.semanticCode.relatedFiles, ...input.semanticCode.entryPoints.map(entry => entry.path)]
@@ -286,6 +287,7 @@ export async function attachTaskWorkset(input: {
     projectId: input.projectId,
     dataDir: input.dataDir,
     task: input.pack.task,
+    ...(input.agent ? { agent: input.agent } : {}),
     lens: input.lens,
     currentFacts: input.currentFacts ?? [],
     ...(input.codeState ? { codeState: input.codeState } : {}),

package/src/codegraph/external-provider.ts

@@ -17,6 +17,8 @@ import type {
 // Keep the default useful in real sessions while still bounding a local call.
 export const DEFAULT_EXTERNAL_CODEGRAPH_TIMEOUT_MS = 1_200;
 export const MAX_EXTERNAL_CODEGRAPH_TIMEOUT_MS = 5_000;
+/** Explicit index maintenance is opt-in and may legitimately take longer. */
+export const EXTERNAL_CODEGRAPH_LIFECYCLE_TIMEOUT_MS = 30_000;
 export const MAX_EXTERNAL_CODEGRAPH_OUTPUT_BYTES = 256 * 1024;
 const MAX_EXTERNAL_NODE_COUNT = 16;
 const MAX_EXTERNAL_EDGE_COUNT = 24;
@@ -85,6 +87,19 @@ export interface ExternalCodeGraphContextResult extends InspectExternalCodeGraph
   caution?: string;
 }
 
+/** Explicit lifecycle operations. Memorix never calls CodeGraph's `install`. */
+export type ExternalCodeGraphLifecycleAction = 'init' | 'sync';
+
+export interface ExternalCodeGraphLifecycleInput extends InspectExternalCodeGraphInput {
+  action: ExternalCodeGraphLifecycleAction;
+}
+
+export interface ExternalCodeGraphLifecycleResult extends InspectExternalCodeGraphResult {
+  action: ExternalCodeGraphLifecycleAction;
+  performed: boolean;
+  message: string;
+}
+
 interface RawExternalStatus {
   initialized: boolean;
   projectPath: string;
@@ -437,6 +452,84 @@ export async function inspectExternalCodeGraph(input: InspectExternalCodeGraphIn
   return { health, quality: providerQuality({ mode, health }) };
 }
 
+/**
+ * Run only a user-requested local lifecycle operation and re-inspect the
+ * result. This deliberately does not alter agent MCP files or invoke the
+ * upstream `codegraph install` command.
+ */
+export async function runExternalCodeGraphLifecycle(
+  input: ExternalCodeGraphLifecycleInput,
+): Promise<ExternalCodeGraphLifecycleResult> {
+  const mode = input.mode ?? 'auto';
+  if (mode === 'off') {
+    const health: ExternalCodeGraphHealth = { state: 'disabled', reason: 'External CodeGraph is disabled by configuration.' };
+    return {
+      action: input.action,
+      performed: false,
+      message: 'External CodeGraph is disabled by configuration.',
+      health,
+      quality: providerQuality({ mode, health }),
+    };
+  }
+
+  const indexPath = join(input.projectRoot, '.codegraph');
+  if (input.action === 'sync' && !existsSync(indexPath)) {
+    const health: ExternalCodeGraphHealth = { state: 'not-detected', reason: 'No local .codegraph index is present for this project.' };
+    return {
+      action: input.action,
+      performed: false,
+      message: 'Initialize CodeGraph first with "memorix codegraph init".',
+      health,
+      quality: providerQuality({ mode, health }),
+    };
+  }
+
+  if (input.action === 'init' && existsSync(indexPath)) {
+    const inspected = await inspectExternalCodeGraph(input);
+    return {
+      action: input.action,
+      performed: false,
+      message: 'A local CodeGraph directory already exists; no initialization was performed.',
+      ...inspected,
+    };
+  }
+
+  const result = await runSafely(input.runner ?? defaultRunner, {
+    command: input.command,
+    args: input.action === 'init'
+      ? ['init', input.projectRoot]
+      : ['sync', input.projectRoot, '--quiet'],
+    cwd: input.projectRoot,
+    // A context read must stay fast; an explicit user-requested index sync is
+    // a different operation and gets its own bounded maintenance window.
+    timeoutMs: EXTERNAL_CODEGRAPH_LIFECYCLE_TIMEOUT_MS,
+    maxOutputBytes: MAX_EXTERNAL_CODEGRAPH_OUTPUT_BYTES,
+  });
+  if (!result.ok) {
+    const health = unavailableHealth(result);
+    return {
+      action: input.action,
+      performed: false,
+      message: 'CodeGraph ' + input.action + ' did not complete: ' + (health.reason ?? 'unknown local error'),
+      health,
+      quality: providerQuality({ mode, health }),
+    };
+  }
+
+  const inspected = await inspectExternalCodeGraph(input);
+  const remainsStale = inspected.health.state === 'stale';
+  return {
+    action: input.action,
+    performed: true,
+    message: input.action === 'init'
+      ? 'Local CodeGraph initialization completed. Run "memorix codegraph sync" when source changes.'
+      : remainsStale
+        ? 'Local CodeGraph synchronization completed, but the graph remains stale against the current worktree; this task will use Lite evidence.'
+        : 'Local CodeGraph synchronization completed and is ready for task-scoped semantic context.',
+    ...inspected,
+  };
+}
+
 function safeRelativePath(projectRoot: string, value: unknown, exclude?: string[]): string | undefined {
   const path = safeText(value, 1_024);
   if (!path || isAbsolute(path)) return undefined;

package/src/embedding/api-provider.ts

@@ -406,6 +406,16 @@ interface APIEmbeddingConfig {
   requestedDimensions: number | null;
 }
 
+class EmbeddingAPIError extends Error {
+  readonly status: number;
+
+  constructor(status: number, detail: string) {
+    super(`Embedding API error (${status}): ${detail}`);
+    this.name = 'EmbeddingAPIError';
+    this.status = status;
+  }
+}
+
 export interface APIEmbeddingProviderCreateOptions {
   /**
    * When false, only previously persisted dimension metadata may initialize
@@ -432,6 +442,14 @@ function getPreferredBatchSize(config: APIEmbeddingConfig): number {
 function parseBatchLimit(error: unknown): number | null {
   if (!(error instanceof Error)) return null;
 
+  // Only a provider-side request-shape error may trigger recursive batch
+  // splitting. Billing, authentication, quota, and upstream errors must fail
+  // once; retrying them multiplies latency without changing the request.
+  const status = error instanceof EmbeddingAPIError
+    ? error.status
+    : Number(error.message.match(/Embedding API error \((\d{3})\)/i)?.[1] ?? 0);
+  if (status > 0 && status !== 400) return null;
+
   const explicit = error.message.match(/should not be larger than\s+(\d+)/i);
   if (explicit) return parseInt(explicit[1], 10);
 
@@ -712,16 +730,14 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
         }
       } catch (error) {
         const providerLimit = parseBatchLimit(error);
-        const fallbackSize = providerLimit ?? Math.ceil(chunkTexts.length / 2);
-
-        if (chunkTexts.length > 1 && fallbackSize < chunkTexts.length) {
+        if (providerLimit !== null && chunkTexts.length > 1 && providerLimit < chunkTexts.length) {
           console.error(
-            `[memorix] Embedding batch too large for provider, retrying in chunks of ${fallbackSize}`,
+            `[memorix] Embedding batch too large for provider, retrying in chunks of ${providerLimit}`,
           );
-          for (let start = 0; start < chunkTexts.length; start += fallbackSize) {
+          for (let start = 0; start < chunkTexts.length; start += providerLimit) {
             await processChunk(
-              chunkTexts.slice(start, start + fallbackSize),
-              chunkIndices.slice(start, start + fallbackSize),
+              chunkTexts.slice(start, start + providerLimit),
+              chunkIndices.slice(start, start + providerLimit),
             );
           }
           return;
@@ -842,6 +858,9 @@ async function fetchWithRetry(
     ? Math.max(100, Math.min(Math.floor(options.timeoutMs), 60_000))
     : 10_000;
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, controller.signal])
+    : controller.signal;
   let response: Response;
   try {
     response = await fetch(url, {
@@ -850,30 +869,94 @@ async function fetchWithRetry(
         ? { 'Content-Type': 'application/json', 'x-goog-api-key': apiKey }
         : { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
       body: JSON.stringify(body),
-      signal: controller.signal,
+      signal,
     });
   } catch (err: unknown) {
     clearTimeout(timeout);
-    if (err instanceof Error && err.name === 'AbortError') {
+    if (err instanceof Error && (err.name === 'AbortError' || controller.signal.aborted || options.signal?.aborted)) {
       throw new Error(`Embedding API timeout after ${timeoutMs}ms: ${url}`);
     }
     throw err;
   }
-  clearTimeout(timeout);
 
-  if (response.ok) {
-    return response.json() as Promise<EmbeddingAPIResponse>;
-  }
+  try {
+    if (response.ok) {
+      return await raceWithAbort(
+        response.json() as Promise<EmbeddingAPIResponse>,
+        signal,
+      );
+    }
+
+    if (options.retry !== false && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
+      const delay = BASE_DELAY_MS * Math.pow(2, attempt);
+      const retryAfter = response.headers.get('retry-after');
+      const parsedRetryAfter = retryAfter ? parseInt(retryAfter, 10) * 1000 : NaN;
+      const waitMs = Number.isFinite(parsedRetryAfter) ? parsedRetryAfter : delay;
+      console.error(`[memorix] Embedding API ${response.status}, retry ${attempt + 1}/${MAX_RETRIES} in ${waitMs}ms`);
+      await waitForRetry(waitMs, options.signal);
+      return fetchWithRetry(url, apiKey, body, options, attempt + 1, nativeGemini);
+    }
 
-  if (options.retry !== false && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
-    const delay = BASE_DELAY_MS * Math.pow(2, attempt);
-    const retryAfter = response.headers.get('retry-after');
-    const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : delay;
-    console.error(`[memorix] Embedding API ${response.status}, retry ${attempt + 1}/${MAX_RETRIES} in ${waitMs}ms`);
-    await new Promise(resolve => setTimeout(resolve, waitMs));
-    return fetchWithRetry(url, apiKey, body, options, attempt + 1, nativeGemini);
+    const errorText = await raceWithAbort(
+      response.text().catch(() => 'unknown error'),
+      signal,
+    );
+    throw new EmbeddingAPIError(response.status, errorText);
+  } catch (err: unknown) {
+    if (err instanceof Error && (err.name === 'AbortError' || controller.signal.aborted || options.signal?.aborted)) {
+      throw new Error(`Embedding API timeout after ${timeoutMs}ms: ${url}`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeout);
   }
+}
 
-  const errorText = await response.text().catch(() => 'unknown error');
-  throw new Error(`Embedding API error (${response.status}): ${errorText}`);
+function abortError(): Error {
+  const error = new Error('Embedding API request aborted');
+  error.name = 'AbortError';
+  return error;
+}
+
+function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(abortError());
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      signal.removeEventListener('abort', onAbort);
+      reject(abortError());
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener('abort', onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+async function waitForRetry(waitMs: number, signal?: AbortSignal): Promise<void> {
+  if (!signal) {
+    await new Promise<void>((resolve) => setTimeout(resolve, waitMs));
+    return;
+  }
+  const abortSignal = signal;
+  if (abortSignal.aborted) throw new Error('Embedding API retry aborted');
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(done, waitMs);
+    const onAbort = () => {
+      clearTimeout(timer);
+      abortSignal.removeEventListener('abort', onAbort);
+      reject(new Error('Embedding API retry aborted'));
+    };
+    function done() {
+      abortSignal.removeEventListener('abort', onAbort);
+      resolve();
+    }
+    abortSignal.addEventListener('abort', onAbort, { once: true });
+  });
 }

package/src/embedding/provider.ts

@@ -34,6 +34,8 @@ export interface EmbeddingRequestOptions {
   timeoutMs?: number;
   /** Disable provider retries for latency-sensitive best-effort work. */
   retry?: boolean;
+  /** Abort the request and any retry wait when the caller's budget expires. */
+  signal?: AbortSignal;
 }
 
 export type EmbeddingModality = 'text' | 'image' | 'audio' | 'video' | 'document';

package/src/hooks/installers/index.ts

@@ -1259,7 +1259,7 @@ function getAgentRulesContent(agent?: AgentName, scope: 'project' | 'global' = '
     '',
     `Default first step for non-trivial coding work: call \x60memorix_project_context\x60 with the user's actual task before progress files, dev-log reads, ad-hoc file reads, or git archaeology. Memorix will choose a task-lensed brief (bugfix, feature, release, onboarding, refactor, docs, test, or general). When the task is continuing prior work, the same brief also includes a bounded prior-work projection. Treat its "Start here" files as the first ${contextNoun} files to inspect.`,
     '',
-    'If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select \x60memorix_project_context\x60 first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user\'s real task before inspecting files, Git history, progress notes, or guessing: \x60memorix resume "<task>" --json\x60. For a new task, use \x60memorix context "<task>" --json\x60 instead. The absence of \x60.memorix\x60 or visible memory files never proves project memory is empty. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax.',
+    'If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select \x60memorix_project_context\x60 first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user\'s real task before inspecting files, Git history, progress notes, or guessing: \x60memorix resume "<task>" --brief-json\x60. For a new task, use \x60memorix context "<task>" --brief-json\x60 instead. The absence of \x60.memorix\x60 or visible memory files never proves project memory is empty. Use \x60--json\x60 only when a diagnostic needs the detailed legacy payload. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax.',
     '',
     'After a successful \x60memorix_project_context\x60 result, the brief is the default retrieval boundary. Do not call more Memorix retrieval tools after a complete brief. Use \x60memorix_context_pack\x60, \x60memorix_search\x60, or \x60memorix_detail\x60 only when the brief lacks a specific reference, freshness field, or fact needed for the task, or when the user explicitly asks for deeper history. In MCP, name that missing fact in \x60purpose\x60 when intentionally expanding beyond the brief. Do not retrieve the same decision twice just to confirm an already-complete brief.',
     'If the user asks for read-only work or says not to modify files, do not call \x60memorix_store\x60 just to record an assessment. Store only when the user explicitly asks to preserve it.',

package/src/hooks/official-skills.ts

@@ -31,8 +31,8 @@ export const OFFICIAL_MEMORIX_SKILLS: OfficialMemorixSkill[] = [
       '',
       '| Situation | Prefer | CLI fallback |',
       '|---|---|---|',
-      '| Starting a coding task and needing the best task-lensed project map | `memorix_project_context` with the user\'s task | `memorix context "<task>" --json` |',
-      '| Continuing prior project work | `memorix_project_context` with the user\'s task | `memorix resume "<task>" --json` |',
+      '| Starting a coding task and needing the best task-lensed project map | `memorix_project_context` with the user\'s task | `memorix context "<task>" --brief-json` |',
+      '| Continuing prior project work | `memorix_project_context` with the user\'s task | `memorix resume "<task>" --brief-json` |',
       '| Need structured refs/freshness for code-bound memories | `memorix_context_pack` | `memorix codegraph context-pack --task "<topic>"` |',
       '| Explicit memory graph question | `memorix_graph_context` | `memorix memory graph-context --query "<topic>"` |',
       '| Specific past decision, bug, file, or change | `memorix_search` | `memorix memory search --query "<topic>"` |',
@@ -45,7 +45,7 @@ export const OFFICIAL_MEMORIX_SKILLS: OfficialMemorixSkill[] = [
       '',
       '- Default first step for non-trivial coding work: call `memorix_project_context` before progress files, dev-log reads, ad-hoc file reads, or git archaeology. Pass the user\'s actual task so Memorix can choose a bugfix, feature, release, onboarding, refactor, docs, test, or general brief. Start by reading its suggested files.',
       '- In Claude Code headless/print-mode, an initial MCP `pending` status is not a failure by itself. Prefer MCP first: use the client\'s tool discovery/dynamic loading to find `memorix_project_context` when it is not in the first visible tool list.',
-      '- Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run `memorix resume "<task>" --json` exactly once before inspecting files, Git history, progress notes, or guessing. The absence of `.memorix` or visible memory files never proves project memory is empty. For a new task, use `memorix context "<task>" --json` instead. If that one command fails, report it and proceed normally; do not probe help, enumerate commands, or chain broad searches.',
+      '- Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run `memorix resume "<task>" --brief-json` exactly once before inspecting files, Git history, progress notes, or guessing. The absence of `.memorix` or visible memory files never proves project memory is empty. For a new task, use `memorix context "<task>" --brief-json` instead. Use `--json` only when a diagnostic needs the detailed legacy payload. If that one command fails, report it and proceed normally; do not probe help, enumerate commands, or chain broad searches.',
       '- After a successful `memorix_project_context`, the brief is the default retrieval boundary. Do not call more Memorix retrieval tools after a complete brief. Use Context Pack, search, or detail only when the brief lacks a specific reference, freshness field, or fact needed for the task, or when the user explicitly asks for deeper history. In MCP, name that missing fact in `purpose` when intentionally expanding beyond the brief. Do not retrieve the same decision twice just to confirm an already-complete brief.',
       '- If the user asks for read-only work or says not to modify files, do not call `memorix_store` just to record an assessment. Store only when the user explicitly asks to preserve it.',
       '- Use `memorix_search` for a specific decision, bug, file, or prior change that the project context did not answer. Fetch detail only for a result you still need after the brief.',

package/src/hooks/rules/memorix-agent-rules.md

@@ -7,7 +7,7 @@ You have access to Memorix memory tools. Follow these rules to maintain persiste
 At the beginning of non-trivial coding work, use Memorix Memory Autopilot before local progress notes or broad file exploration. A session bind is not required for every conversation.
 
 1. Default first step for non-trivial coding work: call `memorix_project_context` with the user's actual task before progress files, dev-log reads, ad-hoc file reads, or git archaeology. Memorix will choose a task-lensed brief (bugfix, feature, release, onboarding, refactor, docs, test, or general). Treat its "Start here" files as the first code or docs to inspect.
-2. If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select `memorix_project_context` first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user's real task before inspecting files, Git history, progress notes, or guessing: use `memorix resume "<task>" --json`. For a new task, use `memorix context "<task>" --json` instead. The absence of `.memorix` or visible memory files never proves project memory is empty. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax.
+2. If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select `memorix_project_context` first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user's real task before inspecting files, Git history, progress notes, or guessing: use `memorix resume "<task>" --brief-json`. For a new task, use `memorix context "<task>" --brief-json` instead. The absence of `.memorix` or visible memory files never proves project memory is empty. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax. Use `--json` only when a diagnostic needs the detailed legacy payload.
 3. After a successful `memorix_project_context` result, the brief is the default retrieval boundary. Do not call more Memorix retrieval tools after a complete brief. Use `memorix_context_pack`, `memorix_search`, or `memorix_detail` only when the brief lacks a specific reference, freshness field, or fact needed for the task, or when the user explicitly asks for deeper history. In MCP, name that missing fact in `purpose` when intentionally expanding beyond the brief. Do not retrieve the same decision twice just to confirm an already-complete brief.
    If the user asks for read-only work or says not to modify files, do not call `memorix_store` just to record an assessment. Store only when the user explicitly asks to preserve it.
 4. Use `memorix_context_pack` when you need structured refs and freshness for code-bound memories.

package/src/knowledge/context-receipt.ts

@@ -0,0 +1,41 @@
+import type { CodeGraphProviderQuality } from '../codegraph/types.js';
+import type { TaskWorkset } from './workset.js';
+
+/**
+ * A small machine-readable counterpart to the agent-facing Workset prompt.
+ * Detailed CLI JSON remains available for diagnostics; this shape is for
+ * clients that need a bounded handoff without loading raw stores.
+ */
+export interface BoundedContextReceipt {
+  schemaVersion: '1';
+  task: string;
+  brief: string;
+  receipt: TaskWorkset['receipt'];
+  code: {
+    selected: CodeGraphProviderQuality['selected'];
+    quality: CodeGraphProviderQuality['selectedQuality'];
+    externalState: CodeGraphProviderQuality['external']['state'];
+    snapshotId?: string;
+  };
+  loadout?: TaskWorkset['agentLoadout'];
+}
+
+export function buildBoundedContextReceipt(input: {
+  workset: TaskWorkset;
+  providerQuality?: CodeGraphProviderQuality;
+}): BoundedContextReceipt {
+  const provider = input.providerQuality ?? input.workset.provenance.codeProvider;
+  return {
+    schemaVersion: '1',
+    task: input.workset.task,
+    brief: input.workset.prompt,
+    receipt: input.workset.receipt,
+    code: {
+      selected: provider?.selected ?? 'lite',
+      quality: provider?.selectedQuality ?? 'heuristic',
+      externalState: provider?.external.state ?? 'not-detected',
+      ...(input.workset.provenance.snapshotId ? { snapshotId: input.workset.provenance.snapshotId } : {}),
+    },
+    ...(input.workset.agentLoadout ? { loadout: input.workset.agentLoadout } : {}),
+  };
+}

package/src/knowledge/workflows.ts

@@ -22,7 +22,7 @@ import type {
 } from './workflow-types.js';
 import type { KnowledgeWorkspace } from './workspace-types.js';
 
-const KNOWN_AGENTS: AgentTarget[] = [
+export const WORKFLOW_AGENT_TARGETS: AgentTarget[] = [
   'windsurf',
   'cursor',
   'claude-code',
@@ -117,7 +117,7 @@ function optionalStatus(data: Record<string, unknown>): WorkflowStatus {
 }
 
 function normalizeAgents(values: string[]): AgentTarget[] {
-  const unknown = values.filter(value => !KNOWN_AGENTS.includes(value as AgentTarget));
+  const unknown = values.filter(value => !WORKFLOW_AGENT_TARGETS.includes(value as AgentTarget));
   if (unknown.length > 0) {
     throw new Error('workflow frontmatter has unsupported agent: ' + unknown[0]);
   }
@@ -459,12 +459,15 @@ function taskScore(workflow: WorkflowSpec, task: string): { score: number; reaso
 export function selectWorkflows(input: {
   workflows: WorkflowSpec[];
   task: string;
+  /** Only select workflows that explicitly support the target agent. */
+  agent?: AgentTarget;
   projectId?: string;
   store?: WorkflowStore;
   limit?: number;
 }): WorkflowSelection[] {
   const selected = input.workflows
-    .filter(workflow => workflow.status === 'active')
+    .filter(workflow => workflow.status === 'active'
+      && (!input.agent || workflow.compatibleAgents.includes(input.agent)))
     .map(workflow => {
       const match = taskScore(workflow, input.task);
       const cautions = input.store && input.projectId