fix: respect --project flag in background sync (fixes #434)

[divideby0]

Description

Fixes #434 - Background sync and watch service now respect the --project flag, providing complete project isolation.

Problem

When starting the MCP server with --project=<project-name>:

• ✅ MCP tools correctly constrained to specified project (explicit parameters ignored)
• ❌ Background sync ran on ALL active projects
• ❌ Watch service monitored ALL project directories

This architectural inconsistency meant the --project flag only provided partial isolation:

• MCP tools were locked to one project
• Background infrastructure still processed all projects
• Caused unnecessary resource usage and slower startup when multiple projects were configured

Solution

Added filtering logic in initialize_file_sync() to check the BASIC_MEMORY_MCP_PROJECT environment variable and filter active_projects accordingly.

Changes

• src/basic_memory/services/initialization.py

  • Added os import
  • Filter active_projects by BASIC_MEMORY_MCP_PROJECT env var (lines 105-109)
  • Added logging when background sync is constrained

• tests/services/test_initialization.py

  • Added test_initialize_file_sync_respects_project_constraint
  • Verifies only 1 background task created when env var is set (instead of 3)
  • Uses @patch.dict("os.environ", {"BASIC_MEMORY_MCP_PROJECT": "project1"})

Testing

All existing tests pass (7/7):

$ uv run pytest tests/services/test_initialization.py -v
...
============================== 7 passed in 4.52s ===============================

New test specifically verifies:

• When 3 projects are active but BASIC_MEMORY_MCP_PROJECT=project1 is set
• Only 1 background sync task is created (for project1)
• Watch service still starts normally

Impact

Before

With 12 projects configured:

• Background sync: 12 projects
• Watch service: 12 directories
• Resource usage: 12× CPU, memory, file handles

After

With 12 projects configured + --project=myproject:

• Background sync: 1 project (myproject)
• Watch service: 1 directory (myproject)
• Resource usage: 1× CPU, memory, file handles

Project Constraint Behavior

The --project flag creates absolute project isolation via the BASIC_MEMORY_MCP_PROJECT environment variable:

MCP Tools (existing behavior - unchanged)

• BASIC_MEMORY_MCP_PROJECT has Priority 1 in resolve_project_parameter()
• Overrides explicit project parameters in tool calls
• Example: --project=foo + read_note(..., project="bar") → uses foo, not bar

Background Sync (new behavior - now aligned)

• Filters active_projects by BASIC_MEMORY_MCP_PROJECT
• Watch service only monitors the constrained project directory
• Complete isolation: same project constraint as MCP tools

No Constraint Cases (unchanged)

• No --project flag: All projects available to MCP tools, all projects synced
• default_project_mode=true: MCP tools default to configured project, all projects still synced
  • Rationale: default_project_mode is a convenience default, not isolation
  • Users wanting isolation should use --project flag

Backwards Compatibility

✅ Fully backwards compatible:

• When --project flag is NOT used: syncs all projects (existing behavior)
• When --project flag IS used: syncs only specified project (new behavior, aligns with MCP tool constraint)
• No breaking changes to API or configuration
• default_project_mode behavior unchanged (doesn't constrain sync)

Security Analysis

Ran Semgrep security scan on changed files:

$ semgrep --config=auto src/basic_memory/services/initialization.py tests/services/test_initialization.py
✅ Scan completed successfully.
 • Findings: 0 (0 blocking)
 • Rules run: 927
 • Targets scanned: 2

Result: ✅ No security issues detected

The changes are safe:

• Simple environment variable read (os.environ.get())
• List filtering with no external input
• No SQL injection, command injection, or path traversal risks
• No new dependencies or network calls

Checklist

• Added test coverage for the fix
• All existing tests pass (7/7)
• Code follows project style (ruff compliant)
• Security scan passed (0 findings)
• Fix is minimal and focused
• Relates to issue [BUG] --project flag doesn't constrain mcp's background sync to specified project #434

---

PR implementation assisted by Claude Code (Anthropic)