[BUG] Move note to different project fails

[phernandez]

Bug Description

A user reported an issue asking the AI to move a file to a new project. The ai attempted the operation, but it was not clear that it did not complete successfully.

Expected Behavior

We don't currently support moving files to a new project. The AI assistant should provide clear feedback to the user.

Actual Behavior

The move_note tool should

• return a clear message explaining that notes can't be moved
• prompt the assistant to recreate the note in the new project

or the we should add support for moving a note to a new project directly in the code. This is problematic because we would have to pass two project values to the move note operation and we would need an api change.

[phernandez]

@claude can you consider some options for addressing this issue?

[claude]

Claude finished @phernandez's task —— View job

---

Analysis Complete

I've thoroughly analyzed the cross-project move issue and have several solution options to consider.

Current State Analysis

The move_note tool is well-implemented for within-project moves but has poor user experience for cross-project attempts:

What happens now:

• User requests cross-project move via AI assistant
• move_note tool silently fails or provides unclear feedback
• User doesn't understand why the operation didn't work
• No guidance on alternative approaches

Technical Architecture:

• Projects are isolated at database level (separate project_id)
• Single SQLite database with per-project filtering
• File systems are completely separate directory trees
• All existing operations are project-scoped

Solution Options

Option 1: Enhanced Error Messaging (Low Complexity) ⭐

Approach: Detect cross-project moves and provide clear guidance

Implementation:

• Add project detection logic to move_note tool
• Return descriptive error with specific guidance
• Suggest alternative workflow (copy/recreate pattern)

Pros:

• Quick to implement (~1-2 hours)
• Maintains current architecture
• Clear user feedback
• No API changes needed

Cons:

• Doesn't solve the underlying user need
• Requires manual workaround steps

Option 2: Full Cross-Project Move Support (High Complexity)

Approach: Implement true cross-project moves

Implementation:

• New API endpoints accepting source/destination projects
• Complex transaction handling across projects
• Link resolution and update logic
• Database migration for project ID changes
• Comprehensive rollback mechanisms

Pros:

• Solves user need completely
• Professional feature completeness
• Future-proofs the system

Cons:

• High complexity (2-3 weeks development)
• API breaking changes required
• Complex edge case handling
• Risk of data corruption if not perfect

Option 3: Copy-and-Delete Workflow (Medium Complexity)

Approach: Implement as two-step operation

Implementation:

• New copy_note_to_project(identifier, target_project, new_path?) tool
• Enhanced delete_note with confirmation
• AI assistant guided workflow
• Optional: move_note_to_project wrapper combining both

Pros:

• Safer than true move (explicit two steps)
• Moderate complexity (~1 week)
• Clear user control over process
• Preserves audit trail

Cons:

• Two-step process may feel clunky
• Temporary duplication of notes
• Still requires cross-project operations

Option 4: Export/Import Pattern (Medium Complexity)

Approach: Use existing export/import mechanisms

Implementation:

• Export single note to standardized format
• Import into target project
• AI assistant orchestrates the workflow
• Optional cleanup of source note

Pros:

• Leverages existing export/import infrastructure
• Clear semantic separation
• Works with external tools
• Safe and reversible

Cons:

• May not preserve all metadata
• Multi-step user experience
• Requires export/import feature completeness

Recommendation: Start with Option 1, Plan for Option 3

Immediate Solution (Option 1)

Implement enhanced error messaging now because:

1. User Experience: Eliminates confusion immediately
2. Low Risk: No architectural changes
3. Quick Win: Can be implemented and deployed this week
4. Guidance Value: Helps users understand the system better

Implementation approach:

# In move_note tool, detect cross-project scenarios
def detect_cross_project_move(identifier, destination_path, current_project):
    # Check if destination path references different project
    # Return helpful error message with alternatives

error_message = """
Cannot move notes between different projects directly. 

Alternative approaches:
1. Switch to source project: switch_project("{source_project}")
2. Read the note content: read_note("{identifier}")  
3. Switch to target project: switch_project("{target_project}")
4. Create the note in new location: write_note(title, content, folder)
5. Delete from source project if desired

This preserves your knowledge while moving it between projects safely.
"""

Future Enhancement (Option 3)

Plan copy_note_to_project tool for next quarter because:

1. User Demand: If users frequently need this, build proper tooling
2. Safety First: Copy-then-delete is safer than atomic move
3. Incremental: Can build on Option 1's validation logic
4. API Evolution: Allows gradual API enhancement

Why Not Option 2?

Full cross-project moves are high risk, high complexity for a relatively uncommon operation. The copy-and-delete pattern is safer and more explicit about what's happening.

Implementation Plan

Phase 1 (This Week):

• Enhance move_note error detection
• Add cross-project validation
• Improve error messaging with alternatives
• Update MCP tool description

Phase 2 (Next Quarter, if demand exists):

• Implement copy_note_to_project tool
• Add project validation helpers
• Create guided workflow prompts
• Comprehensive testing

This approach balances immediate user needs with long-term system health while avoiding over-engineering a complex feature before we understand usage patterns.

---

[phernandez]

@claude cool. Can you make a PR for option 1, improving the guidance in the tool response? Also, lets make an integration test in the test-int dir validating the behavior.

[claude]

Claude finished @phernandez's task —— View job • claude/issue-157-20250620_141726 • Create PR ➔

---

Implementation Complete ✅

Enhanced move_note tool with cross-project detection:

• Added _detect_cross_project_move_attempt() function to detect project names in destination paths
• Added specific error messages for detected cross-project moves vs potential cross-project moves
• Integrated detection into main move_note function before API call
• Provides clear guidance on proper cross-project workflow (read → switch → write → delete)

Integration tests added:

• test_move_note_cross_project_detection() - Tests exact project name detection in paths
• test_move_note_potential_cross_project_guidance() - Tests project-like keyword detection
• test_move_note_normal_moves_still_work() - Ensures normal moves aren't affected

Key Features:

• Detects project names in destination paths (e.g., "other-project/file.md")
• Detects project-like keywords ("project", "workspace", "repo")
• Provides step-by-step guidance for cross-project moves
• Does not interfere with normal within-project moves
• Gracefully handles detection errors without breaking functionality

Changes Committed

• ✅ Updated src/basic_memory/mcp/tools/move_note.py with cross-project detection
• ✅ Added integration tests in test-int/mcp/test_move_note_integration.py
• ✅ Commit: f995258 - "feat: enhance move_note tool with cross-project detection and guidance"

---

[phernandez]

@claude can you tell me if the tool usage docs are unclear for move_note?

@mcp.tool(
    description="Move a note to a new location, updating database and maintaining links.",
)
async def move_note(
    identifier: str,
    destination_path: str,
    project: Optional[str] = None,
) -> str:
    """Move a note to a new file location within the same project.

    Args:
        identifier: Exact entity identifier (title, permalink, or memory:// URL).
                   Must be an exact match - fuzzy matching is not supported for move operations.
                   Use search_notes() or read_note() first to find the correct identifier if uncertain.
        destination_path: New path relative to project root (e.g., "work/meetings/2025-05-26.md")
        project: Optional project name (defaults to current session project)

    Returns:
        Success message with move details

    Examples:
        # Move to new folder (exact title match)
        move_note("My Note", "work/notes/my-note.md")

        # Move by exact permalink
        move_note("my-note-permalink", "archive/old-notes/my-note.md")

        # Specify project with exact identifier
        move_note("My Note", "archive/my-note.md", project="work-project")

        # If uncertain about identifier, search first:
        # search_notes("my note")  # Find available notes
        # move_note("docs/my-note-2025", "archive/my-note.md")  # Use exact result

    Note: This operation moves notes within the specified project only. Moving notes
    between different projects is not currently supported.

    The move operation:
    - Updates the entity's file_path in the database
    - Moves the physical file on the filesystem
    - Optionally updates permalinks if configured
    - Re-indexes the entity for search
    - Maintains all observations and relations
    """

The intended usage is that the you can move a note within a particular project by passing the project arg. This is meant for the case where the project is not currently active. It is not meant to move a note to a different project. That use case is not supported because it would require us to pass two project args, source and destination.

Examples:

Supported:

• AI is working in current project: "main"
• Project "notes" has a note "meeting_notes.md"
• move_note("meeting_notes.md", "archive/meeting_notes.md", project="notes")

Ambiguous:

• AI is working in current project: "main"
• Project "main" has a note "meeting_notes.md"
• move_note("meeting_notes.md", "meeting_notes.md", project="notes")
• this would look in the project "notes" for a note called "meeting_notes.md" and try to rename it to the same value

Would imporoving the tool usage docs help here?

[claude]

Claude finished @phernandez's task —— View job

---

Analysis: move_note Documentation Clarity Issues

Yes, the documentation is unclear and needs improvement. The current docstring has several confusing aspects that would mislead AI assistants about the project parameter's purpose.

Todo List

• Read current move_note tool implementation
• Analyze docstring clarity issues
• Provide specific improvement recommendations

Key Clarity Problems

1. Contradictory Language

• Line 220: "Move a note to a new file location within the same project"
• But then provides a project parameter that can specify a different project
• This creates cognitive dissonance about what "same project" means

2. Ambiguous Parameter Description

• Current: project: Optional project name (defaults to current session project)
• Problem: Doesn't explain that when specified, ALL operations happen within that project
• Misleading: Implies it's just a "default" rather than a context switch

3. Insufficient Examples

• Current examples don't clearly demonstrate the cross-project context scenario
• Missing example showing: "AI working in project A, but moving note within project B"

4. Unclear Scope Statement

• "Moving notes between different projects is not currently supported" appears to contradict the project parameter

Specific Improvement Recommendations

1. Fix the Main Description

# Current (confusing):
"""Move a note to a new file location within the same project.

# Improved (clear):
"""Move a note to a new file location within a specified project.

2. Clarify the Project Parameter

# Current (ambiguous):
project: Optional project name (defaults to current session project)

# Improved (explicit):
project: Optional project name to operate within. If specified, the note will be 
         moved within that project's context, not the current session project.
         Defaults to current session project if not specified.

3. Add Clear Examples

# Add this example to demonstrate cross-project context:
# Move note within different project (while AI is in project "main")
move_note("meeting_notes.md", "archive/meeting_notes.md", project="work-notes")
# ^ This finds "meeting_notes.md" in the "work-notes" project and moves it there

4. Clarify the Limitation Statement

# Current (confusing):
Note: This operation moves notes within the specified project only. Moving notes
between different projects is not currently supported.

# Improved (clearer):
Note: This operation moves notes within a single project only. The 'project' 
parameter specifies which project to operate within, not a destination project.
Moving notes FROM one project TO another project is not supported.

Recommended Complete Docstring

"""Move a note to a new file location within a specified project.

Args:
    identifier: Exact entity identifier (title, permalink, or memory:// URL).
               Must be an exact match - fuzzy matching is not supported for move operations.
               Use search_notes() or read_note() first to find the correct identifier if uncertain.
    destination_path: New path relative to project root (e.g., "work/meetings/2025-05-26.md")
    project: Optional project name to operate within. If specified, the note will be 
             found and moved within that project's context, not the current session project.
             Defaults to current session project if not specified.

Returns:
    Success message with move details

Examples:
    # Move within current session project
    move_note("My Note", "work/notes/my-note.md")

    # Move within a different project (AI in "main", moving note in "work-project")  
    move_note("Meeting Notes", "archive/meeting-notes.md", project="work-project")
    # ^ Finds "Meeting Notes" in "work-project" and moves it to archive within "work-project"

    # If uncertain about identifier, search first:
    # search_notes("my note")  # Find available notes
    # move_note("docs/my-note-2025", "archive/my-note.md")  # Use exact result

Note: This operation moves notes within a single project only. The 'project' 
parameter specifies which project context to operate within, not a destination project.
Moving notes FROM one project TO another project is not supported.

The move operation:
- Updates the entity's file_path in the database
- Moves the physical file on the filesystem  
- Optionally updates permalinks if configured
- Re-indexes the entity for search
- Maintains all observations and relations
"""

Impact on AI Assistant Behavior

The current unclear documentation could lead to:

• Confusion about when to use the project parameter
• Incorrect assumptions about cross-project moves being supported
• Poor error handling when users request actual cross-project moves

The improved documentation would:

• Clearly communicate the single-project limitation
• Explicitly explain the project parameter's context-switching behavior
• Provide better examples for both same-project and cross-project-context scenarios
• Reduce confusion about what operations are and aren't supported

Summary

Yes, improving the tool usage documentation would significantly help. The current docstring is ambiguous about the project parameter's purpose and creates confusion about supported vs unsupported operations. The recommended changes would provide much clearer guidance for AI assistants using this tool.

---