feat(install): persist memory learning settings

Author: krzkraw

headroom/cli/install.py

@@ -344,8 +344,12 @@ def _build_deployment_manifest(
     backend: str,
     anyllm_provider: str | None,
     region: str | None,
-    proxy_mode: str,
+    proxy_mode: str | None,
     memory: bool,
+    learn_enabled: bool | None,
+    memory_storage_mode: str,
+    traffic_learning_min_evidence: int,
+    memory_project_root: str,
     telemetry: bool,
     no_telemetry: bool,
     image: str,
@@ -370,9 +374,13 @@ def _build_deployment_manifest(
         anyllm_provider=anyllm_provider,
         region=region,
         proxy_mode=proxy_mode,
-        memory_enabled=memory,
+        memory_enabled=memory or learn_enabled is True,
         telemetry_enabled=telemetry and not no_telemetry,
         image=image,
+        learn_enabled=learn_enabled,
+        memory_storage_mode=memory_storage_mode,
+        traffic_learning_min_evidence=traffic_learning_min_evidence,
+        memory_project_root=memory_project_root,
         no_http2=no_http2,
         code_aware=code_aware,
         intercept_tool_results=intercept_tool_results,
@@ -524,11 +532,38 @@ def _echo_installed(manifest: DeploymentManifest, *, prefix: str = "Installed pe
 @click.option(
     "--mode",
     "proxy_mode",
-    default="cache",
-    show_default=True,
-    help="Proxy optimization mode. cache = delta-only compression at ~0 prefix-cache busts.",
+    default=None,
+    help="Proxy optimization mode. Omit to use runtime/settings defaults.",
 )
 @click.option("--memory", is_flag=True, help="Enable persistent memory in the proxy runtime.")
+@click.option(
+    "--learn/--no-learn",
+    "learn_enabled",
+    default=None,
+    help="Explicitly enable or disable traffic learning.",
+)
+@click.option(
+    "--memory-storage",
+    "memory_storage_mode",
+    type=click.Choice(["project", "user", "global"], case_sensitive=False),
+    default="project",
+    show_default=True,
+    help="Persistent memory storage scope.",
+)
+@click.option(
+    "--min-evidence",
+    "traffic_learning_min_evidence",
+    type=click.IntRange(min=1),
+    default=5,
+    show_default=True,
+    help="Evidence count required before learning persists a pattern.",
+)
+@click.option(
+    "--memory-project-root",
+    type=click.Path(path_type=str),
+    default="",
+    help="Override the project root used by project memory storage.",
+)
 @click.option(
     "--telemetry",
     is_flag=True,
@@ -606,8 +641,12 @@ def install_apply(
     backend: str,
     anyllm_provider: str | None,
     region: str | None,
-    proxy_mode: str,
+    proxy_mode: str | None,
     memory: bool,
+    learn_enabled: bool | None,
+    memory_storage_mode: str,
+    traffic_learning_min_evidence: int,
+    memory_project_root: str,
     telemetry: bool,
     no_telemetry: bool,
     image: str,
@@ -654,6 +693,10 @@ def install_apply(
         region=region,
         proxy_mode=proxy_mode,
         memory=memory,
+        learn_enabled=learn_enabled,
+        memory_storage_mode=memory_storage_mode,
+        traffic_learning_min_evidence=traffic_learning_min_evidence,
+        memory_project_root=memory_project_root,
         telemetry=telemetry,
         no_telemetry=no_telemetry,
         image=image,
@@ -699,9 +742,8 @@ def install_apply(
 @click.option(
     "--mode",
     "proxy_mode",
-    default="cache",
-    show_default=True,
-    help="Proxy optimization mode. cache = delta-only compression at ~0 prefix-cache busts.",
+    default=None,
+    help="Proxy optimization mode. Omit to use runtime/settings defaults.",
 )
 @click.option(
     "--scope",
@@ -726,6 +768,34 @@ def install_apply(
     help="Tool target to configure when --providers manual is used.",
 )
 @click.option("--memory", is_flag=True, help="Enable persistent memory in the proxy runtime.")
+@click.option(
+    "--learn/--no-learn",
+    "learn_enabled",
+    default=None,
+    help="Explicitly enable or disable traffic learning.",
+)
+@click.option(
+    "--memory-storage",
+    "memory_storage_mode",
+    type=click.Choice(["project", "user", "global"], case_sensitive=False),
+    default="project",
+    show_default=True,
+    help="Persistent memory storage scope.",
+)
+@click.option(
+    "--min-evidence",
+    "traffic_learning_min_evidence",
+    type=click.IntRange(min=1),
+    default=5,
+    show_default=True,
+    help="Evidence count required before learning persists a pattern.",
+)
+@click.option(
+    "--memory-project-root",
+    type=click.Path(path_type=str),
+    default="",
+    help="Override the project root used by project memory storage.",
+)
 @click.option(
     "--telemetry",
     is_flag=True,
@@ -758,11 +828,15 @@ def deploy(
     backend: str,
     anyllm_provider: str | None,
     region: str | None,
-    proxy_mode: str,
+    proxy_mode: str | None,
     scope: str,
     provider_mode: str,
     targets: tuple[str, ...],
     memory: bool,
+    learn_enabled: bool | None,
+    memory_storage_mode: str,
+    traffic_learning_min_evidence: int,
+    memory_project_root: str,
     telemetry: bool,
     no_telemetry: bool,
     image: str,
@@ -786,6 +860,10 @@ def deploy(
         region=region,
         proxy_mode=proxy_mode,
         memory=memory,
+        learn_enabled=learn_enabled,
+        memory_storage_mode=memory_storage_mode,
+        traffic_learning_min_evidence=traffic_learning_min_evidence,
+        memory_project_root=memory_project_root,
         telemetry=telemetry,
         no_telemetry=no_telemetry,
         image=image,
@@ -809,6 +887,18 @@ def install_status(profile: str) -> None:
     click.echo(f"Runtime:    {manifest.runtime_kind}")
     click.echo(f"Supervisor: {manifest.supervisor_kind}")
     click.echo(f"Scope:      {manifest.scope}")
+    click.echo(f"Mode:       {getattr(manifest, 'proxy_mode', None) or 'runtime default'}")
+    click.echo(
+        f"Memory:     {'enabled' if getattr(manifest, 'memory_enabled', False) else 'disabled'}"
+    )
+    learn_enabled = getattr(manifest, "learn_enabled", None)
+    learning = (
+        "runtime default" if learn_enabled is None else ("enabled" if learn_enabled else "disabled")
+    )
+    click.echo(f"Learning:   {learning}")
+    click.echo(f"Storage:    {getattr(manifest, 'memory_storage_mode', 'project')}")
+    click.echo(f"Min evidence: {getattr(manifest, 'traffic_learning_min_evidence', 5)}")
+    click.echo(f"Project root: {getattr(manifest, 'memory_project_root', '') or 'runtime default'}")
     click.echo(f"Port:       {manifest.port}")
     click.echo(f"Status:     {runtime_status(manifest)}")
     click.echo(f"Healthy:    {'yes' if probe_ready(manifest.health_url) else 'no'}")

headroom/install/models.py

@@ -102,9 +102,13 @@ class DeploymentManifest:
     backend: str
     anyllm_provider: str | None = None
     region: str | None = None
-    proxy_mode: str = "cache"
+    proxy_mode: str | None = None
     memory_enabled: bool = False
     memory_db_path: str = ""
+    learn_enabled: bool | None = None
+    memory_storage_mode: str = "project"
+    traffic_learning_min_evidence: int = 5
+    memory_project_root: str = ""
     telemetry_enabled: bool = True
     image: str = "ghcr.io/headroomlabs-ai/headroom:latest"
     service_name: str = "headroom"

headroom/install/planner.py

@@ -129,10 +129,14 @@ def build_manifest(
     backend: str,
     anyllm_provider: str | None,
     region: str | None,
-    proxy_mode: str,
+    proxy_mode: str | None,
     memory_enabled: bool,
     telemetry_enabled: bool,
     image: str,
+    learn_enabled: bool | None = None,
+    memory_storage_mode: str = "project",
+    traffic_learning_min_evidence: int = 5,
+    memory_project_root: str = "",
     no_http2: bool = False,
     code_aware: bool | None = None,
     intercept_tool_results: bool = False,
@@ -166,7 +170,6 @@ def build_manifest(
     base_env = {
         "HEADROOM_PORT": str(port),
         "HEADROOM_HOST": "127.0.0.1",
-        "HEADROOM_MODE": proxy_mode,
         "HEADROOM_BACKEND": backend,
     }
     if anyllm_provider:
@@ -221,11 +224,11 @@ def build_manifest(
         "127.0.0.1",
         "--port",
         str(port),
-        "--mode",
-        proxy_mode,
         "--backend",
         backend,
     ]
+    if proxy_mode is not None:
+        proxy_args.extend(["--mode", proxy_mode])
     proxy_args.append("--telemetry" if telemetry_enabled else "--no-telemetry")
     if memory_enabled:
         proxy_args.append("--memory")
@@ -241,6 +244,13 @@ def build_manifest(
         # runtime the resolved host path is correct, so keep passing it.
         if runtime_kind != RuntimeKind.DOCKER.value:
             proxy_args.extend(["--memory-db-path", str(_paths.memory_db_path())])
+    if learn_enabled is not None:
+        proxy_args.append("--learn" if learn_enabled else "--no-learn")
+    proxy_args.extend(["--memory-storage", memory_storage_mode])
+    if "HEADROOM_MIN_EVIDENCE" not in base_env:
+        proxy_args.extend(["--min-evidence", str(traffic_learning_min_evidence)])
+    if memory_project_root:
+        proxy_args.extend(["--memory-project-root", memory_project_root])
     if anyllm_provider:
         proxy_args.extend(["--anyllm-provider", anyllm_provider])
     if region:
@@ -276,6 +286,10 @@ def build_manifest(
         proxy_mode=proxy_mode,
         memory_enabled=memory_enabled,
         memory_db_path=str(_paths.memory_db_path()),
+        learn_enabled=learn_enabled,
+        memory_storage_mode=memory_storage_mode,
+        traffic_learning_min_evidence=traffic_learning_min_evidence,
+        memory_project_root=memory_project_root,
         telemetry_enabled=telemetry_enabled,
         image=image,
         service_name=f"headroom-{normalized_profile}",

headroom/install/state.py

@@ -78,6 +78,26 @@ def _migrate_deprecated_image(image: Any) -> Any:
     return image
 
 
+def _migrate_manifest_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    """Apply safe in-memory migrations for older deployment manifests."""
+
+    if "image" in payload:
+        payload["image"] = _migrate_deprecated_image(payload["image"])
+    # Mode is represented by the proxy argument generated from ``proxy_mode``.
+    # Older manifests also exported it through the supervisor environment,
+    # creating two competing runtime inputs. Remove only the matching derived
+    # copy; a different or mode-less environment value remains an explicit input.
+    base_env = payload.get("base_env")
+    proxy_mode = payload.get("proxy_mode")
+    if (
+        isinstance(base_env, dict)
+        and proxy_mode is not None
+        and base_env.get("HEADROOM_MODE") == proxy_mode
+    ):
+        base_env.pop("HEADROOM_MODE", None)
+    return payload
+
+
 def load_manifest(profile: str = "default") -> DeploymentManifest | None:
     """Load a deployment manifest when present."""
 
@@ -92,9 +112,7 @@ def load_manifest(profile: str = "default") -> DeploymentManifest | None:
         payload = json.loads(path.read_text(encoding="utf-8"))
         payload["mutations"] = [ManagedMutation(**item) for item in payload.get("mutations", [])]
         payload["artifacts"] = [ArtifactRecord(**item) for item in payload.get("artifacts", [])]
-        if "image" in payload:
-            payload["image"] = _migrate_deprecated_image(payload["image"])
-        return DeploymentManifest(**payload)
+        return DeploymentManifest(**_migrate_manifest_payload(payload))
     except (json.JSONDecodeError, ValueError, TypeError, OSError) as e:
         raise ManifestError(f"deployment profile '{profile}' is corrupt ({path}): {e}") from e
 
@@ -114,9 +132,7 @@ def list_manifests() -> list[DeploymentManifest]:
                 ManagedMutation(**item) for item in payload.get("mutations", [])
             ]
             payload["artifacts"] = [ArtifactRecord(**item) for item in payload.get("artifacts", [])]
-            if "image" in payload:
-                payload["image"] = _migrate_deprecated_image(payload["image"])
-            manifests.append(DeploymentManifest(**payload))
+            manifests.append(DeploymentManifest(**_migrate_manifest_payload(payload)))
         except (OSError, ValueError, TypeError):
             continue
     return manifests

tests/test_cli/test_install_cli.py

@@ -387,6 +387,41 @@ class Manifest:
     assert "Backend:    anthropic" in result.output
 
 
+def test_install_status_reports_effective_memory_options(monkeypatch) -> None:
+    runner = CliRunner()
+
+    class Manifest:
+        profile = "default"
+        preset = "persistent-service"
+        runtime_kind = "python"
+        supervisor_kind = "service"
+        scope = "user"
+        port = 8787
+        backend = "anthropic"
+        health_url = "http://127.0.0.1:8787/readyz"
+        proxy_mode = None
+        memory_enabled = True
+        learn_enabled = False
+        memory_storage_mode = "global"
+        traffic_learning_min_evidence = 7
+        memory_project_root = "/tmp/scratch-project"
+
+    monkeypatch.setattr("headroom.cli.install.load_manifest", lambda profile: Manifest())
+    monkeypatch.setattr("headroom.cli.install.runtime_status", lambda manifest: "running")
+    monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: True)
+    monkeypatch.setattr("headroom.cli.install.probe_json", lambda url: {"config": {}})
+
+    result = runner.invoke(main, ["install", "status"])
+
+    assert result.exit_code == 0, result.output
+    assert "Mode:       runtime default" in result.output
+    assert "Memory:     enabled" in result.output
+    assert "Learning:   disabled" in result.output
+    assert "Storage:    global" in result.output
+    assert "Min evidence: 7" in result.output
+    assert "Project root: /tmp/scratch-project" in result.output
+
+
 def test_install_restart_uses_internal_helpers(monkeypatch) -> None:
     runner = CliRunner()
     calls: list[str] = []