more docs

Author: kevinjqliu

tests/benchmark/test_memory_benchmark.py

@@ -121,6 +121,7 @@ def test_manifest_cache_memory_growth(memory_catalog: InMemoryCatalog) -> None:
         # Memory growth includes ManifestFile objects, metadata, and other overhead
         # We expect about 5-10 KB per iteration for typical workloads
         # The key improvement is that growth is O(N) not O(N²)
+        # Threshold of 15KB/iteration based on observed behavior - O(N²) would show ~50KB+/iteration
         assert growth_per_iteration < 15000, (
             f"Memory growth per iteration ({growth_per_iteration:.0f} bytes) is too high. "
             "This may indicate the O(N²) cache inefficiency is present."
@@ -168,6 +169,10 @@ def test_memory_after_gc_with_cache_cleared(memory_catalog: InMemoryCatalog) ->
     print("\nResults:")
     print(f"  Memory reclaimed by clearing cache: {memory_reclaimed / 1024:.1f} KB")
 
+    # Verify that clearing the cache actually freed some memory
+    # Note: This may be flaky in some environments due to GC behavior
+    assert memory_reclaimed >= 0, "Memory should not increase after clearing cache"
+
 
 @pytest.mark.benchmark
 def test_manifest_cache_deduplication_efficiency() -> None: