fix(mcp): report the accepted checksum from write_note and edit_note (#1619)

Signed-off-by: tonydzi <194927794+tonydzi@users.noreply.github.com>
Signed-off-by: phernandez <paul@basicmachines.co>
Co-authored-by: tonydzi <194927794+tonydzi@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 3 people

src/basic_memory/mcp/clients/knowledge.py

@@ -75,14 +75,18 @@ async def write_note(self, note: Entity, *, overwrite: bool) -> WriteNoteRespons
             )
         return write_note_response_adapter.validate_json(response.content)
 
-    async def create_entity(self, entity_data: dict[str, Any]) -> EntityResponse:
+    async def create_entity(self, entity_data: dict[str, Any]) -> EntityResponseV2:
         """Create a new entity.
 
         Args:
             entity_data: Entity data including title, content, folder, etc.
 
         Returns:
-            EntityResponse with created entity details
+            EntityResponseV2 with created entity details. The endpoint's
+            response_model is EntityResponseV2 (it carries file_checksum /
+            db_checksum, not the legacy EntityResponse.checksum key), so the
+            response must be parsed as that type or those fields silently
+            default to None (#1586).
 
         Raises:
             ToolError: If the request fails
@@ -102,21 +106,22 @@ async def create_entity(self, entity_data: dict[str, Any]) -> EntityResponse:
                 operation="create_entity",
                 path_template="/v2/projects/{project_id}/knowledge/entities",
             )
-        return EntityResponse.model_validate(response.json())
+        return EntityResponseV2.model_validate(response.json())
 
     async def update_entity(
         self,
         entity_id: str,
         entity_data: dict[str, Any],
-    ) -> EntityResponse:
+    ) -> EntityResponseV2:
         """Update an existing entity (full replacement).
 
         Args:
             entity_id: Entity external_id (UUID)
             entity_data: Complete entity data for replacement
 
         Returns:
