feat(cp7): single-file checkpoint save/load

proteus/runtime/memory.py

@@ -9,6 +9,9 @@ imports only pydantic + stdlib and NO other runtime module.
 
 from __future__ import annotations
 
+import re
+from pathlib import Path
+
 from pydantic import BaseModel, Field
 
 
@@ -56,3 +59,28 @@ class MemoryCheckpoint(BaseModel):
     memory_turns: list[MemoryTurn] = Field(default_factory=list)
     outcome: str
     transparent_prompt: str
+
+
+def _safe(name: str) -> str:
+    """Make a model string safe as a single path segment."""
+    return re.sub(r"[^A-Za-z0-9._-]", "_", name) or "model"
+
+
+def save_checkpoint(ckpt: MemoryCheckpoint, root: str | Path = "runs/memory") -> Path:
+    """Write *ckpt* to ``<root>/<safe(model)>/<created_at>.json`` and return the path.
+
+    Creates parent directories. The filename is the (already filesystem-safe)
+    ``created_at`` stamp so on-disk ordering matches creation order.
+    """
+    root = Path(root)
+    directory = root / _safe(ckpt.model)
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / f"{_safe(ckpt.created_at)}.json"
+    path.write_text(ckpt.model_dump_json(), encoding="utf-8")
+    return path
+
+
+def load_checkpoint(path: str | Path) -> MemoryCheckpoint:
+    """Read one MemoryCheckpoint from *path* (raises FileNotFoundError on miss)."""
+    text = Path(path).read_text(encoding="utf-8")
+    return MemoryCheckpoint.model_validate_json(text)

tests/runtime/test_memory.py

@@ -37,3 +37,24 @@ def test_checkpoint_defaults():
     )
     assert ck.motive_category == "survival"
     assert ck.memory_turns == []
+
+
+def test_save_and_load_round_trip(tmp_path):
+    from proteus.runtime.memory import save_checkpoint, load_checkpoint
+
+    ck = _checkpoint()
+    path = save_checkpoint(ck, root=tmp_path)
+    assert path.exists()
+    # model name is in the path; the stamp-derived filename ends in .json
+    assert "demo" in str(path)
+    assert path.suffix == ".json"
+    reloaded = load_checkpoint(path)
+    assert reloaded.model_dump() == ck.model_dump()
+
+
+def test_load_missing_raises(tmp_path):
+    from proteus.runtime.memory import load_checkpoint
+
+    import pytest
+    with pytest.raises(FileNotFoundError):
+        load_checkpoint(tmp_path / "nope.json")