fix: Rename write_note entity_type to note_type for clarity (#419)

Signed-off-by: phernandez <paul@basicmachines.co>
Signed-off-by: Paul Hernandez <60959+phernandez@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Paul Hernandez <phernandez@users.noreply.github.com>

Author: 3 people

docs/ai-assistant-guide-extended.md

@@ -557,7 +557,7 @@ Adopt GraphQL instead of REST for our API layer.
 """,
     folder="decisions",
     tags=["decision", "api", "graphql"],
-    entity_type="decision",
+    note_type="decision",
     project="main"
 )
 ```
@@ -594,7 +594,7 @@ await write_note(
 """,
     folder="meetings",
     tags=["meeting", "api", "team"],
-    entity_type="meeting",
+    note_type="meeting",
     project="main"
 )
 ```
@@ -646,7 +646,7 @@ Specification for user authentication system using JWT tokens.
 """,
     folder="specs",
     tags=["spec", "auth", "security"],
-    entity_type="spec",
+    note_type="spec",
     project="main"
 )
 ```
@@ -1612,7 +1612,7 @@ await write_note(
 {related_entities}
 """,
     folder="decisions",
-    entity_type="decision",
+    note_type="decision",
     project="main"
 )
 ```
@@ -2687,14 +2687,14 @@ await write_note(
 
 ### Content Management
 
-**write_note(title, content, folder, tags, entity_type, project)**
+**write_note(title, content, folder, tags, note_type, project)**
 - Create or update markdown notes
 - Parameters:
   - `title` (required): Note title
   - `content` (required): Markdown content
   - `folder` (required): Destination folder
   - `tags` (optional): List of tags
-  - `entity_type` (optional): Entity type (note, person, meeting, etc.)
+  - `note_type` (optional): Type of note (stored in frontmatter). Can be "note", "person", "meeting", "guide", etc.
   - `project` (required unless default_project_mode): Target project
 - Returns: Created/updated entity with permalink
 - Example:
@@ -2704,7 +2704,7 @@ await write_note(
     content="# API Design\n...",
     folder="specs",
     tags=["api", "design"],
-    entity_type="spec",
+    note_type="spec",
     project="main"
 )
 ```

src/basic_memory/api/routers/project_router.py

@@ -113,7 +113,7 @@ async def sync_project(
     force_full: bool = Query(
         False, description="Force full scan, bypassing watermark optimization"
     ),
-    run_in_background: bool = Query(True, description="Run in background")
+    run_in_background: bool = Query(True, description="Run in background"),
 ):
     """Force project filesystem sync to database.
 
@@ -142,7 +142,9 @@ async def sync_project(
             "message": f"Filesystem sync initiated for project '{project_config.name}'",
         }
     else:
-        report = await sync_service.sync(project_config.home, project_config.name, force_full=force_full)
+        report = await sync_service.sync(
+            project_config.home, project_config.name, force_full=force_full
+        )
         logger.info(
             f"Filesystem sync completed for project: {project_config.name} (force_full={force_full})"
         )

src/basic_memory/file_utils.py

@@ -213,7 +213,7 @@ def dump_frontmatter(post: frontmatter.Post) -> str:
         sort_keys=False,
         allow_unicode=True,
         default_flow_style=False,
-        Dumper=yaml.SafeDumper
+        Dumper=yaml.SafeDumper,
     )
 
     # Construct the final markdown with frontmatter

src/basic_memory/mcp/tools/write_note.py

@@ -16,9 +16,6 @@
 # Define TagType as a Union that can accept either a string or a list of strings or None
 TagType = Union[List[str], str, None]
 
