Refactor: introduce ProjectResolver and unify project selection across MCP/API/CLI

[phernandez]

Refactor: introduce ProjectResolver and unify project selection across MCP/API/CLI

Why

Project resolution logic is scattered (default project, constrained env project, explicit parameters, discovery mode). This leads to inconsistent behavior and duplicated logic.

Scope

• Create a single reusable ProjectResolver (pure logic / small class) that:
  • resolves the effective project given requested project + env constraints + config
  • supports discovery mode (optional)
  • returns a typed result (mode + project name/id + reason)
• Use it in:
  • MCP project resolution (basic_memory/mcp/project_context.py and MCP tools)
  • API project routing (where applicable)
  • CLI commands that infer default project

Acceptance criteria

• One canonical implementation of project resolution (no duplicated decision trees).
• Existing behavior preserved (or changes explicitly documented).
• MCP tool behavior remains fully covered.

Dependencies

• Ideally after containers/config injection work, so resolver is used via injected config.

[claude]

Claude finished @phernandez's task in 3m 27s —— View job

---

Analysis Complete: ProjectResolver Refactor

Task List

• Gather context: Read current project resolution implementation
• Analyze project resolution patterns across MCP/API/CLI
• Identify duplication and inconsistencies
• Propose ProjectResolver design
• Apply appropriate labels for triage
• Provide recommendations and next steps

---

Current State Analysis

I've completed a thorough analysis of the project resolution logic across the codebase. Here's what I found:

1. MCP Layer (src/basic_memory/mcp/project_context.py)

Strengths:

• ✅ Well-defined resolve_project_parameter() with clear three-tier hierarchy
• ✅ Comprehensive test coverage (tests/mcp/test_project_context.py)
• ✅ Handles all modes: cloud mode, CLI constraint (env var), explicit param, default project
• ✅ Supports discovery mode for cross-project tools

Resolution logic:

# Cloud mode: requires explicit project (unless allow_discovery=True)
if config.cloud_mode:
    return project or None (if allow_discovery) or raise ValueError

# Local mode - Priority hierarchy:
# 1. BASIC_MEMORY_MCP_PROJECT env var (CLI --project constraint)
# 2. Explicit project parameter
# 3. config.default_project (if default_project_mode=True)
# 4. None (no resolution)

2. CLI Layer (src/basic_memory/cli/commands/)

Issues:

