Add completion signal for bm watch indexing

[bm-clawd]

Currently there's no built-in way to detect when bm watch has finished processing a batch of file changes. Users need to poll bm status or use search_notes as a proxy to detect completion.

Use cases:

• Bulk imports: Writing hundreds of notes and waiting for indexing to complete before querying
• Benchmarking: Need deterministic timing for when index is fully up-to-date
• Integration testing: Synchronizing test steps that depend on indexed data

Current workarounds:

• Poll bm status until files_out_of_sync hits 0
• Search for a known note from the batch and wait for it to appear
• Run bm reindex (synchronous but reprocesses everything, slow for large projects)

Potential solutions:

1. MCP notification: Emit an event when watch completes a batch (e.g., indexing_complete notification)
2. bm status --wait flag: Block until sync complete, then exit (like git status but waits)
3. Event stream: Watch emits structured events (indexing_started, indexing_complete) on stdout
4. Progress indicator: Simple output like "Indexed 71/71 files" when batch completes

Context:

• @Brennall: bulk importing 400 notes, needs to know when batch is indexed before querying
• @groksrc: ran into this while working on benchmarks

Prefer option 1 (MCP notification) or option 2 (--wait flag) for cleanest integration with existing tooling.

[claude]

Claude finished @bm-clawd's task in 47s —— View job

---

Issue Triage

• Analyze issue type and context
• Check for duplicate issues
• Assess complexity by reviewing relevant code
• Apply labels
• Provide triage summary

---

Triage Summary

Type: Feature request — new functionality for detecting when bm watch finishes indexing a batch of file changes

Priority: Medium — affects specific workflows (bulk imports, benchmarking, integration testing) but has workable workarounds today

Component: Sync/Watch infrastructure, MCP tools

Complexity: Medium — the architecture already has solid foundations to build on

Duplicate: No duplicates found

---

Codebase Analysis

After reviewing the sync infrastructure, here's what exists today and what would need to be added:

What already exists:

• WatchService tracks events with full metadata (WatchEvent objects) and persists state to ~/.basic-memory/watch-status.json
• SyncCoordinator has clean lifecycle management (STARTING, RUNNING, STOPPING states)
• project_info MCP resource already reads and exposes watch status
• Structured event tracking — last 100 events kept in WatchServiceState.recent_events

Key files:

• src/basic_memory/sync/watch_service.py — core watch loop and event tracking
• src/basic_memory/sync/coordinator.py — lifecycle management
• src/basic_memory/schemas/project_info.py — WatchServiceState schema
• ~/.basic-memory/watch-status.json — persisted status file

---

Recommended Approach

The issue's preference for Option 1 (MCP notification) or Option 2 (--wait flag) maps well to what the codebase supports:

Short term — bm status --wait flag (Low complexity):

• The status command already reads files_out_of_sync
• Add a --wait flag that polls until files_out_of_sync == 0 with a configurable timeout
• Implementation: ~30-50 lines in the CLI status command
• Works immediately for bulk import and integration testing use cases

Medium term — MCP notification (Medium complexity):

• WatchService already fires per-file events; add a batch-completion event after each debounced change set is processed
• Emit an MCP notifications/message after each sync batch completes
• Requires adding a callback hook in WatchService and wiring it to the MCP server's notification channel
• Implementation: ~100-150 lines across watch service and MCP server

Longer term — Event stream on stdout (Lower priority):

• When running bm watch interactively, emit structured JSON events for each batch
• Useful for shell scripting and CI pipelines

The --wait flag could be implemented quickly and covers the most immediate use cases (@Brennall's bulk import, @groksrc's benchmarks). The MCP notification approach is cleaner for LLM-driven workflows and would be the natural next step.