[BUG] File extension removed when renaming files

[groksrc]

Bug Description

When renaming a file using Basic Memory, the ".md" extension is frequently removed, making the file unrecognizable both in Finder and Obsidian. This forces users to manually add the extension back each time.

Steps To Reproduce

Steps to reproduce the behavior:

1. Have Basic Memory installed
2. Use the rename/move functionality to rename a markdown file
3. The ".md" extension is removed from the filename
4. File becomes unrecognizable in Finder and Obsidian

Expected Behavior

When renaming a file, the file extension should be preserved. If renaming "document.md" to "new-document", the result should be "new-document.md".

Actual Behavior

The file extension is removed during the rename operation. Files lose their ".md" extension and become unrecognizable to both the file system (Finder) and Obsidian.

Additionally, when attempting to fix this issue:

• Basic Memory sometimes reports that all files have been modified when many still need fixing
• Files in subfolders are sometimes completely skipped

Environment

• OS: [Unknown - reported by Discord user]
• Python version: [Unknown]
• Basic Memory version: [Unknown]
• Installation method: [Unknown]
• Claude Desktop version (if applicable): [Unknown]

Additional Context

• User has found a workaround by asking Basic Memory to add the extension back, but this process is unreliable
• The issue affects file recognition in both Finder and Obsidian
• Problem extends to batch operations where some files are skipped or incorrectly reported as fixed

Possible Solution

The rename/move functionality should:

1. Preserve file extensions by default
2. Handle file extensions separately from the filename when processing renames
3. Ensure batch operations correctly process all files including those in subfolders

[groksrc]

@claude take a look at this and see if you can identify the issue causing it.

[claude]

Claude finished @groksrc's task —— View job

---

Analysis Complete: File Extension Bug Identified ✅

I've analyzed the file extension removal issue and identified the root cause. Here's my detailed findings:

Todo List

• Search for rename/move functionality in the codebase
• Examine MCP tools that handle file operations (move_note, edit_note)
• Analyze file extension handling logic
• Check batch operation code for skipping issues
• Identify root cause and report findings

Root Cause Analysis

The Primary Issue: Permalink Generation During Move Operations

The bug occurs in the move_entity method in EntityService (src/basic_memory/services/entity_service.py:688):

# 7. Update permalink if configured
if app_config.update_permalinks_on_move:
    # Generate new permalink from destination path
    new_permalink = await self.resolve_permalink(destination_path)  # ← BUG HERE

The Issue Chain:

1. When update_permalinks_on_move is True (default is False in config)
2. User moves a file like "folder/document.md" to "folder/new-document.md"
3. The system calls resolve_permalink("folder/new-document.md")
4. This calls generate_permalink() which correctly strips the extension at utils.py:52:

   base = os.path.splitext(path_str)[0]  # "folder/new-document.md" → "folder/new-document"

5. The extension-less permalink gets written to the file's frontmatter and database
6. Later operations may reference this extension-less permalink, causing file recognition issues

Key Files Involved:

• src/basic_memory/mcp/tools/move_note.py - MCP tool interface (correct)
• src/basic_memory/services/entity_service.py:688 - BUG LOCATION: Calls resolve_permalink with destination path
• src/basic_memory/utils.py:52 - Extension removal (working as designed for permalinks)
• src/basic_memory/config.py:65-68 - Configuration setting (default: False)

Configuration Dependency

The bug only manifests when:

• app_config.update_permalinks_on_move = True (user must have enabled this)
• Default value is False, so this affects users who explicitly enabled permalink updates

Secondary Issues Mentioned

The batch operation issues (files being skipped, incorrect reporting) likely stem from:

1. Files with inconsistent permalink vs filename relationships after moves
2. Search indexing problems when extensions are mismatched
3. Potential issues in subdirectory traversal logic

Why This is Problematic

• File System Recognition: .md files without extensions appear as plain text files
• Obsidian Integration: Obsidian expects .md extensions for markdown files
• Data Consistency: Mismatch between physical filename and stored permalink
• User Experience: Forces manual fixing of extensions

The Fix Approach

The generate_permalink() function is working correctly - permalinks should not have extensions. The issue is that move_entity shouldn't be generating new permalinks based on the destination path when the user is just renaming files. Instead:

1. Preserve permalinks during moves unless explicitly changed by user
2. Only update permalinks when the semantic meaning changes (not just filename)
3. Separate file path updates from permalink generation

