[BUG] Permalink does not change when file changes for local changes

[Narsail]

Bug Description

A clear and concise description of what the bug is.

Steps To Reproduce

• Run basic-memory sync --watch --verbose
• Create a file in obsidian
• Rename file / or move

What happens

• Permalink stays the same

What do you expect to happen

• Permalink should be synced to the new name / folder path

[ryanstraight]

I've run into this, as well. Manual workaround for me is to just delete the permalink YAML line and, if you've got basic-memory sync --watch set, it'll recreate the correct one. (Can take a time or two.)

Edit to add: unfortunately, if you watch the sync log, removing the permalink and re-adding it shows up as deletion and modification, rather than a move or rename. Just noticed that.

[phernandez]

I think there is probably some confusion about the expected behavior. The permalink is designed not to change when the file is moved. It's a "stable identifier".

I took the idea from Obsidian: https://help.obsidian.md/publish/permalinks

Here's the docs about them. They might need to be clearer:
https://memory.basicmachines.co/docs/knowledge-format#Permalinks+and+memory+%2F%2F+URLs

In fact, I'm kind of second guessing if they are really useful at all. I've considered removing the feature and just making everything be based on file path.

[Narsail]

Ah interesting. One of the things I noticed is that it immediately takes the note title for me (in most cases ‘untitled-xx’ and then stays that way.Sent from my iPhoneOn 4 Apr 2025, at 03:29, Paul Hernandez ***@***.***> wrote: I think there is probably some confusion about the expected behavior. The permalink is designed not to change when the file is moved. It's a "stable identifier". I took the idea from Obsidian: https://help.obsidian.md/publish/permalinks Here's the docs about them. They might need to be clearer: https://memory.basicmachines.co/docs/knowledge-format#Permalinks+and+memory+%2F%2F+URLs In fact, I'm kind of second guessing if they are really useful at all. I've considered removing the feature and just making everything be based on file path.—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: ***@***.***> phernandez left a comment (basicmachines-co/basic-memory#73) I think there is probably some confusion about the expected behavior. The permalink is designed not to change when the file is moved. It's a "stable identifier". I took the idea from Obsidian: https://help.obsidian.md/publish/permalinks Here's the docs about them. They might need to be clearer: https://memory.basicmachines.co/docs/knowledge-format#Permalinks+and+memory+%2F%2F+URLs In fact, I'm kind of second guessing if they are really useful at all. I've considered removing the feature and just making everything be based on file path. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: ***@***.***>

[ryanstraight]

I personally like the idea of unique identifiers, but only if they're meaningful to the human if they're human-facing. A hundred files with a permalink metadata of "untitled..." is confusing.

[phernandez]

claude: It seems like the behavior of the permalinks is not clear. What are your thoughts? I've considered removing the permalink feature? I think the problem comes from the watch service syncing with a default file name. It's not wrong, it's just not helpful behavior

[github-actions]

Claude Code Analysis

Based on the analysis of issue #73, I can provide a thorough assessment and potential solutions for the permalink not changing when files are renamed or moved locally.

Problem Analysis

The issue occurs because:

1. When files are renamed or moved, Basic Memory intentionally preserves the original permalink in the handle_move method in sync_service.py (lines 466-493):

async def handle_move(self, old_path, new_path):
    # ...
    # Update file_path but keep the same permalink for link stability
    updated = await self.entity_repository.update(entity.id, {"file_path": new_path})
    # ...

2. This is an intentional design choice as stated in the comment "keep the same permalink for link stability"
3. The permalink is never regenerated based on the new file path
4. The frontmatter in the file is not updated to reflect any new permalink

Expected vs. Current Behavior

• Current behavior: When files are renamed/moved, the permalink stays the same in both database and file frontmatter
• Expected behavior: According to the user issue, permalinks should be updated to match the new file name/path

Root Cause

The root cause is that the system is designed to preserve permalinks when files move, but this behavior is confusing for users who expect permalinks to track with file name changes.

In entity_service.py, we can see the permalink resolution logic (line 45-83):

async def resolve_permalink(self, file_path: Permalink | Path, markdown: Optional[EntityMarkdown] = None) -> str:
    # ... 
    # For existing files, try to find current permalink
    existing = await self.repository.get_by_file_path(str(file_path))
    if existing:
        return existing.permalink
    # ...

This function prioritizes existing permalinks for files that already exist in the database, which prevents permalinks from updating when files move.

Proposed Solutions

Solution 1: Configuration Option for Permalink Behavior

Add a configuration setting that controls permalink update behavior:

1. In config.py, add a new setting:

update_permalinks_on_move: bool = False  # Default keeps current behavior

2. Modify handle_move method in sync_service.py to check this setting:

async def handle_move(self, old_path, new_path):
    logger.info("Moving entity", old_path=old_path, new_path=new_path)

    entity = await self.entity_repository.get_by_file_path(old_path)
    if entity:
        update_data = {"file_path": new_path}
        
        # If configured to update permalinks, generate new one
        if self.config.update_permalinks_on_move:
            # Generate new permalink based on new path
            new_permalink = generate_permalink(new_path)
            update_data["permalink"] = new_permalink
            
            # Update frontmatter in file
            await self.file_service.update_frontmatter(new_path, {"permalink": new_permalink})
            logger.info(
                "Updated permalink on move",
                old_permalink=entity.permalink,
                new_permalink=new_permalink,
                old_path=old_path,
                new_path=new_path,
            )
        else:
            # Current behavior - keep same permalink
            logger.debug(
                "Keeping permalink on move for link stability",
                permalink=entity.permalink,
                old_path=old_path,
                new_path=new_path,
            )
        
        # Update entity in database
        updated = await self.entity_repository.update(entity.id, update_data)
        
        # Rest of function remains the same...

Solution 2: Permalink Versioning/History

A more sophisticated solution would maintain a history of permalinks:

1. Modify the Entity model to track both current and previous permalinks:

class Entity(BaseModel):
    # ... existing fields ...
    permalink: str  # Current permalink
    previous_permalinks: List[str] = []  # History of prior permalinks

2. Update both entity_service.py and link_resolver.py to handle resolution from both current and previous permalinks.

Solution 3: Separate Concepts of "ID" and "Permalink"

Currently, permalinks serve dual purposes - as stable identifiers and as human-readable references. Separating these:

1. Keep internal stable UUIDs as primary identifiers
2. Make permalinks reflect the current file path/name
3. Update permalinks on moves but maintain internal linking via UUID

This would involve more structural changes to multiple components.

Files That Need Modification

1. src/basic_memory/sync/sync_service.py:

   • Update handle_move method to support permalink updates

2. src/basic_memory/services/entity_service.py:

   • Modify resolve_permalink to potentially regenerate permalinks on move

3. src/basic_memory/config.py:

   • Add configuration option for permalink behavior

4. Test files:

   • tests/sync/test_sync_service.py: Update tests to cover new behavior
   • tests/sync/test_watch_service.py: Add tests for permalink changes on moves

Recommended Approach

The simplest solution is to implement a configuration toggle (Solution 1) that gives users the choice:

1. Add a user-controlled setting for whether permalinks should update on file moves
2. Default to the current behavior (stable permalinks) for backward compatibility
3. Update documentation to clarify the behavior of permalinks

This approach preserves backward compatibility while addressing the user's expectations.

---

🤖 Generated with Claude Code GitHub Action

[phernandez]

@Narsail @ryanstraight FYI this issue has been fixed in the v0.12.0 release.

Added new config properties for:

• updating permalinks when a file is moved (default False)
• syncing in real time when the mcp process starts (default True)

Note:

• The real time sync means that it is no longer necessary to run the basic-memory sync --watch process in a a terminal to sync changes to the db (so the AI can see them). This will be done automatically.

The config file for Basic Memory is in the home directory under .basic-memory/config.json.

To change the properties, set the following values:

 ~/.basic-memory/config.json 
{
  "sync_changes": true,
  "update_permalinks_on_move": true
}

Thanks for using Basic Memory!