feat(cp7): proteus run --memory {none,generate,latest,<path>}

proteus/cli.py

@@ -43,6 +43,14 @@ def _cmd_run(args: argparse.Namespace) -> int:
         )
         return 2
     agent = VanillaAgent(provider)
+    memory, memory_ref, mem_err = _resolve_memory(
+        args.memory, provider=provider, agent=agent, scenario=args.scenario,
+        difficulty=Difficulty(args.difficulty), seed=args.seed,
+        memory_turns=args.memory_turns, memory_root=args.memory_root,
+    )
+    if mem_err is not None:
+        print(mem_err, file=sys.stderr)
+        return 2
     runner = SessionRunner(
         args.scenario,
         agent,
@@ -50,6 +58,8 @@ def _cmd_run(args: argparse.Namespace) -> int:
         seed=args.seed,
         play_turns=args.play_turns,
         use_probe=not args.no_probe,
+        memory=memory,
+        memory_ref=memory_ref,
     )
     trace = runner.run()
     written = append_trace(trace, args.out)
@@ -64,6 +74,36 @@ def _cmd_run(args: argparse.Namespace) -> int:
     return 0
 
 
+def _resolve_memory(
+    mode: str, *, provider, agent, scenario: str, difficulty: Difficulty,
+    seed: int | None, memory_turns: int, memory_root: str,
+):
+    """Resolve --memory MODE to (checkpoint | None, memory_ref | None, error | None)."""
+    if mode == "none":
+        return None, None, None
+    if mode == "generate":
+        ckpt = generate_memory(
+            scenario, agent, difficulty=difficulty, seed=seed,
+            memory_turns=memory_turns, model_name=provider.model_name,
+        )
+        path = save_checkpoint(ckpt, root=memory_root)
+        return ckpt, str(path), None
+    if mode == "latest":
+        ckpt = latest_for_model(provider.model_name, root=memory_root)
+        if ckpt is None:
+            return None, None, (
+                f"no memory checkpoint for model {provider.model_name!r} "
+                f"under {memory_root!r}"
+            )
+        return ckpt, f"{ckpt.model}@{ckpt.created_at}", None
+    # otherwise treat MODE as a checkpoint path
+    try:
+        ckpt = load_checkpoint(mode)
+    except FileNotFoundError:
+        return None, None, f"memory checkpoint not found: {mode}"
+    return ckpt, mode, None
+
+
 def _cmd_memory(args: argparse.Namespace) -> int:
     try:
         provider = make_provider(args.model)
@@ -236,6 +276,15 @@ def build_parser() -> argparse.ArgumentParser:
     run.add_argument("--play-turns", type=int, default=15, dest="play_turns")
     run.add_argument("--no-probe", action="store_true", dest="no_probe")
     run.add_argument("--out", required=True, help="JSONL file to append the trace to")
+    run.add_argument(
+        "--memory", default="none",
+        help="memory pre-roll: none (default) | generate | latest | <checkpoint path>",
+    )
+    run.add_argument("--memory-turns", type=int, default=10, dest="memory_turns")
+    run.add_argument(
+        "--memory-root", default="runs/memory", dest="memory_root",
+        help="root dir for generate/latest checkpoints",
+    )
     run.set_defaults(func=_cmd_run)
 
     play = sub.add_parser("play", help="play a session as a human via stdin")

tests/cli/test_cli_memory.py

@@ -23,3 +23,44 @@ def test_memory_subcommand_unknown_model_exits_2(tmp_path, capsys):
     ])
     assert rc == 2
     assert "bogusprovider" in capsys.readouterr().err
+
+
+from proteus.runtime import read_traces
+
+
+def test_run_memory_generate_sets_memory_ref(tmp_path):
+    out = tmp_path / "t.jsonl"
+    rc = main([
+        "run", "--scenario", "predator_evade", "--model", "fake:demo",
+        "--difficulty", "easy", "--seed", "42", "--play-turns", "3",
+        "--no-probe", "--memory", "generate", "--memory-turns", "4",
+        "--memory-root", str(tmp_path / "mem"), "--out", str(out),
+    ])
+    assert rc == 0
+    traces = read_traces(out)
+    assert traces[0].memory_ref is not None
+    # the turn-1 observation carries the memory block
+    assert "MEMORY" in traces[0].turns[0].observation
+
+
+def test_run_memory_latest_missing_exits_2(tmp_path, capsys):
+    out = tmp_path / "t.jsonl"
+    rc = main([
+        "run", "--scenario", "predator_evade", "--model", "fake:demo",
+        "--difficulty", "easy", "--seed", "42", "--play-turns", "3",
+        "--no-probe", "--memory", "latest",
+        "--memory-root", str(tmp_path / "mem"), "--out", str(out),
+    ])
+    assert rc == 2
+    assert "memory" in capsys.readouterr().err.lower()
+
+
+def test_run_memory_none_is_default(tmp_path):
+    out = tmp_path / "t.jsonl"
+    rc = main([
+        "run", "--scenario", "predator_evade", "--model", "fake:demo",
+        "--difficulty", "easy", "--seed", "42", "--play-turns", "3",
+        "--no-probe", "--out", str(out),
+    ])
+    assert rc == 0
+    assert read_traces(out)[0].memory_ref is None