Conclusion

This is a configuration-dependent bug that affects users who have enabled update_permalinks_on_move. The fix requires modifying the move_entity logic to preserve file extensions in the physical filename while keeping permalink generation separate.

---

[groksrc]

@claude double check your answer here. I have a suspicion that this happens when a filename without the file extension is passed.

[claude]

Claude finished @groksrc's task —— View job

---

You're absolutely right! I found the exact root cause.

Todo List

• Re-examine the move_note MCP tool input validation
• Trace execution path when filename without extension is passed
• Look for extension handling in file operations
• Test the hypothesis about extension-less input
• Update root cause analysis with corrected findings

Final Root Cause Analysis: Extension Handling Inconsistency

Your hypothesis is 100% correct. The bug occurs when a filename without the .md extension is passed to move_note. Here's the complete picture:

The Inconsistency Between Write and Move Operations

Write operations work correctly because:

• write_note uses the Entity schema (src/basic_memory/schemas/base.py:217-223)
• The file_path property automatically appends .md for markdown content:

  @property
  def file_path(self):
      safe_title = self.safe_title
      if self.content_type == "text/markdown":
          return f"{self.folder}/{safe_title}.md" if self.folder else f"{safe_title}.md"  # ← Auto-appends .md

Move operations fail because:

• move_note passes the destination_path directly to the filesystem without validation
• No extension auto-appending logic exists in the move operation
• When user provides "new-folder/new-document", the file literally gets moved to that path without .md

The Exact Problem Chain

1. User calls: move_note("My Note", "new-folder/new-document") ← No .md extension
2. move_note.py:436: Passes destination_path as-is to the API
3. entity_service.py:710: destination_file = project_config.home / destination_path - uses exact path
4. entity_service.py:725: source_file.rename(destination_file) - moves to extension-less path
5. Result: File becomes new-folder/new-document (no .md extension)

Why This Breaks Things

• File system: Extension-less files don't register as markdown files
• Obsidian: Can't recognize files without .md extensions
• Basic Memory: May have issues with file type detection

The Fix Location

The issue should be fixed in src/basic_memory/mcp/tools/move_note.py around line 427-437 by adding extension validation similar to how Entity.file_path works:

# Before calling the API, ensure .md extension for markdown files
if not destination_path.endswith('.md'):
    # Check if source is a markdown file by examining the entity
    entity = await resolve_entity(identifier)  # Would need to add this lookup
    if entity.content_type == "text/markdown":
        destination_path += '.md'

Supporting Evidence

• Line 221 in base.py: Write operations auto-append .md for markdown
• Line 710 in entity_service.py: Move operations use destination path exactly as provided
• Documentation inconsistency: Move examples show .md extensions but don't enforce them

This explains why the issue is intermittent - it only happens when users provide extension-less paths, which is a natural thing to do since they see write operations work without explicit extensions.

---

[groksrc]

@claude let's have move_note raise if there's no file extension provided. All of the examples in the file have a file extension so one has been assumed since the beginning. We can also update the docs if it will help the LLM understand how to use the tool correctly without throwing.

[claude]

Claude finished @groksrc's task —— View job • claude/issue-171-20250829-0348 • Create PR ➔

---

Todo List ✅

• Read current move_note.py implementation to understand the validation point
• Add validation logic to check if destination_path has a file extension
• Raise descriptive error when extension is missing
• Review and update docstring/examples if needed for clarity
• Test the validation logic (syntax validation)
• Commit and push changes
• Provide PR creation link

Implementation Complete

✅ Added file extension validation at line 427-444 in move_note.py:

• Checks if destination_path contains a dot and has a non-empty extension
• Provides clear error message with examples when extension is missing
• Suggests adding .md extension as the fix
• Logs warning for debugging purposes

✅ Updated docstring at line 362-363:

• Made file extension requirement explicit in the Args documentation
• Clarified that .md is typically expected for markdown files

The validation logic uses '.' not in destination_path or not destination_path.split('.')[-1] which will catch:

• Paths with no dots: "folder/filename"
• Paths ending with dot: "folder/filename."
• All valid extensions pass: "folder/filename.md"

Changes Committed

Commit: 3dcc494 - "fix: require file extension in move_note destination path"
Branch: claude/issue-171-20250829-0348

---