refactor(core): add shared runtime orchestration (#1002)

Extracts runtime, indexing, and index orchestration from the cloud platform into the local-first core: session-explicit stateless repositories, accepted-note mutation runners with optimistic concurrency (db_version CAS), note materialization with per-note worker routing and crash recovery, scan reconciliation with delete re-verification and unreadable-subtree carry-through, directory/project delete runners with structured errors and relation cleanup, and the relay-persistence contracts (base-checksum precondition, superseded-content live updates).

Verified against the full adversarial review: all 28 confirmed findings fixed with regression tests, plausible findings adjudicated and fixed, all review threads resolved. Follow-up structure campaign: #1053.

Signed-off-by: phernandez <paul@basicmachines.co>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: phernandez

AGENTS.md

@@ -22,9 +22,10 @@ See the [README.md](README.md) file for a project overview.
 - Run unit tests (Postgres): `just test-unit-postgres`
 - Run integration tests (SQLite): `just test-int-sqlite`
 - Run integration tests (Postgres): `just test-int-postgres`
-- Run impacted tests: `just testmon` (pytest-testmon; only tests affected by changed code)
+- Run impacted tests: `just fast-test` or `just testmon` (pytest-testmon; only tests affected by changed code)
 - Run MCP smoke test: `just test-smoke`
-- Fast local loop: `just fast-check` (default iteration flow)
+- Fast static check: `just fast-check` (fix, format, typecheck)
+- Fast test loop: `just fast-test` (pytest-testmon impacted tests)
 - Local consistency check: `just doctor`
 - Run all consolidated agent package checks: `just package-check`
 - Run Claude Code plugin checks: `just package-check-claude-code`
@@ -39,7 +40,7 @@ See the [README.md](README.md) file for a project overview.
 - Type check: `just typecheck` or `uv run ty check src tests test-int`
 - Type check (pyright): `just typecheck-pyright` or `uv run pyright`
 - Format: `just format` or `uv run ruff format .`
-- Run all code checks: `just check` (runs lint, format, typecheck, test)
+- Run all static code checks: `just check` (runs lint, format, typecheck)
 - Create db migration: `just migration "Your migration message"`
 - Run development MCP Inspector: `just run-inspector`
 
@@ -54,10 +55,11 @@ See the [README.md](README.md) file for a project overview.
 ### Code/Test/Verify Loop (fast path)
 
 1) **Code:** make changes.
-2) **Test:** `just fast-check` (lint/format/typecheck + pytest-testmon impacted tests for changed code).
-3) **Verify:** `just doctor` (end-to-end file ↔ DB loop in a temp project).
-4) **Package verify:** `just package-check` when changes touch `plugins/`, `skills/`, `integrations/`, package metadata, or release wiring.
-5) **Full gate (when needed):** `just test` or `just check` for SQLite + Postgres.
+2) **Check:** `just fast-check` (fix, format, typecheck; no tests).
+3) **Test:** `just fast-test` for pytest-testmon impacted tests, or a targeted `uv run pytest ...` command.
+4) **Verify:** `just doctor` (end-to-end file ↔ DB loop in a temp project).
+5) **Package verify:** `just package-check` when changes touch `plugins/`, `skills/`, `integrations/`, package metadata, or release wiring.
+6) **Full gate (when needed):** `just test` for SQLite + Postgres.
 
 Run `just test-smoke` when you specifically need the MCP smoke flow.
 

justfile

@@ -27,7 +27,9 @@
     synchronize_projects,
 )
 import logfire
+from basic_memory.cloud.note_content_materialization import drain_pending_materializations
 from basic_memory.config import init_api_logging
