@mnemom/mnemom 0.17.3-next.1 → 0.17.3-next.3

package/README.md

@@ -84,6 +84,31 @@ An explicit launch shape (`--remote-control`, `--server`, `MNEMOM_AGENT_REMOTE_C
 or `launch` in `launcher.toml`) also skips the Remote Control capability probe
 (`claude --help`), which only feeds the automatic upgrade to Remote Control.
 
+#### Context profile: how the gateway folds a session's context
+
+`--context-profile <off|balanced|aggressive>` picks how the Mnemom gateway folds a
+session's context. Each profile serves a different set of use cases:
+
+- **`balanced`** (the default) keeps more of the earlier work verbatim and folds later —
+  for long sessions that revisit earlier files and decisions.
+- **`aggressive`** folds earlier and keeps a tighter working set — for cost-sensitive
+  sessions and short, focused tasks.
+- **`off`** leaves compaction to the coding agent.
+
+Set it per launch, as a standing default, or in the environment (flag > env > `launcher.toml`):
+
+```bash
+mnemom agent my-task --context-profile aggressive   # this launch only
+mnemom agent config set context_profile aggressive  # persists in ~/.mnemom/launcher.toml
+export MNEMOM_AGENT_CONTEXT_PROFILE=aggressive      # for every launch in this shell
+```
+
+`--no-context` (or `context = false` in `launcher.toml`) is the same as `off`. Pass one or the
+other: `--no-context` together with `--context-profile balanced` or `aggressive` is refused. A
+`--context-profile` flag overrides a standing `context = false` in `launcher.toml`. `--dry-run`
+prints the resolved profile and, when the launch sends the per-session config header, the
+decoded key/value list; `mnemom agent show` and the session ledger record the profile.
+
 #### Context handoff (experimental, off by default)
 
 **Off by default.** `--context-handoff` (or the standing default `mnemom agent config set

package/dist/commands/agent-config.js

@@ -190,6 +190,9 @@ function deleteKey(cfg, key) {
         case "context_handoff":
             delete cfg.contextHandoff;
             break;
+        case "context_profile":
+            delete cfg.contextProfile;
+            break;
         default:
             requireSpec(key); // throws the known-keys message for anything unknown
     }

package/dist/commands/agent-sessions.js

@@ -177,6 +177,8 @@ export function buildShowView(local, remote, reason) {
         launchBits.push(`model ${local.model}`);
     if (local.effort)
         launchBits.push(`effort ${local.effort}`);
+    if (local.context_profile)
+        launchBits.push(`context ${local.context_profile}`);
     L.push(fmt.label("launch:       ", launchBits.join(" · ")));
     L.push(fmt.label("conversation: ", local.conversation_id));
     const goalMode = resolveGoalMode(local, remote);

package/dist/commands/agent.d.ts

@@ -25,7 +25,7 @@
  * line, or the proxy's stdin under RC). It is never logged, printed, or passed as
  * an argv value.
  */
-import { type LaunchShape, type SealedContractEnvelope } from "../lib/agent.js";
+import { type ContextProfile, type LaunchShape, type SealedContractEnvelope } from "../lib/agent.js";
 export interface AgentOptions {
     goal?: string;
     requirement?: string[];
@@ -58,6 +58,12 @@ export interface AgentOptions {
      * gateway to skip folding for this session only.
      */
     context?: boolean;
+    /**
+     * How the gateway folds this session's context (`--context-profile`): `off`, `balanced` or
+     * `aggressive`. Undefined ⇒ MNEMOM_AGENT_CONTEXT_PROFILE (the `context_profile` setting), else
+     * `balanced`. `--no-context` is `off`; combined with balanced|aggressive the launch refuses.
+     */
+    contextProfile?: ContextProfile;
     /** context-hint seed default: commander `--no-context-hint` sets this false. */
     contextHint?: boolean;
     /** Attach the Slack channel server (`--slack`; lib/slack-launch.ts). */
@@ -108,6 +114,8 @@ export declare function recordSessionLaunch(ctx: {
     goalMode: string | null;
     /** The Claude Code session id (pickCcSessionId); null/absent when Claude Code picks it. */
     ccSessionId?: string | null;
+    /** The resolved context profile this launch runs under. */
+    contextProfile: ContextProfile;
 }): Promise<void>;
 /**
  * Resolve the Anthropic key with NO 1Password dependency (built for external
@@ -233,4 +241,8 @@ export declare function printPlan(ctx: {
     goalMode: string | null;
     yolo: boolean;
     cli: ResolvedCli;
+    /** The resolved context profile (`resolveContextProfile`). */
+    contextProfile: ContextProfile;
+    /** The decoded `x-mnemom-session-config` overlay (`buildSessionConfig`); empty ⇒ no header. */
+    sessionConfig: Record<string, string>;
 }): void;

package/dist/commands/agent.js

@@ -40,12 +40,24 @@ import { fmt } from "../lib/format.js";
 import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
 import { goalAlignmentLine, resolveSessionSetup } from "./agent-session.js";
 import { AgentIdentityMismatchError, defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, isQuietPreambleExit, resolveDefaultSlug, resolvePreflightedAccount, } from "./agent-setup.js";
-import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfigB64, resolveContextFold, resolveContextHandoff, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, sessionDisplayName, SESSION_NAME_ENV, } from "../lib/agent.js";
+import { assembleContract, buildGoalModeHeader, buildCustomHeaders, buildHandoffMcpConfigJson, buildSessionConfig, buildSessionConfigB64, resolveContextHandoff, resolveContextProfile, resolveHandoffGatewayHost, HANDOFF_RC_KEY_ENV_NAME, isProdGateway, launchPreferenceExplicit, launchPreflighted, remoteControlAllowed, resolveAnthropicDoor, resolveConversationId, resolveGatewayHost, resolveLaunchShape, resolveRemoteControlShape, passthroughName, sanitizeAgentName, sessionDisplayName, SESSION_NAME_ENV, SESSION_CONFIG_HEADER, } from "../lib/agent.js";
 import { LAUNCHER_STORE_PATH, mergeStore } from "../lib/launcher-store.js";
 import { slackChannelArgs } from "../lib/slack-launch.js";
 /** The CLI's own provider-key store (zero 1Password): ~/.mnemom/launcher.json, 0600. */
 const CODE_STORE = LAUNCHER_STORE_PATH;
 const say = (line = "") => console.error(line);
+/**
+ * The one-line launch note for a non-default context profile (`balanced`, the default, is
+ * silent — nothing is sent). `off` keeps the wording `--no-context` has always printed.
+ */
+function sayContextProfile(profile) {
+    if (profile === "off") {
+        say("mnemom agent: context folding OFF for this session (--no-context or context = false).");
+    }
+    else if (profile === "aggressive") {
+        say("mnemom agent: context profile aggressive — the gateway folds earlier and keeps a tighter working set.");
+    }
+}
 /** Entry point for `mnemom agent [scenario]`. Throws on fatal misconfig. */
 export async function agentCommand(scenarioArg, options = {}) {
     // ── session name + goal ── (a bare `mnemom agent` in a terminal asks for both,
@@ -99,12 +111,18 @@ export async function agentCommand(scenarioArg, options = {}) {
     const cellNote = isProdGateway(env) ? "us-2/prod" : `custom (${gatewayHost})`;
     const yolo = options.yolo !== false; // default ON
     const contextHint = options.contextHint !== false; // default ON
-    // Context folding is ON by default; --no-context (or `context = false` in
-    // launcher.toml → MNEMOM_AGENT_CONTEXT) turns it off for this session via the
-    // per-session config header. `undefined` sessionConfigB64 ⇒ nothing sent.
-    const contextFold = resolveContextFold({ context: options.context, env });
+    // Context profile: `balanced` (the gateway's own defaults) unless --context-profile /
+    // MNEMOM_AGENT_CONTEXT_PROFILE (the `context_profile` setting) says otherwise; --no-context
+    // (or `context = false` in launcher.toml → MNEMOM_AGENT_CONTEXT) is `off`. Anything but
+    // balanced rides in the per-session config header; `undefined` sessionConfigB64 ⇒ nothing sent.
+    const contextProfile = resolveContextProfile({
+        contextProfile: options.contextProfile,
+        context: options.context,
+        env,
+    });
     const contextHandoff = resolveContextHandoff({ contextHandoff: options.contextHandoff, env });
-    const sessionConfigB64 = buildSessionConfigB64({ fold: contextFold, contextHandoff });
+    const sessionConfig = buildSessionConfig({ profile: contextProfile, contextHandoff });
+    const sessionConfigB64 = buildSessionConfigB64({ profile: contextProfile, contextHandoff });
     // ── which CLI executable (name or full path) ── resolve GRACEFULLY: if it's not
     // found we don't crash with a technical error — we ask for the path at launch.
     let cli;
@@ -143,13 +161,13 @@ export async function agentCommand(scenarioArg, options = {}) {
             goalMode,
             yolo,
             cli: planCli,
+            contextProfile,
+            sessionConfig,
         });
         if (previewShape === "remote-control") {
             say("mnemom agent: the plan shows Remote Control because this machine can run it; the real launch uses it only if your account is entitled (internal Mnemom accounts), else terminal-only.");
         }
-        if (!contextFold) {
-            say("mnemom agent: context folding OFF for this session (--no-context or context = false).");
-        }
+        sayContextProfile(contextProfile);
         if (contextHandoff) {
             say("mnemom agent: context handoff ON (experimental) — the `handoff` MCP tool would be registered.");
         }
@@ -269,12 +287,11 @@ export async function agentCommand(scenarioArg, options = {}) {
         envelope,
         goalMode,
         ccSessionId: cc.id,
+        contextProfile,
     });
     logLaunch({ shape, door, agent, conversationId, cellNote, envelope, goalMode, cli });
     say(goalAlignmentLine(goalAlignmentMode(envelope, goalMode)));
-    if (!contextFold) {
-        say("mnemom agent: context folding OFF for this session (--no-context or context = false).");
-    }
+    sayContextProfile(contextProfile);
     // ── handoff MCP tool (MNE-7564) ── OFF by default: absent/false ⇒ handoffMcpConfigPath stays
     // undefined and buildCliArgs/spawnRcCli are byte-identical to a build without this flag. ON:
     // the config is written to a 0600 temp file and referenced by PATH only — never inlined into
@@ -377,6 +394,7 @@ export async function recordSessionLaunch(ctx) {
         cli: ctx.cli.name,
         contract: toLedgerContract(ctx.envelope?.contract ?? null),
         goal_mode: goalAlignmentMode(ctx.envelope, ctx.goalMode),
+        context_profile: ctx.contextProfile,
         cc_session_id: ctx.ccSessionId ?? null,
     }, {
         dir: MNEMOM_DIR,
@@ -1085,6 +1103,13 @@ export function printPlan(ctx) {
     L.push(`  agent:         ${ctx.agent}`);
     L.push(`  conversation:  ${ctx.conversationId}`);
     L.push(`  yolo:          ${ctx.yolo ? "on (--dangerously-skip-permissions)" : "off"}`);
+    L.push(`  context:       ${ctx.contextProfile}`);
+    const overlay = Object.entries(ctx.sessionConfig);
+    if (overlay.length > 0) {
+        L.push(`  session config (${SESSION_CONFIG_HEADER}):`);
+        for (const [k, v] of overlay)
+            L.push(`    ${k}=${v}`);
+    }
     if (ctx.envelope) {
         L.push(`  contract:      ${ctx.envelope.canonical}`);
         L.push(`  contract sha:  ${ctx.envelope.sha}`);

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { program, Option } from "commander";
+import { program, InvalidArgumentError, Option } from "commander";
 import { isEntrypoint } from "./lib/entrypoint.js";
 import { CLI_VERSION } from "./version.js";
 import { statusCommand } from "./commands/status.js";
@@ -29,7 +29,7 @@ import { agentDoctorCommand } from "./commands/agent-doctor.js";
 import { agentSetupCommand } from "./commands/agent-setup.js";
 import { agentInviteCommand, runAgentInvocation } from "./commands/agent-invite.js";
 import { applyConfigToEnv, loadLauncherConfig } from "./lib/launcher-config.js";
-import { resolveImplicit } from "./lib/agent.js";
+import { parseContextProfile, resolveImplicit } from "./lib/agent.js";
 import { wrapCommand } from "./commands/wrap.js";
 import { onboardCommand } from "./commands/onboard.js";
 import { skillsListCommand, skillsDescribeCommand } from "./commands/skills.js";
@@ -143,6 +143,16 @@ const agentCmd = program
     .option("--slack", "Attach the Slack channel: messages addressed to this session arrive in it, and it can reply (see `mnemom agent slack`)")
     .option("--context", "Force context folding ON for this launch even when launcher.toml (context = false) or MNEMOM_AGENT_CONTEXT turns it off")
     .option("--no-context", "Disable context folding for this launch (folding is on by default; tells the gateway to skip it for this session)")
+    .addOption(new Option("--context-profile <profile>", 'How the gateway folds this session\'s context. "balanced" (default) keeps more of the earlier work verbatim and folds later — for long sessions that revisit earlier files and decisions. "aggressive" folds earlier and keeps a tighter working set — for cost-sensitive sessions and short, focused tasks. "off" leaves compaction to the coding agent. Also: config key context_profile, env MNEMOM_AGENT_CONTEXT_PROFILE.').argParser((v) => {
+    // One validator for all three surfaces (flag, MNEMOM_AGENT_CONTEXT_PROFILE,
+    // launcher.toml context_profile): trimmed, case-insensitive, same error wording.
+    try {
+        return parseContextProfile(v, "--context-profile");
+    }
+    catch (e) {
+        throw new InvalidArgumentError(e.message);
+    }
+}))
     .option("--context-handoff", "EXPERIMENTAL, off by default: register the `handoff(note)` MCP tool and tell the gateway to turn on the context-handoff capability for this session")
     .option("--no-context-handoff", "Keep context handoff off for this launch even when launcher.toml (context_handoff = true) or MNEMOM_AGENT_CONTEXT_HANDOFF turns it on")
     .option("--dry-run", "Print the resolved launch plan and exit — no key read, no spawn")
@@ -234,6 +244,7 @@ const agentCmd = program
             contextHint: opts.contextHint,
             slack: opts.slack ?? cfg.slackListen,
             context: opts.context,
+            contextProfile: opts.contextProfile,
             contextHandoff: opts.contextHandoff,
             setup: opts.setup,
             keySource: cfg.keySource,

package/dist/lib/agent-ledger.d.ts

@@ -14,7 +14,7 @@
  * `sessions.retention_days` (default 30) are dropped when the next one is
  * recorded. No count cap — a long retention keeps everything in the window.
  */
-import type { LaunchShape, SealedContract } from "./agent.js";
+import type { ContextProfile, LaunchShape, SealedContract } from "./agent.js";
 /** The ledger's file name under MNEMOM_DIR. */
 export declare const LEDGER_FILE = "sessions.jsonl";
 /** Days a launch stays in the ledger when `sessions.retention_days` is unset. */
@@ -75,6 +75,12 @@ export interface SessionRecord {
      * records written before this field existed omit it (still `v: 1`).
      */
     cc_session_id?: string | null;
+    /**
+     * The context profile the launch ran under (`--context-profile` / `context_profile` /
+     * `MNEMOM_AGENT_CONTEXT_PROFILE`, or `balanced` by default). Optional: records written
+     * before profiles existed omit it (still `v: 1`).
+     */
+    context_profile?: ContextProfile;
 }
 /** Goal-alignment mode as recorded at launch. */
 export type GoalMode = "off" | "on" | "implicit";

package/dist/lib/agent.d.ts

@@ -161,6 +161,21 @@ export declare const GOAL_MODE_HEADER = "x-mnemom-goal-mode";
 export declare const SESSION_CONFIG_HEADER = "x-mnemom-session-config";
 /** The gateway env key that gates context folding (allow-listed for per-session overlay). */
 export declare const CONTEXT_RUNTIME_KEY = "CONTEXT_RUNTIME_ENABLED";
+/** Gateway fold-tuning keys the `aggressive` context profile sets (all allow-listed per session). */
+export declare const CONTEXT_TAIL_BUDGET_KEY = "CONTEXT_RUNTIME_TAIL_BUDGET_TOKENS";
+export declare const CONTEXT_READ_CACHE_KEY = "CONTEXT_RUNTIME_READ_CACHE_TOKENS";
+export declare const CONTEXT_HEAD_RECLAIM_KEY = "CONTEXT_RUNTIME_HEAD_BREAKPOINT_RECLAIM";
+/**
+ * The named presets for how the gateway folds a session's context (`--context-profile`,
+ * launcher.toml `context_profile`, `MNEMOM_AGENT_CONTEXT_PROFILE`):
+ *   - `off`        → `CONTEXT_RUNTIME_ENABLED: "false"` — compaction is left to the coding agent
+ *                    (the same bytes `--no-context` has always sent).
+ *   - `balanced`   → NO fold keys: the gateway's own defaults stand. The default.
+ *   - `aggressive` → a smaller tail budget + read cache and head-breakpoint reclaim on: folds
+ *                    earlier and keeps a tighter working set.
+ */
+export declare const CONTEXT_PROFILES: readonly ["off", "balanced", "aggressive"];
+export type ContextProfile = (typeof CONTEXT_PROFILES)[number];
 /**
  * The gateway env key that gates the whole context-handoff capability (level lines +
  * `/mnemom/context/handoff` route + the digest note section) for a single session
@@ -272,12 +287,49 @@ export declare function resolveContextFold(opts: {
     context?: boolean;
     env?: NodeJS.ProcessEnv;
 }): boolean;
+/**
+ * Validate a context-profile word — the ONE validator behind all three surfaces (the
+ * `--context-profile` flag, launcher.toml `context_profile`, the `MNEMOM_AGENT_CONTEXT_PROFILE`
+ * env var); trimmed, case-insensitive. `source` names the surface in the error so a customer
+ * knows which setting to fix.
+ */
+export declare function parseContextProfile(raw: string, source: string): ContextProfile;
+/**
+ * Which context profile this launch runs under. Precedence, highest wins:
+ *   1. `--no-context` — always `off`. Combined with an explicit `--context-profile
+ *      balanced|aggressive` it is a CONFLICT and the launch refuses (never a silent override);
+ *      `--context-profile off` agrees with it.
+ *   2. an explicit `--context-profile <profile>` flag (`--context` alongside it is fine — the
+ *      profile wins);
+ *   3. `MNEMOM_AGENT_CONTEXT_PROFILE` (which `applyConfigToEnv` sets from the `context_profile`
+ *      config key) — an invalid value is an error, never a silent default;
+ *   4. the folding boolean when NO profile is set anywhere: `context = false` in launcher.toml
+ *      (→ `MNEMOM_AGENT_CONTEXT`, see `resolveContextFold`) means `off`;
+ *   5. `balanced` (the default).
+ */
+export declare function resolveContextProfile(opts: {
+    contextProfile?: ContextProfile;
+    context?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): ContextProfile;
+/**
+ * The decoded per-session env overlay for this launch — the `config` object of the
+ * `x-mnemom-session-config` payload, in wire order: the profile's keys first
+ * (`CONTEXT_RUNTIME_ENABLED` for `off`; the three fold-tuning keys for `aggressive`; nothing
+ * for `balanced`), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON. Empty
+ * for `balanced` with handoff off — the common case, where no header is sent at all.
+ * Exported so `--dry-run` can list exactly what the header carries.
+ */
+export declare function buildSessionConfig(opts: {
+    profile: ContextProfile;
+    contextHandoff: boolean;
+}): Record<string, string>;
 /**
  * The `x-mnemom-session-config` value for this launch, or `undefined` when there is
- * nothing to override (the gateway's own defaults stand — the common case). Two
- * independent overlays, both OFF by default (folding is ON by default so only its OFF
- * state is ever sent; handoff is OFF by default so only its ON state is ever sent):
- *   - `fold: false` → `CONTEXT_RUNTIME_ENABLED: "false"` (`--no-context`).
+ * nothing to override (the gateway's own defaults stand — `balanced` with handoff off,
+ * byte-identical to a launch before profiles existed). Two independent overlays:
+ *   - the context profile (`buildSessionConfig`): `off` → `CONTEXT_RUNTIME_ENABLED: "false"`,
+ *     `aggressive` → the three fold-tuning keys, `balanced` → nothing;
  *   - `contextHandoff: true` → `CONTEXT_HANDOFF_ENABLED: "true"` (the `context_handoff`
  *     setting) — the SAME header the `handoff` MCP tool's own call to
  *     `/mnemom/context/handoff` must also send, since the gateway resolves the flag
@@ -285,7 +337,7 @@ export declare function resolveContextFold(opts: {
  * base64url so it survives the gateway's inbound strip.
  */
 export declare function buildSessionConfigB64(opts: {
-    fold: boolean;
+    profile: ContextProfile;
     contextHandoff: boolean;
 }): string | undefined;
 /**

package/dist/lib/agent.js

@@ -226,6 +226,30 @@ export const GOAL_MODE_HEADER = "x-mnemom-goal-mode";
 export const SESSION_CONFIG_HEADER = "x-mnemom-session-config";
 /** The gateway env key that gates context folding (allow-listed for per-session overlay). */
 export const CONTEXT_RUNTIME_KEY = "CONTEXT_RUNTIME_ENABLED";
+/** Gateway fold-tuning keys the `aggressive` context profile sets (all allow-listed per session). */
+export const CONTEXT_TAIL_BUDGET_KEY = "CONTEXT_RUNTIME_TAIL_BUDGET_TOKENS";
+export const CONTEXT_READ_CACHE_KEY = "CONTEXT_RUNTIME_READ_CACHE_TOKENS";
+export const CONTEXT_HEAD_RECLAIM_KEY = "CONTEXT_RUNTIME_HEAD_BREAKPOINT_RECLAIM";
+/**
+ * The named presets for how the gateway folds a session's context (`--context-profile`,
+ * launcher.toml `context_profile`, `MNEMOM_AGENT_CONTEXT_PROFILE`):
+ *   - `off`        → `CONTEXT_RUNTIME_ENABLED: "false"` — compaction is left to the coding agent
+ *                    (the same bytes `--no-context` has always sent).
+ *   - `balanced`   → NO fold keys: the gateway's own defaults stand. The default.
+ *   - `aggressive` → a smaller tail budget + read cache and head-breakpoint reclaim on: folds
+ *                    earlier and keeps a tighter working set.
+ */
+export const CONTEXT_PROFILES = ["off", "balanced", "aggressive"];
+/** The per-session env overlay each profile expands to (key order is the wire order). */
+const CONTEXT_PROFILE_CONFIG = {
+    off: [[CONTEXT_RUNTIME_KEY, "false"]],
+    balanced: [],
+    aggressive: [
+        [CONTEXT_TAIL_BUDGET_KEY, "60000"],
+        [CONTEXT_READ_CACHE_KEY, "8000"],
+        [CONTEXT_HEAD_RECLAIM_KEY, "true"],
+    ],
+};
 /**
  * The gateway env key that gates the whole context-handoff capability (level lines +
  * `/mnemom/context/handoff` route + the digest note section) for a single session
@@ -432,12 +456,69 @@ export function resolveContextFold(opts) {
         return true;
     return !(raw === "0" || raw === "false" || raw === "off" || raw === "no");
 }
+/**
+ * Validate a context-profile word — the ONE validator behind all three surfaces (the
+ * `--context-profile` flag, launcher.toml `context_profile`, the `MNEMOM_AGENT_CONTEXT_PROFILE`
+ * env var); trimmed, case-insensitive. `source` names the surface in the error so a customer
+ * knows which setting to fix.
+ */
+export function parseContextProfile(raw, source) {
+    const v = raw.trim().toLowerCase();
+    if (CONTEXT_PROFILES.includes(v))
+        return v;
+    throw new Error(`${source} must be one of ${CONTEXT_PROFILES.join(", ")} (got '${raw}').`);
+}
+/**
+ * Which context profile this launch runs under. Precedence, highest wins:
+ *   1. `--no-context` — always `off`. Combined with an explicit `--context-profile
+ *      balanced|aggressive` it is a CONFLICT and the launch refuses (never a silent override);
+ *      `--context-profile off` agrees with it.
+ *   2. an explicit `--context-profile <profile>` flag (`--context` alongside it is fine — the
+ *      profile wins);
+ *   3. `MNEMOM_AGENT_CONTEXT_PROFILE` (which `applyConfigToEnv` sets from the `context_profile`
+ *      config key) — an invalid value is an error, never a silent default;
+ *   4. the folding boolean when NO profile is set anywhere: `context = false` in launcher.toml
+ *      (→ `MNEMOM_AGENT_CONTEXT`, see `resolveContextFold`) means `off`;
+ *   5. `balanced` (the default).
+ */
+export function resolveContextProfile(opts) {
+    if (opts.context === false) {
+        if (opts.contextProfile !== undefined && opts.contextProfile !== "off") {
+            throw new Error(`mnemom agent: --no-context and --context-profile ${opts.contextProfile} disagree — drop one (--no-context is the same as --context-profile off).`);
+        }
+        return "off";
+    }
+    if (opts.contextProfile !== undefined)
+        return opts.contextProfile;
+    const raw = (opts.env?.MNEMOM_AGENT_CONTEXT_PROFILE ?? "").trim();
+    if (raw !== "")
+        return parseContextProfile(raw, "MNEMOM_AGENT_CONTEXT_PROFILE");
+    if (!resolveContextFold({ context: opts.context, env: opts.env }))
+        return "off";
+    return "balanced";
+}
+/**
+ * The decoded per-session env overlay for this launch — the `config` object of the
+ * `x-mnemom-session-config` payload, in wire order: the profile's keys first
+ * (`CONTEXT_RUNTIME_ENABLED` for `off`; the three fold-tuning keys for `aggressive`; nothing
+ * for `balanced`), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON. Empty
+ * for `balanced` with handoff off — the common case, where no header is sent at all.
+ * Exported so `--dry-run` can list exactly what the header carries.
+ */
+export function buildSessionConfig(opts) {
+    const config = {};
+    for (const [k, v] of CONTEXT_PROFILE_CONFIG[opts.profile])
+        config[k] = v;
+    if (opts.contextHandoff)
+        config[CONTEXT_HANDOFF_KEY] = "true";
+    return config;
+}
 /**
  * The `x-mnemom-session-config` value for this launch, or `undefined` when there is
- * nothing to override (the gateway's own defaults stand — the common case). Two
- * independent overlays, both OFF by default (folding is ON by default so only its OFF
- * state is ever sent; handoff is OFF by default so only its ON state is ever sent):
- *   - `fold: false` → `CONTEXT_RUNTIME_ENABLED: "false"` (`--no-context`).
+ * nothing to override (the gateway's own defaults stand — `balanced` with handoff off,
+ * byte-identical to a launch before profiles existed). Two independent overlays:
+ *   - the context profile (`buildSessionConfig`): `off` → `CONTEXT_RUNTIME_ENABLED: "false"`,
+ *     `aggressive` → the three fold-tuning keys, `balanced` → nothing;
  *   - `contextHandoff: true` → `CONTEXT_HANDOFF_ENABLED: "true"` (the `context_handoff`
  *     setting) — the SAME header the `handoff` MCP tool's own call to
  *     `/mnemom/context/handoff` must also send, since the gateway resolves the flag
@@ -445,11 +526,7 @@ export function resolveContextFold(opts) {
  * base64url so it survives the gateway's inbound strip.
  */
 export function buildSessionConfigB64(opts) {
-    const config = {};
-    if (!opts.fold)
-        config[CONTEXT_RUNTIME_KEY] = "false";
-    if (opts.contextHandoff)
-        config[CONTEXT_HANDOFF_KEY] = "true";
+    const config = buildSessionConfig(opts);
     if (Object.keys(config).length === 0)
         return undefined;
     const payload = JSON.stringify({ v: 1, config });

package/dist/lib/launcher-config.d.ts

@@ -15,7 +15,7 @@
  * resolvers in lib/code.ts keep the built-in default as the final fallback);
  * the caller folds the plain-value settings under the CLI flags.
  */
-import { type GoalModeDefault, type LaunchShape } from "./agent.js";
+import { type ContextProfile, type GoalModeDefault, type LaunchShape } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
 export declare const LAUNCHER_CONFIG_PATH: string;
 /** Where the CLI resolves the Anthropic key from; advisory ordering/restriction. */
@@ -45,6 +45,12 @@ export interface LauncherConfig {
      * every launch. Off means byte-identical to a launch with no MNE-7564 change at all.
      */
     contextHandoff?: boolean;
+    /**
+     * How the gateway folds each session's context (`balanced` when unset): `off` leaves
+     * compaction to the coding agent, `balanced` keeps more earlier work verbatim, `aggressive`
+     * folds earlier with a tighter working set. `--context-profile` overrides it per launch.
+     */
+    contextProfile?: ContextProfile;
     guardrails?: {
         maxTurns?: number;
         budgetUsd?: number;

package/dist/lib/launcher-config.js

@@ -19,7 +19,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "
 import { dirname, join } from "node:path";
 import { parse as parseToml, stringify as stringifyToml, TomlError } from "smol-toml";
 import { MNEMOM_DIR } from "./config.js";
-import { isPositiveInt, isPositiveNumber, } from "./agent.js";
+import { CONTEXT_PROFILES, isPositiveInt, isPositiveNumber, parseContextProfile, } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
 export const LAUNCHER_CONFIG_PATH = join(MNEMOM_DIR, "launcher.toml");
 const LAUNCH_SHAPES = ["terminal", "remote-control", "server"];
@@ -188,6 +188,14 @@ export const CONFIG_KEYS = [
             c.contextHandoff = coerceBool("context_handoff", v);
         },
     },
+    {
+        key: "context_profile",
+        describe: `How the gateway folds each session's context (${CONTEXT_PROFILES.join("|")}; balanced by default)`,
+        get: (c) => c.contextProfile,
+        set: (c, v) => {
+            c.contextProfile = parseContextProfile(v, "context_profile");
+        },
+    },
     {
         key: "guardrails.max_turns",
         describe: "Contract guardrail: turn ceiling (positive integer)",
@@ -266,6 +274,8 @@ export function parseLauncherConfig(text) {
         cfg.slackChannel = coerceNonEmpty("slack_channel", str(raw.slack_channel) ?? "");
     if (raw.context_handoff !== undefined)
         cfg.contextHandoff = coerceBool("context_handoff", str(raw.context_handoff) ?? "");
+    if (raw.context_profile !== undefined)
+        cfg.contextProfile = parseContextProfile(str(raw.context_profile) ?? "", "context_profile");
     const g = raw.guardrails;
     if (g !== undefined) {
         if (typeof g !== "object" || g === null || Array.isArray(g)) {
@@ -334,6 +344,8 @@ export function serializeLauncherConfig(cfg) {
         doc.slack_allow = cfg.slackAllow;
     if (cfg.contextHandoff !== undefined)
         doc.context_handoff = cfg.contextHandoff;
+    if (cfg.contextProfile !== undefined)
+        doc.context_profile = cfg.contextProfile;
     const g = cfg.guardrails;
     if (g && (g.maxTurns !== undefined || g.budgetUsd !== undefined || g.stallTurns !== undefined)) {
         const gr = {};
@@ -386,4 +398,7 @@ export function applyConfigToEnv(cfg, env = process.env) {
     if (cfg.contextHandoff !== undefined && !(env.MNEMOM_AGENT_CONTEXT_HANDOFF ?? "").trim()) {
         env.MNEMOM_AGENT_CONTEXT_HANDOFF = cfg.contextHandoff ? "1" : "0";
     }
+    if (cfg.contextProfile !== undefined && !(env.MNEMOM_AGENT_CONTEXT_PROFILE ?? "").trim()) {
+        env.MNEMOM_AGENT_CONTEXT_PROFILE = cfg.contextProfile;
+    }
 }

package/dist/lib/update/decide.d.ts

@@ -64,6 +64,9 @@ export interface UpdateState {
     method?: InstallMethod;
     /** Channel the last successful update installed from; feeds defaultChannel. */
     followChannel?: UpdateChannel;
+    /** The background worker startup last spawned, while it runs (cleared when it finishes). */
+    workerPid?: number;
+    workerSince?: number;
 }
 export interface UpdatePrefs {
     channel?: UpdateChannel;
@@ -121,6 +124,19 @@ export declare function entitlementFresh(cache: EntitlementCache | undefined, no
  * registry response).
  */
 export declare function pickTarget(tags: DistTags, channel: UpdateChannel): string | undefined;
+/**
+ * Longest a worker lives: it waits for its parent `mnemom` (a whole agent session)
+ * up to this long. A recorded worker older than this is treated as gone, so a
+ * recycled pid can't block updates.
+ */
+export declare const WORKER_MAX_AGE_MS: number;
+/**
+ * A known update is still pending and nothing is working on it: the last worker
+ * recorded `available` but was killed before installing (e.g. while waiting out
+ * a long agent session). Startup respawns one without waiting for the next
+ * scheduled check.
+ */
+export declare function shouldResume(state: UpdateState, current: string, now: number, alive: (pid: number) => boolean): boolean;
 /** Whether the background worker should poll the registry now. */
 export declare function shouldCheck(state: UpdateState, channel: UpdateChannel, now: number): boolean;
 export declare function backoffDelay(failures: number): number;

package/dist/lib/update/decide.js

@@ -115,6 +115,33 @@ export function pickTarget(tags, channel) {
         return next;
     return compareVersions(next, stable) >= 0 ? next : stable;
 }
+/**
+ * Longest a worker lives: it waits for its parent `mnemom` (a whole agent session)
+ * up to this long. A recorded worker older than this is treated as gone, so a
+ * recycled pid can't block updates.
+ */
+export const WORKER_MAX_AGE_MS = 12 * HOUR;
+/**
+ * A known update is still pending and nothing is working on it: the last worker
+ * recorded `available` but was killed before installing (e.g. while waiting out
+ * a long agent session). Startup respawns one without waiting for the next
+ * scheduled check.
+ */
+export function shouldResume(state, current, now, alive) {
+    if (!state.available || !isValidVersion(state.available))
+        return false;
+    if (compareVersions(state.available, current) <= 0)
+        return false;
+    if (state.installBlocked || !canSelfUpdate(state.method ?? "unknown"))
+        return false;
+    if (state.backoffUntil !== undefined && now < state.backoffUntil)
+        return false;
+    const working = state.workerPid !== undefined &&
+        state.workerSince !== undefined &&
+        now - state.workerSince < WORKER_MAX_AGE_MS &&
+        alive(state.workerPid);
+    return !working;
+}
 /** Whether the background worker should poll the registry now. */
 export function shouldCheck(state, channel, now) {
     if (state.backoffUntil !== undefined && now < state.backoffUntil)

package/dist/lib/update/run.d.ts

@@ -29,6 +29,8 @@ export interface RunDeps {
      * `mnemom agent` session). Resolving false skips the install this pass.
      */
     beforeInstall?(): Promise<boolean>;
+    /** The background worker's own pid: it clears its `workerPid` record when done. */
+    pid?: number;
 }
 export interface RunResult {
     /** The channel actually honoured (next falls back to latest when not entitled). */

package/dist/lib/update/run.js

@@ -37,13 +37,17 @@ function failurePatch(state, now, message) {
 export async function runUpdate(deps, settings, opts = {}) {
     const now = deps.now();
     const state = deps.loadState();
+    // Every exit path forgets this worker's record, so startup can tell it's gone.
+    const done = deps.pid !== undefined && state.workerPid === deps.pid
+        ? { workerPid: undefined, workerSince: undefined }
+        : {};
     let tags;
     try {
         tags = await deps.fetchDistTags();
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        deps.saveState(failurePatch(state, now, message));
+        deps.saveState({ ...failurePatch(state, now, message), ...done });
         return { channel: settings.channel, channelDowngraded: false, error: message };
     }
     const entitled = settings.channel === "next" ? await resolveEntitlement(deps, state, now) : false;
@@ -71,12 +75,18 @@ export async function runUpdate(deps, settings, opts = {}) {
     };
     const result = { channel, channelDowngraded, method, target, action };
     if (action.kind !== "install") {
-        deps.saveState(base);
+        deps.saveState({ ...base, ...done });
         return result;
     }
-    const proceed = deps.beforeInstall ? await deps.beforeInstall() : true;
-    if (!proceed) {
+    let proceed = true;
+    if (deps.beforeInstall) {
+        // Record what we found BEFORE the (possibly hours-long) wait: if this worker
+        // is killed meanwhile, the next launch still knows an update is pending.
         deps.saveState(base);
+        proceed = await deps.beforeInstall();
+    }
+    if (!proceed) {
+        deps.saveState({ ...base, ...done });
         return { ...result, action: { kind: "notify", version: action.version, reason: "deferred" } };
     }
     const outcome = await deps.install(action.version);
@@ -87,15 +97,20 @@ export async function runUpdate(deps, settings, opts = {}) {
             installBlocked: undefined,
             pending: { from: deps.current, to: action.version, channel },
             followChannel: channel,
+            ...done,
         });
         return { ...result, installed: action.version };
     }
     if (outcome.eacces) {
         // Retrying can't fix permissions — switch to notify-with-instructions.
-        deps.saveState({ ...base, installBlocked: true, lastError: outcome.message });
+        deps.saveState({ ...base, installBlocked: true, lastError: outcome.message, ...done });
     }
     else {
-        deps.saveState({ ...failurePatch(state, now, outcome.message), available: base.available });
+        deps.saveState({
+            ...failurePatch(state, now, outcome.message),
+            available: base.available,
+            ...done,
+        });
     }
     return { ...result, error: outcome.message };
 }

package/dist/lib/update/startup.d.ts

@@ -2,7 +2,8 @@
  * The per-invocation hook, run before commander parses argv. It must cost
  * ~nothing and never fail the user's command:
  *   1. print a one-line stderr notice (completed update, or an available one);
- *   2. if a check is due, spawn the detached worker and return immediately.
+ *   2. if a check is due — or a known update was left uninstalled by a worker
+ *      that died — spawn the detached worker and return immediately.
  * All I/O is injected; `defaultStartupDeps()` wires the real process.
  */
 import { type UpdateChannel, type UpdateMode, type UpdatePrefs, type UpdateState } from "./decide.js";
@@ -18,8 +19,10 @@ export interface StartupDeps {
     saveState(patch: Partial<UpdateState>): void;
     entryPath: string;
     writeErr(line: string): void;
-    spawnWorker(args: [entry: string, channel: UpdateChannel, mode: UpdateMode, parentPid: string]): void;
+    /** Returns the worker's pid (undefined if the spawn failed). */
+    spawnWorker(args: [entry: string, channel: UpdateChannel, mode: UpdateMode, parentPid: string]): number | undefined;
     pid: number;
+    alive(pid: number): boolean;
 }
 export declare function maybeRunUpdateHook(deps: StartupDeps): void;
 /** dist/lib/update/startup.js → dist/update-worker.js */

package/dist/lib/update/startup.js

@@ -2,16 +2,18 @@
  * The per-invocation hook, run before commander parses argv. It must cost
  * ~nothing and never fail the user's command:
  *   1. print a one-line stderr notice (completed update, or an available one);
- *   2. if a check is due, spawn the detached worker and return immediately.
+ *   2. if a check is due — or a known update was left uninstalled by a worker
+ *      that died — spawn the detached worker and return immediately.
  * All I/O is injected; `defaultStartupDeps()` wires the real process.
  */
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { CLI_VERSION } from "../../version.js";
-import { resolveSettings, shouldCheck, startupNotice, } from "./decide.js";
+import { resolveSettings, shouldCheck, shouldResume, startupNotice, } from "./decide.js";
 import { classifyInstall } from "./install-method.js";
 import { loadUpdateState, saveUpdateState } from "./state.js";
 import { entryRealpath, loadUpdatePrefs } from "./system.js";
+import { isAlive } from "./worker.js";
 /** Commands that manage updates themselves, or must stay side-effect free. */
 const SKIP_COMMANDS = new Set(["update", "config"]);
 export function maybeRunUpdateHook(deps) {
@@ -41,11 +43,21 @@ export function maybeRunUpdateHook(deps) {
         }
         if (SKIP_COMMANDS.has(deps.argv[0] ?? ""))
             return;
-        if (!shouldCheck(state, settings.channel, now))
+        const due = shouldCheck(state, settings.channel, now);
+        const resume = !due && settings.mode === "auto" && shouldResume(state, deps.current, now, deps.alive);
+        if (!due && !resume)
             return;
         // Stamp first so a burst of commands doesn't spawn a burst of workers.
-        deps.saveState({ lastCheck: now });
-        deps.spawnWorker([deps.entryPath, settings.channel, settings.mode, String(deps.pid)]);
+        if (due)
+            deps.saveState({ lastCheck: now });
+        const pid = deps.spawnWorker([
+            deps.entryPath,
+            settings.channel,
+            settings.mode,
+            String(deps.pid),
+        ]);
+        if (pid !== undefined)
+            deps.saveState({ workerPid: pid, workerSince: now });
     }
     catch {
         /* the updater never breaks the user's command */
@@ -75,6 +87,8 @@ export function defaultStartupDeps(argv) {
             });
             child.on("error", () => { });
             child.unref();
+            return child.pid;
         },
+        alive: (pid) => isAlive(pid),
     };
 }

package/dist/lib/update/worker.js

@@ -8,7 +8,7 @@
  */
 import { CLI_VERSION } from "../../version.js";
 import { getApiUrl } from "../config.js";
-import { isUpdateChannel, isUpdateMode } from "./decide.js";
+import { isUpdateChannel, isUpdateMode, WORKER_MAX_AGE_MS, } from "./decide.js";
 import { classifyInstall } from "./install-method.js";
 import { fetchChannelEntitlement, fetchDistTags } from "./registry.js";
 import { runUpdate } from "./run.js";
@@ -23,7 +23,7 @@ export function parseWorkerArgs(args) {
 }
 export const PARENT_POLL_MS = 5000;
 /** Give up waiting on a very long session; the next run picks the update up. */
-export const PARENT_WAIT_MAX_MS = 12 * 60 * 60 * 1000;
+export const PARENT_WAIT_MAX_MS = WORKER_MAX_AGE_MS;
 /** `kill(pid, 0)` probes liveness without signalling. EPERM still means alive. */
 export function isAlive(pid, kill = (p, s) => void process.kill(p, s)) {
     try {
@@ -60,6 +60,7 @@ export function realRunDeps(entry, credential) {
         fetchEntitlement: async () => fetchChannelEntitlement(fetch, getApiUrl(), await credential()),
         installMethod: async () => classifyInstall(entry, await npmGlobalRoot()),
         install: (version) => npmInstallGlobal(version),
+        pid: process.pid,
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.3-next.1",
+  "version": "0.17.3-next.3",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {