Add directory move support to move_note tool

[phernandez]

Summary

Extend the move_note MCP tool to support moving entire directories, not just individual files. Also rename the folder parameter in write_note to directory for consistency.

Motivation

Currently, move_note only moves single files. Users need to move directories to reorganize their knowledge base structure efficiently.

Requirements

1. Add is_directory parameter to move_note

async def move_note(
    identifier: str,
    destination_path: str,
    is_directory: bool = False,  # NEW
    project: Optional[str] = None,
    context: Context | None = None,
) -> str:

When is_directory=True:

• identifier is a directory path (e.g., "docs", "projects/2025")
• destination_path is the new directory path (no file extension required)
• All files within the directory are moved, preserving relative structure

2. Service layer changes

New method in EntityService:

async def move_directory(
    self, source_dir: str, dest_dir: str, project_config, app_config
) -> DirectoryMoveResult:
    # 1. Find all entities with file_path starting with source_dir/
    entities = await self.entity_repository.find_by_directory_prefix(source_dir)
    
    # 2. Validate no conflicts at destination
    # 3. Move each file, updating database
    # 4. Return results (success count, failures, etc.)

3. API endpoint

New endpoint or enhanced existing:

• POST /knowledge/move-directory
• Request: { "source_directory": str, "destination_directory": str }
• Response: { "total_files": int, "successful_moves": int, "failed_moves": int, "errors": [...] }

4. Rename folder → directory in write_note

For naming consistency across all tools:

• write_note(..., folder: str, ...) → write_note(..., directory: str, ...)
• Update docstrings and examples

Existing Infrastructure to Reuse

• EntityRepository.find_by_directory_prefix() - SQL LIKE query for finding entities in a directory
• FileService.move_file() - Atomic file moves with concurrency control
• FileService.ensure_directory() - Creates destination directories
• Existing error handling patterns in move_note

Design Considerations

• Transaction safety: Wrap DB updates in transaction; rollback file moves on failure
• Conflict detection: Check all destination paths before starting moves
• Path transformation: old_path.replace(f"{source}/", f"{dest}/", 1)
• Progress reporting: Return detailed results for large directory moves

Testing Requirements

• Unit tests for path transformation
• Integration tests for directories with 1, 10, 100+ files
• Error cases: permission denied, conflicts, partial failures
• Concurrent directory move operations

Acceptance Criteria

• move_note("docs", "archive/docs", is_directory=True) moves all files in docs/ to archive/docs/
• Nested directories are preserved (e.g., docs/a/b.md → archive/docs/a/b.md)
• Database records updated for all moved files
• Search index re-indexed for all moved files
• Clear error messages for conflicts and failures
• write_note parameter renamed from folder to directory

[claude]

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

---

Issue Analysis Complete ✅

I've analyzed this feature request and prepared a detailed implementation plan.

Issue Triage

Classification:

• Type: Feature request (MCP tool enhancement)
• Component: MCP tools, API, Service layer
• Complexity: Medium-Complex (changes across multiple layers)
• Priority: Medium (UX improvement for knowledge base reorganization)

No Duplicates Found: This is a unique feature request.

Key Findings

The codebase already has excellent infrastructure to build on:

✅ Existing Components:

1. EntityRepository.find_by_directory_prefix() - Optimized SQL LIKE queries for directory listing
2. FileService.move_file() - Atomic file moves with concurrency control
3. EntityService.move_entity() - Complete single-file move logic with:
   • Transaction safety & rollback
   • Permalink updates (configurable)
   • Checksum recalculation
   • Database + filesystem consistency
4. V2 API endpoint /knowledge/entities/{entity_id}/move with stable UUIDs
5. Established test patterns in tests/mcp/test_tool_move_note.py

Proposed Implementation

Minimal approach that extends existing infrastructure:

1. Rename Parameter ✅ Simple

• Change write_note(..., folder: str, ...) → write_note(..., directory: str, ...)
• Update docstrings and examples

2. Add is_directory Parameter to move_note

async def move_note(
    identifier: str,
    destination_path: str,
    is_directory: bool = False,  # NEW - backward compatible
    project: Optional[str] = None,
    context: Context | None = None,
) -> str:

When is_directory=True:

• Find all files using EntityRepository.find_by_directory_prefix()
• Transform paths: new_path = old_path.replace(source_dir, dest_dir, 1)
• Move each file via existing EntityService.move_entity() (reuses all safety logic)
• Return detailed summary with success/failure counts

Example:

move_note("docs", "archive/docs", is_directory=True)
# Moves: docs/a.md → archive/docs/a.md
#        docs/sub/b.md → archive/docs/sub/b.md

3. Service Layer Method

# EntityService.move_directory()
async def move_directory(
    self, source_dir: str, dest_dir: str, 
    project_config, app_config
) -> DirectoryMoveResult:
    # 1. Find all entities in directory
    # 2. Validate no destination conflicts
    # 3. Move files using move_entity()
    # 4. Return detailed results

4. API Endpoint (Optional)

POST /v2/knowledge/move-directory
Request: { "source_directory": str, "destination_directory": str }
Response: { "total_files": int, "successful": int, "failed": int, "errors": [...] }

Design Principles

1. Reuse existing logic - Leverage move_entity() instead of duplicating
2. Fail fast - Validate all paths before moving anything
3. Detailed reporting - Per-file success/failure for debugging
4. Transaction safety - Each file move is atomic (best-effort directory rollback)
5. Backward compatible - is_directory=False default preserves existing behavior

Testing Strategy

Unit Tests (tests/):

• Path transformation logic
• Conflict detection
• Error formatting

Integration Tests (test-int/):

• 1 file, 10 files, 100+ files
• Nested subdirectories preserved
• Error cases: conflicts, permissions, partial failures
• Both SQLite and Postgres

Coverage: Maintains 100% requirement

Questions Before Implementation

Please confirm your preferences:

1. API Endpoint: Add dedicated /v2/knowledge/move-directory endpoint?

   • Yes: Cleaner API, better for future features
   • No: Simpler, faster implementation
   • Recommendation: Yes (follows v2 API patterns)

2. Rollback Strategy: On partial failure:

   • Option A: Best-effort (log failures, continue) ← Matches current behavior
   • Option B: Full rollback (attempt to undo all moves)
   • Recommendation: A

3. Progress Reporting: For 100+ files:

   • Option A: Final summary only ← Simpler MVP
   • Option B: Streaming progress
   • Recommendation: A

4. Proceed with implementation? Or would you like adjustments?

---

Branch: claude/issue-516-20260121-0023 is ready for implementation