-            EntityResponse with updated entity details
+            EntityResponseV2 with updated entity details. See create_entity
+            for why this must be EntityResponseV2, not EntityResponse (#1586).
 
         Raises:
             ToolError: If the request fails
@@ -136,7 +141,7 @@ async def update_entity(
                 operation="update_entity",
                 path_template="/v2/projects/{project_id}/knowledge/entities/{entity_id}",
             )
-        return EntityResponse.model_validate(response.json())
+        return EntityResponseV2.model_validate(response.json())
 
     async def get_entity(
         self,
@@ -215,15 +220,16 @@ async def patch_entity(
         self,
         entity_id: str,
         patch_data: dict[str, Any],
-    ) -> EntityResponse:
+    ) -> EntityResponseV2:
         """Partially update an entity.
 
         Args:
             entity_id: Entity external_id (UUID)
             patch_data: Partial entity data to update
 
         Returns:
-            EntityResponse with updated entity details
+            EntityResponseV2 with updated entity details. See create_entity
+            for why this must be EntityResponseV2, not EntityResponse (#1586).
 
         Raises:
             ToolError: If the request fails
@@ -243,7 +249,7 @@ async def patch_entity(
                 operation="patch_entity",
                 path_template="/v2/projects/{project_id}/knowledge/entities/{entity_id}",
             )
-        return EntityResponse.model_validate(response.json())
+        return EntityResponseV2.model_validate(response.json())
 
     async def delete_entity(self, entity_id: str) -> DeleteEntitiesResponse:
         """Delete an entity.

src/basic_memory/mcp/tools/edit_note.py

@@ -32,7 +32,7 @@
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import _extract_response_data, _response_detail_text
 from basic_memory.schemas.base import Entity
-from basic_memory.schemas.response import EntityResponse
+from basic_memory.schemas.v2.entity import EntityResponseV2
 from basic_memory.services.link_resolver import (
     detect_project_from_workspace_identifier_prefix,
     is_workspace_qualified_plain_identifier,
@@ -664,7 +664,7 @@ async def edit_note(
 
                 file_created = False
                 entity_id = ""
-                result: EntityResponse | None = None
+                result: EntityResponseV2 | None = None
 
                 # Try to resolve the entity; for append/prepend, create it if not found
                 try:
@@ -799,13 +799,18 @@ async def edit_note(
                 # --- Format response ---
                 # result is always set: either by create_entity (auto-create) or patch_entity (edit)
                 assert result is not None
+                # Report the accepted revision's checksum: it is recorded at accept
+                # time and is what checksum-guarded edits compare base_checksum
+                # against. file_checksum arrives later from deferred materialization
+                # and can drift from it (#1586).
+                checksum = result.db_checksum
                 if file_created:
                     summary = [
                         f"# Created note ({operation})",
                         f"project: {active_project.name}",
                         f"file_path: {result.file_path}",
                         f"permalink: {result.permalink}",
-                        f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
+                        f"checksum: {checksum[:8] if checksum else 'unknown'}",
                         "fileCreated: true",
                     ]
                     lines_added = len(content.split("\n"))
@@ -816,7 +821,7 @@ async def edit_note(
                         f"project: {active_project.name}",
                         f"file_path: {result.file_path}",
                         f"permalink: {result.permalink}",
-                        f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
+                        f"checksum: {checksum[:8] if checksum else 'unknown'}",
                     ]
 
                     # Add operation-specific details
@@ -872,7 +877,7 @@ async def edit_note(
                         "title": result.title,
                         "permalink": result.permalink,
                         "file_path": result.file_path,
-                        "checksum": result.checksum,
+                        "checksum": checksum,
                         "operation": operation,
                         "fileCreated": file_created,
                     }

src/basic_memory/mcp/tools/write_note.py

@@ -549,12 +549,20 @@ async def write_note(
                     for note in similar_notes
                 ]
 
+            # Report the accepted revision's checksum. It is recorded
+            # synchronously at accept time, and it is the value checksum-guarded
+            # edits compare base_checksum against. file_checksum is filled in
+            # later by deferred materialization and can drift if the file is
+            # edited outside Basic Memory, so it is not what a caller should
+            # echo back (#1586).
+            checksum = result.db_checksum
+
             summary = [
                 f"# {action} note",
                 f"project: {active_project.name}",
                 f"file_path: {result.file_path}",
                 f"permalink: {response_permalink}",
-                f"checksum: {result.file_checksum[:8] if result.file_checksum else 'unknown'}",
+                f"checksum: {checksum[:8] if checksum else 'unknown'}",
             ]
 
             # Count observations by category
@@ -602,7 +610,7 @@ async def write_note(
                     "title": result.title,
                     "permalink": response_permalink,
                     "file_path": result.file_path,
-                    "checksum": result.file_checksum,
+                    "checksum": checksum,
                     "action": action.lower(),
                     "similar_notes": [dataclasses.asdict(note) for note in similar_notes],
                 }

test-int/mcp/test_edit_note_integration.py

@@ -62,6 +62,45 @@ async def test_edit_note_append_operation(mcp_server, app, test_project):
         assert "This content was appended." in content
 
 
+@pytest.mark.asyncio
+async def test_edit_note_reports_real_checksum(mcp_server, app, test_project):
+    """edit_note must report the persisted checksum, not a permanent "unknown" (#1586).
+
+    A real SHA-256 checksum is computed and stored for every edit; the MCP
+    response must surface it instead of always falling back to "unknown".
+    """
+
+    async with Client(mcp_server) as client:
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Checksum Probe",
+                "directory": "probe",
+                "content": "# Checksum Probe\n\nOriginal content.",
+            },
+        )
+
+        edit_result = await client.call_tool(
+            "edit_note",
+            {
+                "project": test_project.name,
+                "identifier": "Checksum Probe",
+                "operation": "append",
+                "content": "\n\nAppended content.",
+            },
+        )
+
+        edit_text = edit_result.content[0].text
+        assert "checksum: unknown" not in edit_text
+        checksum_line = next(
+            line for line in edit_text.splitlines() if line.startswith("checksum: ")
+        )
+        reported_checksum = checksum_line.removeprefix("checksum: ")
+        assert len(reported_checksum) == 8
+        assert all(c in "0123456789abcdef" for c in reported_checksum)
+
+
 @pytest.mark.asyncio
 async def test_edit_note_prepend_operation(mcp_server, app, test_project):
     """Test prepending content to an existing note."""

tests/mcp/clients/test_clients.py

@@ -30,7 +30,11 @@ async def test_create_entity(self, monkeypatch):
         """Test create_entity calls correct endpoint."""
 
         mock_response = MagicMock()
+        # The entity routes return EntityResponseV2, which always carries these ids.
         mock_response.json.return_value = {
+            "id": 1,
+            "external_id": "entity-uuid-123",
+            "db_checksum": "d" * 64,
             "permalink": "test",
             "title": "Test",
             "file_path": "test.md",
@@ -53,13 +57,18 @@ async def mock_call_post(client, url, **kwargs):
         client = KnowledgeClient(mock_http, "proj-123")
         result = await client.create_entity({"title": "Test"})
         assert result.title == "Test"
+        assert result.db_checksum == "d" * 64
 
     @pytest.mark.asyncio
     async def test_update_entity(self, monkeypatch):
         """Test update_entity calls correct endpoint without fast query params."""
 
         mock_response = MagicMock()
+        # The entity routes return EntityResponseV2, which always carries these ids.
         mock_response.json.return_value = {
+            "id": 1,
+            "external_id": "entity-uuid-123",
+            "db_checksum": "d" * 64,
             "permalink": "test",
             "title": "Test",
             "file_path": "test.md",
@@ -82,13 +91,18 @@ async def mock_call_put(client, url, **kwargs):
         client = KnowledgeClient(mock_http, "proj-123")
         result = await client.update_entity("entity-123", {"title": "Test"})
         assert result.title == "Test"
+        assert result.db_checksum == "d" * 64
 
     @pytest.mark.asyncio
     async def test_patch_entity(self, monkeypatch):
         """Test patch_entity calls correct endpoint without fast query params."""
 
         mock_response = MagicMock()
+        # The entity routes return EntityResponseV2, which always carries these ids.
         mock_response.json.return_value = {
+            "id": 1,
+            "external_id": "entity-uuid-123",
+            "db_checksum": "d" * 64,
             "permalink": "test",
             "title": "Test",
             "file_path": "test.md",
@@ -111,6 +125,7 @@ async def mock_call_patch(client, url, **kwargs):
         client = KnowledgeClient(mock_http, "proj-123")
         result = await client.patch_entity("entity-123", {"operation": "append"})
         assert result.title == "Test"
+        assert result.db_checksum == "d" * 64
 
     @pytest.mark.asyncio
     async def test_resolve_entity(self, monkeypatch):

tests/mcp/test_tool_edit_note.py

@@ -1699,3 +1699,42 @@ async def test_edit_note_append_traversal_identifier_json_error(client, test_pro
     assert isinstance(result, dict)
     assert result["error"] == "SECURITY_VALIDATION_ERROR"
     assert result["fileCreated"] is False
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("file_checksum", [None, "c" * 64])
+async def test_edit_note_reports_the_accepted_db_checksum(
+    monkeypatch, app, test_project, file_checksum
+):
+    """edit_note reports db_checksum, the value edit preconditions compare (#1586).
+
+    The PATCH response is replaced to inject a not-yet-materialized file and a
+    drifted file checksum, which the inline test environment never produces.
+    """
+    await write_note(
+        project=test_project.name,
+        title="Deferred Edit Note",
+        directory="test",
+        content="# Deferred Edit Note\n\nOriginal body.",
+    )
+
+    db_checksum = "b" * 64  # a real, already-persisted SHA-256 hex digest
+    real_patch_entity = KnowledgeClient.patch_entity
+
+    async def fake_patch_entity(self, entity_id, patch_data):
+        result = await real_patch_entity(self, entity_id, patch_data)
+        return result.model_copy(
+            update={"file_checksum": file_checksum, "db_checksum": db_checksum}
+        )
+
+    monkeypatch.setattr(KnowledgeClient, "patch_entity", fake_patch_entity)
+
+    result = await edit_note(
+        project=test_project.name,
+        identifier="Deferred Edit Note",
+        operation="append",
+        content="\n\nAppended body.",
+    )
+
+    assert "checksum: unknown" not in result
+    assert f"checksum: {db_checksum[:8]}" in result

tests/mcp/test_tool_write_note.py

@@ -1,5 +1,6 @@
 """Tests for note tools that exercise the full stack with SQLite."""
 
+from datetime import datetime, timezone
 from textwrap import dedent
 from typing import Any
 
@@ -9,6 +10,7 @@
 from basic_memory import db
 from basic_memory import config as config_module
 from basic_memory.mcp import clients as clients_module
+from basic_memory.mcp.clients import KnowledgeClient
 from basic_memory.mcp.tools import write_note, read_note, delete_note
 from basic_memory.mcp.tools.write_note import (
     SIMILAR_NOTES_LIMIT,
@@ -19,6 +21,8 @@
 )
 from basic_memory.repository.relation_repository import RelationRepository
 from basic_memory.schemas.search import SearchItemType, SearchResponse, SearchResult
+from basic_memory.schemas.v2.entity import EntityResponseV2
+from basic_memory.schemas.v2.note_write import NoteCreated
 from basic_memory.workspace_context import workspace_permalink_context
 
 
@@ -229,6 +233,51 @@ async def test_write_note_no_tags(app, test_project):
     assert expected in content
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("file_checksum", [None, "c" * 64])
+async def test_write_note_reports_the_accepted_db_checksum(
+    monkeypatch, app, test_project, file_checksum
+):
+    """write_note reports db_checksum, the value edit preconditions compare (#1586).
+
+    file_checksum is None until deferred materialization runs, and can differ
+    from db_checksum after an outside edit; either way the response must carry
+    the accepted revision's checksum. The client call is replaced to inject
+    those two file states, which the inline test environment never produces.
+    """
+    now = datetime.now(timezone.utc)
+    db_checksum = "a" * 64  # a real, already-persisted SHA-256 hex digest
+
+    async def fake_write_note(self, note, *, overwrite):
+        entity = EntityResponseV2(
+            external_id="11111111-1111-1111-1111-111111111111",
+            id=1,
+            title=note.title,
+            note_type=note.note_type,
+            permalink=f"{test_project.name}/{note.directory}/{note.title.lower()}",
+            file_path=f"{note.directory}/{note.title}.md",
+            created_at=now,
+            updated_at=now,
+            db_version=1,
+            db_checksum=db_checksum,
+            file_version=None,
+            file_checksum=file_checksum,
+        )
+        return NoteCreated(entity=entity)
+
+    monkeypatch.setattr(KnowledgeClient, "write_note", fake_write_note)
+
+    result = await write_note(
+        project=test_project.name,
+        title="Deferred Materialization Note",
+        directory="test",
+        content="# Deferred Materialization Note\n\nBody.",
+    )
+
+    assert "checksum: unknown" not in result
+    assert f"checksum: {db_checksum[:8]}" in result
+
+
 @pytest.mark.asyncio
 async def test_write_note_update_existing(app, test_project):
     """Test creating a new note.