fix: clarify cache docs, skip caching empty graphs

Addresses Copilot review feedback on #661.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mempalace/palace_graph.py

@@ -26,7 +26,8 @@ from .config import MempalaceConfig
 from .palace import get_collection as _get_palace_collection
 from .palace import mine_lock
 
-# Module-level graph cache — mirrors _metadata_cache pattern in mcp_server.py
+# Module-level graph cache with TTL and write-invalidation.
+# Warm cache serves build_graph() in O(1); invalidate_graph_cache() clears on writes.
 _graph_cache_nodes = None
 _graph_cache_edges = None
 _graph_cache_time = 0.0
@@ -66,6 +67,8 @@ def build_graph(col=None, config=None):
     """
     global _graph_cache_nodes, _graph_cache_edges, _graph_cache_time
     now = time.time()
+    # NOTE: warm cache ignores col/config args — intentional for the MCP server's
+    # single-palace use case. Callers switching collections must invalidate first.
     if _graph_cache_nodes is not None and (now - _graph_cache_time) < _GRAPH_CACHE_TTL:
         return _graph_cache_nodes, _graph_cache_edges
 
@@ -124,6 +127,9 @@ def build_graph(col=None, config=None):
             "dates": sorted(data["dates"])[-5:] if data["dates"] else [],
         }
 
+    # Only cache non-empty graphs so new data is picked up immediately
+    # when the palace is first populated.
+    if nodes:
         _graph_cache_nodes = nodes
         _graph_cache_edges = edges
         _graph_cache_time = time.time()

tests/test_palace_graph.py

@@ -119,7 +119,12 @@ class TestBuildGraph:
         assert len(nodes["busy"]["dates"]) <= 5
 
     def test_cache_returns_same_result(self):
-        """Second call within TTL returns cached nodes without re-scanning."""
+        """Second call within TTL returns cached nodes without re-scanning.
+
+        The cache intentionally ignores col/config args when warm — this is
+        correct for the MCP server's single-palace use case. Callers that
+        switch collections must call invalidate_graph_cache() first.
+        """
         col = _make_fake_collection(
             [{"room": "auth", "wing": "wing_code", "hall": "security", "date": "2026-01-01"}]
         )