• ❌ No centralized resolution - scattered across commands
• ❌ Direct access to ConfigManager().config.default_project
• ❌ Inconsistent handling (some commands use get_active_project(), others don't)

Examples of duplication:

• tool.py (lines 110, 145, 182, 262): project_name or config_manager.default_project
• format.py (line 173): Manual default project handling
• command_utils.py: Uses get_active_project() but no standalone CLI resolution

3. API Layer (src/basic_memory/deps.py, src/basic_memory/api/v2/routers/)

Current approach:

• ✅ V1 API: FastAPI dependency injection with ProjectPathDep (path-based)
• ✅ V2 API: Integer project IDs with ProjectIdPathDep (more efficient)
• ✅ Separate resolution endpoint: /v2/projects/resolve (name/permalink → ID)

Issues:

• ⚠️ API depends entirely on path parameters - no default project concept
• ⚠️ Different resolution strategy than MCP/CLI (path-driven vs config-driven)

4. Environment Variables

• BASIC_MEMORY_MCP_PROJECT - CLI constraint for MCP server (takes highest priority)
• Used in: MCP tools, background sync filtering, CLI mcp command

---

Identified Inconsistencies

1. Duplication: Same resolution logic exists in:

   • mcp/project_context.py::resolve_project_parameter() - most complete
   • CLI commands - manual, inconsistent fallback to default_project
   • API deps - path-based, no default project support

2. Missing Coverage:

   • CLI commands don't respect BASIC_MEMORY_MCP_PROJECT env var
   • API has no concept of default project mode
   • No unified "resolution result" type explaining why a project was chosen

3. Behavioral Differences:

   • MCP: Config-driven with fallbacks (env var → param → default → None)
   • CLI: Manual fallback to default_project only
   • API: Path-driven only (no fallbacks)

---

Proposed Solution: ProjectResolver

Design Goals

1. Single source of truth for all project resolution logic
2. Typed results explaining resolution mode and reason
3. Reusable across MCP, API, CLI contexts
4. Preserves existing behavior (no breaking changes)
5. Injectable via dependency injection (fits with container work)

Proposed Implementation

Location: src/basic_memory/services/project_resolver.py

Core Types:

from enum import Enum
from dataclasses import dataclass
from typing import Optional

class ProjectResolutionMode(Enum):
    """How the project was resolved."""
    ENV_CONSTRAINT = "env_constraint"  # BASIC_MEMORY_MCP_PROJECT
    EXPLICIT_PARAM = "explicit_param"  # User-provided parameter
    DEFAULT_PROJECT = "default_project"  # config.default_project
    CLOUD_MODE = "cloud_mode"  # Cloud mode with explicit project
    DISCOVERY = "discovery"  # Discovery mode (no specific project)
    NONE = "none"  # No resolution possible

@dataclass
class ProjectResolution:
    """Result of project resolution with context."""
    project_name: Optional[str]  # Resolved project name (None for discovery)
    mode: ProjectResolutionMode  # How it was resolved
    reason: str  # Human-readable explanation
    
    @property
    def is_resolved(self) -> bool:
        """Whether a specific project was resolved."""
        return self.project_name is not None

class ProjectResolver:
    """Unified project resolution logic."""
    
    def __init__(self, config: BasicMemoryConfig):
        self.config = config
    
    async def resolve(
        self,
        project: Optional[str] = None,
        allow_discovery: bool = False,
        check_env: bool = True,  # For CLI: may want to skip env check
    ) -> ProjectResolution:
        """Resolve project using unified logic.
        
        Resolution priority (local mode):
        1. BASIC_MEMORY_MCP_PROJECT env var (if check_env=True)
        2. Explicit project parameter
        3. config.default_project (if default_project_mode=True)
        4. None (discovery mode if allowed, else error)
        
        Cloud mode: requires explicit project unless allow_discovery=True
        """
        # Implementation here

Integration Points

MCP Layer (project_context.py):

# Replace resolve_project_parameter() with ProjectResolver
async def resolve_project_parameter(
    project: Optional[str] = None,
    allow_discovery: bool = False
) -> Optional[str]:
    """Legacy wrapper for backward compatibility."""
    resolver = ProjectResolver(ConfigManager().config)
    result = await resolver.resolve(project, allow_discovery)
    return result.project_name

CLI Layer (cli/commands/command_utils.py):

async def get_default_project_for_cli() -> Optional[str]:
    """Get default project for CLI commands."""
    resolver = ProjectResolver(ConfigManager().config)
    result = await resolver.resolve(check_env=False)  # CLI ignores env constraint
    return result.project_name

API Layer (optional enhancement):

# Add optional default project support to API if needed
# Currently API is path-driven which is correct for REST semantics
# But could add header-based project selection later

---

Recommendations

Phase 1: Core Implementation (This PR)

1. ✅ Create src/basic_memory/services/project_resolver.py
2. ✅ Implement ProjectResolver class with typed results
3. ✅ Comprehensive unit tests (mirror existing test_project_context.py)
4. ✅ Update mcp/project_context.py to use ProjectResolver internally
5. ✅ Verify all MCP tests still pass (behavior preserved)

Phase 2: CLI Integration (Follow-up PR)

1. Create CLI helper in cli/commands/command_utils.py
2. Replace manual default_project access across CLI commands
3. Add CLI integration tests

Phase 3: API Enhancement (Optional, Future)

• Consider adding optional default project support to API
• Would require middleware or header-based project selection
• Lower priority since API's path-based approach is RESTful

---

Dependencies & Ordering

Mentioned in issue:

Ideally after containers/config injection work, so resolver is used via injected config

Current assessment:

• ✅ Config is already injectable (BasicMemoryConfig via ConfigManager)
• ✅ Can implement now without waiting for container work
• ✅ When container work lands, switch from ConfigManager() to injected config

Suggested approach:

1. Implement ProjectResolver now with ConfigManager() dependency
2. When container/DI work completes, refactor to inject config
3. This allows incremental progress without blocking on other work

---

Issue Classification

Type: Enhancement / Refactoring
Priority: Medium
Component: MCP, CLI, Architecture
Complexity: Medium

Estimated scope:

• Phase 1 (core): ~200 LOC + ~150 LOC tests
• Phase 2 (CLI): ~100 LOC changes across 5-7 files
• Well-scoped with clear acceptance criteria

Label applied: enhancement

---

Summary

This is a well-defined refactoring task with clear benefits:

✅ Reduces duplication - Single implementation replacing 3+ scattered versions
✅ Improves maintainability - One place to update project resolution logic
✅ Better observability - Typed results explain how projects were resolved
✅ Preserves behavior - Can maintain backward compatibility during transition
✅ Aligns with architecture - Fits dependency injection pattern

The existing MCP implementation in project_context.py serves as an excellent starting point - it already handles all the complex cases (cloud mode, env constraints, discovery mode). The refactor would extract and enhance this logic into a reusable service.

Ready to proceed with implementation when prioritized. I recommend starting with Phase 1 (core ProjectResolver) as it provides immediate value and can be tested in isolation before broader integration.