Invalidate config cache when file is modified by another process

Add mtime-based cache validation so long-lived processes (like the MCP
stdio server) detect when the config file has been modified externally
(e.g. by `bm project set-cloud` in a separate terminal). This is a
cheap os.stat() call per config access that only triggers a re-read
when the file mtime has actually changed.

Fixes #660

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Drew Cain <groksrc@gmail.com>

Author: groksrc

src/basic_memory/config.py

@@ -629,6 +629,10 @@ def data_dir_path(self) -> Path:
 
 # Module-level cache for configuration
 _CONFIG_CACHE: Optional[BasicMemoryConfig] = None
+# Track config file mtime so cross-process changes (e.g. `bm project set-cloud`
+# in a separate terminal) invalidate the cache in long-lived processes like the
+# MCP stdio server.
+_CONFIG_MTIME: Optional[float] = None
 
 
 class ConfigManager:
@@ -662,13 +666,30 @@ def load_config(self) -> BasicMemoryConfig:
         Environment variables take precedence over file config values,
         following Pydantic Settings best practices.
 
-        Uses module-level cache for performance across ConfigManager instances.
+        Uses module-level cache with file mtime validation so that
+        cross-process config changes (e.g. `bm project set-cloud` in a
+        separate terminal) are picked up by long-lived processes like
+        the MCP stdio server.
         """
-        global _CONFIG_CACHE
+        global _CONFIG_CACHE, _CONFIG_MTIME
 
-        # Return cached config if available
+        # Trigger: cached config exists but the on-disk file may have been
+        # modified by another process (CLI command in a different terminal).
+        # Why: the MCP server is long-lived; without this check it would
+        # serve stale project routing forever.
+        # Outcome: cheap os.stat() per access; re-read only when mtime differs.
         if _CONFIG_CACHE is not None:
-            return _CONFIG_CACHE
+            try:
+                current_mtime = self.config_file.stat().st_mtime
+            except OSError:
+                current_mtime = None
+
+            if current_mtime is not None and current_mtime == _CONFIG_MTIME:
+                return _CONFIG_CACHE
+
+            # mtime changed or file gone — invalidate and fall through to re-read
+            _CONFIG_CACHE = None
+            _CONFIG_MTIME = None
 
         if self.config_file.exists():
             try:
@@ -723,6 +744,12 @@ def load_config(self) -> BasicMemoryConfig:
 
                 _CONFIG_CACHE = BasicMemoryConfig(**merged_data)
 
+                # Record mtime so subsequent calls detect cross-process changes
+                try:
+                    _CONFIG_MTIME = self.config_file.stat().st_mtime
+                except OSError:
+                    _CONFIG_MTIME = None
+
                 # Re-save to normalize legacy config into current format
                 if needs_resave:
                     # Create backup before overwriting so users can revert if needed
@@ -753,10 +780,11 @@ def load_config(self) -> BasicMemoryConfig:
 
     def save_config(self, config: BasicMemoryConfig) -> None:
         """Save configuration to file and invalidate cache."""
-        global _CONFIG_CACHE
+        global _CONFIG_CACHE, _CONFIG_MTIME
         save_basic_memory_config(self.config_file, config)
         # Invalidate cache so next load_config() reads fresh data
         _CONFIG_CACHE = None
+        _CONFIG_MTIME = None
 
     @property
     def projects(self) -> Dict[str, str]:

test-int/conftest.py

@@ -258,6 +258,7 @@ def config_manager(app_config: BasicMemoryConfig, config_home) -> ConfigManager:
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
 
     config_manager = ConfigManager()
     # Update its paths to use the test directory

tests/cli/conftest.py

@@ -25,6 +25,7 @@ def isolated_home(tmp_path, monkeypatch) -> Path:
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
 
     monkeypatch.setenv("HOME", str(tmp_path))
     if os.name == "nt":

tests/cli/test_json_output.py

@@ -350,6 +350,7 @@ def _write(config_data: dict):
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         config_dir = tmp_path / ".basic-memory"
         config_dir.mkdir(parents=True, exist_ok=True)

tests/cli/test_project_add_with_local_path.py

@@ -27,6 +27,7 @@ def mock_config(tmp_path, monkeypatch):
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
 
     config_dir = tmp_path / ".basic-memory"
     config_dir.mkdir(parents=True, exist_ok=True)

tests/cli/test_project_list_and_ls.py

@@ -29,6 +29,7 @@ def _write(config_data: dict) -> Path:
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         config_dir = tmp_path / ".basic-memory"
         config_dir.mkdir(parents=True, exist_ok=True)

tests/cli/test_project_set_cloud_local.py

@@ -22,6 +22,7 @@ def mock_config(tmp_path, monkeypatch):
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
 
     config_dir = tmp_path / ".basic-memory"
     config_dir.mkdir(parents=True, exist_ok=True)
@@ -68,6 +69,7 @@ def test_set_cloud_no_credentials(self, runner, tmp_path, monkeypatch):
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         config_dir = tmp_path / ".basic-memory"
         config_dir.mkdir(parents=True, exist_ok=True)
@@ -91,6 +93,7 @@ def test_set_cloud_with_oauth_session(self, runner, tmp_path, monkeypatch):
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         config_dir = tmp_path / ".basic-memory"
         config_dir.mkdir(parents=True, exist_ok=True)
@@ -161,18 +164,21 @@ def test_set_local_clears_workspace_id(self, runner, mock_config):
 
         # Manually set workspace_id on the project
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
         config_data = json.loads(mock_config.read_text())
         config_data["projects"]["research"]["mode"] = "cloud"
         config_data["projects"]["research"]["workspace_id"] = "11111111-1111-1111-1111-111111111111"
         mock_config.write_text(json.dumps(config_data, indent=2))
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         # Set back to local
         result = runner.invoke(app, ["project", "set-local", "research"])
         assert result.exit_code == 0
 
         # Verify workspace_id was cleared
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
         updated_data = json.loads(mock_config.read_text())
         assert updated_data["projects"]["research"]["workspace_id"] is None
         assert updated_data["projects"]["research"]["mode"] == "local"
@@ -187,6 +193,7 @@ def test_set_cloud_with_workspace_stores_workspace_id(self, runner, mock_config,
         from basic_memory.schemas.cloud import WorkspaceInfo
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         async def fake_get_available_workspaces():
             return [
@@ -210,6 +217,7 @@ async def fake_get_available_workspaces():
 
         # Verify workspace_id was persisted
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
         updated_data = json.loads(mock_config.read_text())
         assert (
             updated_data["projects"]["research"]["workspace_id"]
@@ -222,6 +230,7 @@ def test_set_cloud_with_workspace_not_found(self, runner, mock_config, monkeypat
         from basic_memory.schemas.cloud import WorkspaceInfo
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         async def fake_get_available_workspaces():
             return [
@@ -249,17 +258,20 @@ def test_set_cloud_uses_default_workspace_when_no_flag(self, runner, mock_config
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         # Set default_workspace in config
         config_data = json.loads(mock_config.read_text())
         config_data["default_workspace"] = "global-default-tenant-id"
         mock_config.write_text(json.dumps(config_data, indent=2))
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         result = runner.invoke(app, ["project", "set-cloud", "research"])
         assert result.exit_code == 0
 
         # Verify workspace_id was set from default
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
         updated_data = json.loads(mock_config.read_text())
         assert updated_data["projects"]["research"]["workspace_id"] == "global-default-tenant-id"

tests/cli/test_workspace_commands.py

@@ -76,6 +76,7 @@ def _setup_config(self, monkeypatch):
         monkeypatch.setenv("HOME", str(temp_path))
         monkeypatch.setenv("BASIC_MEMORY_CONFIG_DIR", str(config_dir))
         basic_memory.config._CONFIG_CACHE = None
+        basic_memory.config._CONFIG_MTIME = None
 
         config_manager = ConfigManager()
         test_config = BasicMemoryConfig(
@@ -106,6 +107,7 @@ async def fake_get_available_workspaces(context=None):
 
         # Verify config was updated
         basic_memory.config._CONFIG_CACHE = None
+        basic_memory.config._CONFIG_MTIME = None
         config = ConfigManager().config
         assert config.default_workspace == "11111111-1111-1111-1111-111111111111"
 

tests/conftest.py

@@ -138,6 +138,7 @@ def config_manager(app_config: BasicMemoryConfig, config_home: Path, monkeypatch
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
 
     # Create a new ConfigManager that uses the test home directory
     config_manager = ConfigManager()

tests/services/test_project_service.py

@@ -778,6 +778,7 @@ async def test_add_project_with_project_root_sanitizes_paths(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         test_cases = [
             # (project_name, user_path, expected_sanitized_name)
@@ -845,6 +846,7 @@ async def test_add_project_with_project_root_rejects_escape_attempts(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         # All of these should succeed by being sanitized to paths under project_root
         # The sanitization removes dangerous patterns, so they don't escape
@@ -931,6 +933,7 @@ async def test_add_project_with_project_root_normalizes_case(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         test_cases = [
             # (input_path, expected_normalized_path)
@@ -985,6 +988,7 @@ async def test_add_project_with_project_root_detects_case_collisions(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         # First, create a project with lowercase path
         first_project = "documents-project"
@@ -1159,6 +1163,7 @@ async def test_add_project_nested_validation_with_project_root(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
 
         parent_project_name = f"cloud-parent-{os.urandom(4).hex()}"
         child_project_name = f"cloud-child-{os.urandom(4).hex()}"