@mnemom/mnemom 0.17.3-next.2 → 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/package.json

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