[BUG] Fails to update note ("already exists")

[ryanstraight]

Bug Description (From Claude)

The write_note function is failing to update existing notes in the Basic Memory system, producing errors both when attempting to write without a specified folder and when attempting to update files that already exist.

Steps To Reproduce

1. Check current date/time using the get_time function (unrelated, part of custom instructions to get the time so Claude can accurately understand relative times like, "Look at yesterday's note," etc.)
2. Retrieve an existing note using read_note with its permalink (e.g., "periodic-notes-daily-2025-04-18")
3. Attempt to update the note using write_note with the same title
4. Observe error indicating the file already exists

Expected Behavior

The write_note function should be able to update existing notes, either by overwriting them entirely or by merging changes with the existing content. This would allow for programmatic updates to daily notes and other frequently modified documents.

Actual Behavior

Two distinct errors were observed:

1. When attempting to write without specifying folder:

Error executing tool write_note: 1 validation error for write_noteArguments
folder
  Field required [type=missing, input_value={'title': '2025-04-18', '...llows [[2025-04-17]]\n'}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.11/v/missing

2. When attempting to write with folder specified:

Error executing tool write_note: file for entity Periodic Notes/Daily/2025-04-17 already exists: Periodic Notes\Daily\2025-04-17.md

Environment

• OS: Windows 11 Insider
• Python version: 3.13.2
• Basic Memory version: 0.12.2
• Installation method: uv 0.6.10
• Claude Desktop version: 0.9.2

Additional Context

• This issue affects core functionality for assistants designed to update daily notes or maintain knowledge repositories
• The error seems to indicate that the write_note function is designed to create new files only, not update existing ones
• The folder parameter appears to be required even when the permalink is specified, which creates redundancy
• There may be a need for an update_note function or a parameter for write_note that allows overwriting existing files

Possible Solution

Three potential solutions:

1. Modify the write_note function to accept an overwrite boolean parameter that, when set to true, allows updating existing files
2. Create a dedicated update_note function specifically for modifying existing notes
3. Implement a "merge" capability that would allow selective updating of note sections while preserving other content

As a temporary workaround, users could:

• Read the existing note with read_note
• Create a new note with a slightly modified title or in a different folder
• Manually copy the content back to the original location

This issue significantly impacts the usability of Basic Memory for maintaining living documents like daily notes, where regular updates are essential.

[phernandez]

Hi @ryanstraight thanks for reporting this issue. The intended behavior of the write_note tool is:

• look up the note by folder/title in the db
• if it does not exist, it is assumed to be new
• if it exists, it's assumed to be an update

For new writes, the code will error if there is in fact a file already. I added this so it doesn't clobber things unintentionally.

I suspect what may be happening is that because you are using windows, the file path is not matching in the db? so it's not finding the file when it should.

Either that, or the file you are trying to write to exists but is not indexed.

In any case, if you could share the logs with me, I can investigate and fix the issue. They are located in your HOME/.basic-memory/basic-memory-mcp.log

you can send them to me at hello @ basicmachines.co.

I appreciate the feedback!

[phernandez]

claude: look at the issue reported by the user and troubleshoot what the cause may be. Could this be a windows isssue?

[github-actions]

Claude Code Analysis

After analyzing the codebase, I've identified the root cause of the issue and can suggest potential fixes:

Issue Analysis:

The bug occurs when attempting to update an existing note using the write_note MCP tool. The error reported by the user suggests two distinct problems:

1. The write_note function requires the folder parameter even when trying to update an existing note
2. When the folder is provided, it still fails with "file for entity {title} already exists"

Root Cause:

The problem is in the create_entity method in the EntityService class. In lines 108-111:

if await self.file_service.exists(file_path):
    raise EntityCreationError(
        f"file for entity {schema.folder}/{schema.title} already exists: {file_path}"
    )

This check prevents any file from being created if it already exists. However, when the write_note MCP tool is used, it calls create_or_update_entity, which tries to be smart about whether to create or update. The problem is in how it determines this - it uses the link_resolver to find the entity, but there seems to be an issue with the resolution logic.

Windows-Specific Issues:

This could be Windows-specific due to path handling differences. Windows uses backslashes for paths, which can cause issues if the code is not consistently handling them. Notice in the error message, the path uses backslashes (Periodic Notes\Daily\2025-04-17.md), which is Windows format.

Suggested Fixes:

Option 1: Modify the write_note function to accept a permalink parameter

@mcp.tool(
    description="Create or update a markdown note. Returns a markdown formatted summary of the semantic content.",
)
async def write_note(
    title: str,
    content: str,
    folder: str = None,  # Make folder optional
    permalink: str = None,  # Add permalink parameter
    tags=None,
) -> str:
    """Write a markdown note to the knowledge base."""
    # ...existing code...
    
    # Modified logic to handle updates via permalink
    if permalink:
        # Try to resolve the permalink first
        entity = Entity(
            title=title,
            folder=folder or "",  # Use empty folder if not provided
            entity_type="note",
            content_type="text/markdown",
            content=content,
            permalink=permalink,  # Set the permalink
            entity_metadata=metadata,
        )
    else:
        # Create new entity with required folder
        if not folder:
            raise ValueError("folder is required when permalink is not provided")
        entity = Entity(
            title=title,
            folder=folder,
            entity_type="note",
            content_type="text/markdown",
            content=content,
            entity_metadata=metadata,
        )
    
    # Create or update via knowledge API
    # ...rest of the function...

Option 2: Fix the create_entity method to work better with the create_or_update_entity flow

async def create_entity(self, schema: EntitySchema) -> EntityModel:
    """Create a new entity and write to filesystem."""
    logger.debug(f"Creating entity: {schema.title}")

    # Get file path and ensure it's a Path object
    file_path = Path(schema.file_path)
    
    # REMOVE THIS BLOCK - let the create_or_update_entity handle the logic
    # if await self.file_service.exists(file_path):
    #     raise EntityCreationError(
    #         f"file for entity {schema.folder}/{schema.title} already exists: {file_path}"
    #     )

    # Get unique permalink
    permalink = await self.resolve_permalink(schema.permalink or file_path)
    schema._permalink = permalink

    post = await schema_to_markdown(schema)

    # write file
    final_content = frontmatter.dumps(post, sort_keys=False)
    checksum = await self.file_service.write_file(file_path, final_content)

    # parse entity from file
    entity_markdown = await self.entity_parser.parse_file(file_path)

    # create entity
    created = await self.create_entity_from_markdown(file_path, entity_markdown)

    # add relations
    entity = await self.update_entity_relations(created.file_path, entity_markdown)

    # Set final checksum to mark complete
    return await self.repository.update(entity.id, {"checksum": checksum})

Option 3: Add an overwrite parameter to the write_note tool

@mcp.tool(
    description="Create or update a markdown note. Returns a markdown formatted summary of the semantic content.",
)
async def write_note(
    title: str,
    content: str,
    folder: str,
    tags=None,
    overwrite: bool = False,  # Add overwrite parameter
) -> str:
    """Write a markdown note to the knowledge base."""
    # ...existing code...
    
    # Pass overwrite parameter to entity creation
    entity = Entity(
        title=title,
        folder=folder,
        entity_type="note",
        content_type="text/markdown",
        content=content,
        entity_metadata=metadata,
        _overwrite=overwrite,  # Add this flag
    )
    
    # Then modify the entity_service.py to handle this flag
    # in the create_entity method:
    
    # if await self.file_service.exists(file_path) and not getattr(schema, "_overwrite", False):
    #     raise EntityCreationError(...)

Conclusion:

The issue is most likely caused by a path resolution problem in the link resolver, possibly exacerbated by Windows-specific path handling. The write_note tool currently requires a folder parameter and doesn't handle file updates correctly - it should be able to determine whether to create or update based on the note's identity.

The most complete fix would be to:

1. Make the folder parameter optional in write_note when a permalink is provided
2. Fix the entity resolution logic to better handle Windows paths
3. Add an overwrite flag to explicitly allow updates to existing files

These changes would need to be made in:

• /src/basic_memory/mcp/tools/write_note.py
• /src/basic_memory/services/entity_service.py
• Possibly /src/basic_memory/services/link_resolver.py to improve path handling for Windows

This should resolve the reported issue without breaking existing functionality.

---

🤖 Generated with Claude Code GitHub Action

[ryanstraight]

@phernandez sent! Thanks!

[bm-claudeai]

Issue Resolution

This issue has been resolved and the write_note tool now works correctly for updating existing notes.

Root Cause

The problem was in the EntityParser.parse_file method which couldn't handle absolute file paths correctly. This caused issues when the write_note tool tried to update existing files.

Fix Applied

Commit: 9bff1f7 - "fix: [BUG] write_note Tool Fails to Update Existing Files in Some Situations. (#80)"

The fix updated EntityParser.parse_file to properly handle both relative and absolute paths:

# Check if the path is already absolute
if isinstance(path, Path) and path.is_absolute() or (isinstance(path, str) and Path(path).is_absolute()):
    absolute_path = Path(path)
else:
    absolute_path = self.base_path / path

Current Functionality

The write_note tool now correctly:

• ✅ Creates new notes when they don't exist
• ✅ Updates existing notes when they do exist
• ✅ Preserves custom frontmatter fields during updates
• ✅ Handles various tag input formats
• ✅ Returns appropriate status ("Created" vs "Updated")

Test Coverage

Comprehensive tests demonstrate the functionality works correctly:

• test_write_note_update_existing() - Basic update functionality
• test_write_note_preserves_custom_metadata() - Custom frontmatter preservation
• Multiple edge cases and integration scenarios

The issue reported in this ticket should no longer occur with current versions of Basic Memory. If you continue to experience problems with write_note, please open a new issue with specific reproduction steps.

Closing as resolved. 🎉