-# Define TagType as a Union that can accept either a string or a list of strings or None
-TagType = Union[List[str], str, None]
-
 
 @mcp.tool(
     description="Create or update a markdown note. Returns a markdown formatted summary of the semantic content.",
@@ -29,7 +26,7 @@ async def write_note(
     folder: str,
     project: Optional[str] = None,
     tags: list[str] | str | None = None,
-    entity_type: str = "note",
+    note_type: str = "note",
     context: Context | None = None,
 ) -> str:
     """Write a markdown note to the knowledge base.
@@ -70,7 +67,8 @@ async def write_note(
                 available projects.
         tags: Tags to categorize the note. Can be a list of strings, a comma-separated string, or None.
               Note: If passing from external MCP clients, use a string format (e.g. "tag1,tag2,tag3")
-        entity_type: Type of entity to create. Defaults to "note". Can be "guide", "report", "config", etc.
+        note_type: Type of note to create (stored in frontmatter). Defaults to "note".
+                   Can be "guide", "report", "config", "person", etc.
         context: Optional FastMCP context for performance caching.
 
     Returns:
@@ -96,14 +94,14 @@ async def write_note(
             content="# Weekly Standup\\n\\n- [decision] Use SQLite for storage #tech"
         )
 
-        # Create a note with tags and entity type
+        # Create a note with tags and note type
         write_note(
             project="work-project",
             title="API Design",
             folder="specs",
             content="# REST API Specification\\n\\n- implements [[Authentication]]",
             tags=["api", "design"],
-            entity_type="guide"
+            note_type="guide"
         )
 
         # Update existing note (same title/folder)
@@ -147,7 +145,7 @@ async def write_note(
         entity = Entity(
             title=title,
             folder=folder,
-            entity_type=entity_type,
+            entity_type=note_type,
             content_type="text/markdown",
             content=content,
             entity_metadata=metadata,

tests/api/test_project_router.py

@@ -588,9 +588,7 @@ async def test_sync_project_endpoint_foreground_with_changes(
         assert "deleted" in data
 
         # At least one of these should have changes
-        has_changes = (
-            len(data["new"]) > 0 or len(data["modified"]) > 0 or len(data["deleted"]) > 0
-        )
+        has_changes = len(data["new"]) > 0 or len(data["modified"]) > 0 or len(data["deleted"]) > 0
         assert has_changes or data["total"] >= 0  # Either changes detected or empty sync is valid
 
     finally:

tests/mcp/test_tool_read_note.py

@@ -402,7 +402,7 @@ async def test_read_note_preserves_functionality_with_security(self, app, test_p
                 Additional content with various formatting.
             """).strip(),
             tags=["security", "test", "full-feature"],
-            entity_type="guide",
+            note_type="guide",
         )
 
         # Test reading by permalink

tests/mcp/test_tool_write_note.py

@@ -538,7 +538,7 @@ async def test_write_note_with_custom_entity_type(app, test_project):
         folder="guides",
         content="# Guide Content\nThis is a guide",
         tags=["guide", "documentation"],
-        entity_type="guide",
+        note_type="guide",
     )
 
     assert result
@@ -574,14 +574,14 @@ async def test_write_note_with_custom_entity_type(app, test_project):
 
 @pytest.mark.asyncio
 async def test_write_note_with_report_entity_type(app, test_project):
-    """Test creating a note with entity_type="report"."""
+    """Test creating a note with note_type="report"."""
     result = await write_note.fn(
         project=test_project.name,
         title="Monthly Report",
         folder="reports",
         content="# Monthly Report\nThis is a monthly report",
         tags=["report", "monthly"],
-        entity_type="report",
+        note_type="report",
     )
 
     assert result
@@ -599,13 +599,13 @@ async def test_write_note_with_report_entity_type(app, test_project):
 
 @pytest.mark.asyncio
 async def test_write_note_with_config_entity_type(app, test_project):
-    """Test creating a note with entity_type="config"."""
+    """Test creating a note with note_type="config"."""
     result = await write_note.fn(
         project=test_project.name,
         title="System Config",
         folder="config",
         content="# System Configuration\nThis is a config file",
-        entity_type="config",
+        note_type="config",
     )
 
     assert result
@@ -659,21 +659,21 @@ async def test_write_note_update_existing_with_different_entity_type(app, test_p
         folder="test",
         content="# Initial Content\nThis starts as a note",
         tags=["test"],
-        entity_type="note",
+        note_type="note",
     )
 
     assert result1
     assert "# Created note" in result1
     assert f"project: {test_project.name}" in result1
 
-    # Update the same note with a different entity_type
+    # Update the same note with a different note_type
     result2 = await write_note.fn(
         project=test_project.name,
         title="Changeable Type",
         folder="test",
         content="# Updated Content\nThis is now a guide",
         tags=["guide"],
-        entity_type="guide",
+        note_type="guide",
     )
 
     assert result2
@@ -976,7 +976,7 @@ async def test_write_note_security_with_all_parameters(self, app, test_project):
             folder="../../../etc/malicious",
             content="# Malicious Content\nThis should be blocked by security validation.",
             tags=["malicious", "test"],
-            entity_type="guide",
+            note_type="guide",
         )
 
         assert isinstance(result, str)
@@ -1026,7 +1026,7 @@ async def test_write_note_preserves_functionality_with_security(self, app, test_
                 Additional content with various formatting.
             """).strip(),
             tags=["security", "test", "full-feature"],
-            entity_type="guide",
+            note_type="guide",
         )
 
         # Should succeed normally

tests/services/test_entity_service.py

@@ -1315,7 +1315,9 @@ async def test_edit_entity_replace_section_strips_duplicate_header(
 
     # Count occurrences of "## Testing" - should only be 1
     testing_header_count = file_content.count("## Testing")
-    assert testing_header_count == 1, f"Expected 1 '## Testing' header, found {testing_header_count}"
+    assert testing_header_count == 1, (
+        f"Expected 1 '## Testing' header, found {testing_header_count}"
+    )
 
     assert "New content for testing section" in file_content
     assert "Original content" not in file_content