+from basic_memory.deps.services import drain_background_tasks
 from basic_memory.services.exceptions import EntityAlreadyExistsError
 from basic_memory.services.initialization import initialize_app
 from basic_memory.workspace_context import (
@@ -67,10 +69,10 @@ async def lifespan(app: FastAPI):  # pragma: no cover
         app.state.session_maker = session_maker
         logger.info("Database connections cached in app state")
 
-        # Create and start sync coordinator (lifecycle centralized in coordinator)
-        sync_coordinator = container.create_sync_coordinator()
-        await sync_coordinator.start()
-        app.state.sync_coordinator = sync_coordinator
+        # Create and start local watch coordinator (lifecycle centralized in coordinator)
+        watch_coordinator = container.create_watch_coordinator()
+        await watch_coordinator.start()
+        app.state.watch_coordinator = watch_coordinator
 
     # Proceed with startup
     yield
@@ -82,7 +84,13 @@ async def lifespan(app: FastAPI):  # pragma: no cover
         mode=container.mode.name.lower(),
     ):
         logger.info("Shutting down Basic Memory API")
-        await sync_coordinator.stop()
+        await watch_coordinator.stop()
+        # A local note write returns 202 before its markdown file is written;
+        # SIGTERM can land while that materialization (and the vector sync /
+        # relation resolution it schedules) is still queued. Drain both queues
+        # before the engine closes so an accepted write is never lost.
+        await drain_pending_materializations()
+        await drain_background_tasks()
         await container.shutdown_database()
 
 

src/basic_memory/api/app.py

@@ -17,10 +17,10 @@
 
 from basic_memory import db
 from basic_memory.config import BasicMemoryConfig, ConfigManager
-from basic_memory.runtime import RuntimeMode, resolve_runtime_mode
+from basic_memory.runtime.mode import RuntimeMode, resolve_runtime_mode
 
 if TYPE_CHECKING:  # pragma: no cover
-    from basic_memory.sync import SyncCoordinator
+    from basic_memory.index.watch_coordinator import WatchCoordinator
 
 
 @dataclass
@@ -54,40 +54,43 @@ def create(cls) -> "ApiContainer":  # pragma: no cover
     # --- Runtime Mode Properties ---
 
     @property
-    def should_sync_files(self) -> bool:
-        """Whether file sync should be started.
+    def should_watch_files(self) -> bool:
+        """Whether local file watching should be started.
 
-        Sync is enabled when:
-        - sync_changes is True in config
-        - Not in test mode (tests manage their own sync)
+        Watching is enabled when:
+        - index_changes is True in config
+        - Not in test mode (tests manage their own watcher lifecycle)
+        - Not in cloud mode (cloud handles storage events differently)
         """
-        return self.config.sync_changes and not self.mode.is_test
+        return self.config.index_changes and not self.mode.is_test and not self.mode.is_cloud
 
     @property
-    def sync_skip_reason(self) -> str | None:  # pragma: no cover
-        """Reason why sync is skipped, or None if sync should run.
+    def watch_skip_reason(self) -> str | None:  # pragma: no cover
+        """Reason why local watching is skipped, or None if it should run.
 
-        Useful for logging why sync was disabled.
+        Useful for logging why local watching was disabled.
         """
         if self.mode.is_test:
             return "Test environment detected"
-        if not self.config.sync_changes:
-            return "Sync changes disabled"
+        if self.mode.is_cloud:
+            return "Cloud mode enabled"
+        if not self.config.index_changes:
+            return "Local file watching disabled"
         return None
 
-    def create_sync_coordinator(self) -> "SyncCoordinator":  # pragma: no cover
-        """Create a SyncCoordinator with this container's settings.
+    def create_watch_coordinator(self) -> "WatchCoordinator":  # pragma: no cover
+        """Create a WatchCoordinator with this container's settings.
 
         Returns:
-            SyncCoordinator configured for this runtime environment
+            WatchCoordinator configured for this runtime environment
         """
         # Deferred import to avoid circular dependency
-        from basic_memory.sync import SyncCoordinator
+        from basic_memory.index.watch_coordinator import WatchCoordinator
 
-        return SyncCoordinator(
+        return WatchCoordinator(
             config=self.config,
-            should_sync=self.should_sync_files,
-            skip_reason=self.sync_skip_reason,
+            should_watch=self.should_watch_files,
+            skip_reason=self.watch_skip_reason,
         )
 
     # --- Database Factory ---