merge: resolve conflict with main (insert_before/after_section tests)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

README.md

@@ -23,6 +23,18 @@ Basic Memory lets you build persistent knowledge through natural conversations w
 Claude, while keeping everything in simple Markdown files on your computer. It uses the Model Context Protocol (MCP) to
 enable any compatible LLM to read and write to your local knowledge base.
 
+## What's New in v0.19.0
+
+- **Semantic Vector Search** — find notes by meaning, not just keywords. Combines full-text and vector similarity for hybrid search with FastEmbed embeddings.
+- **Schema System** — infer, validate, and diff the structure of your knowledge base with `schema_infer`, `schema_validate`, and `schema_diff` tools.
+- **Per-Project Cloud Routing** — route individual projects through the cloud while others stay local, using API key authentication (`basic-memory project set-cloud`).
+- **FastMCP 3.0** — upgraded to FastMCP 3.0 with tool annotations for better client integration.
+- **CLI Overhaul** — JSON output mode (`--json`) for scripting, workspace-aware commands, and an htop-inspired project dashboard.
+- **Smarter Editing** — `edit_note` append/prepend auto-creates notes if they don't exist; `write_note` has an overwrite guard to prevent accidental data loss.
+- **Richer Search Results** — matched chunk text returned in search results for better context.
+
+See the full [CHANGELOG](CHANGELOG.md) for details.
+
 - Website: [basicmemory.com](https://basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme)
 - Documentation: [docs.basicmemory.com](https://docs.basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme)
 - Community: [Discord](https://discord.gg/tyvKNccgqN?utm_source=github&utm_medium=referral&utm_campaign=readme)

src/basic_memory/mcp/tools/edit_note.py

@@ -158,7 +158,7 @@ def _format_error_response(
 
 
 @mcp.tool(
-    description="Edit an existing markdown note using various operations like append, prepend, find_replace, or replace_section.",
+    description="Edit an existing markdown note using various operations like append, prepend, find_replace, replace_section, insert_before_section, or insert_after_section.",
     annotations={"destructiveHint": False, "openWorldHint": False},
 )
 async def edit_note(
@@ -190,6 +190,8 @@ async def edit_note(
                   - "prepend": Add content to the beginning of the note (creates the note if it doesn't exist)
                   - "find_replace": Replace occurrences of find_text with content (note must exist)
                   - "replace_section": Replace content under a specific markdown header (note must exist)
+                  - "insert_before_section": Insert content before a section heading without consuming it (note must exist)
+                  - "insert_after_section": Insert content after a section heading without consuming it (note must exist)
         content: The content to add or use for replacement
         project: Project name to edit in. Optional - server will resolve using hierarchy.
                 If unknown, use list_memory_projects() to discover available projects.
@@ -257,7 +259,14 @@ async def edit_note(
         logger.info("MCP tool call", tool="edit_note", identifier=identifier, operation=operation)
 
         # Validate operation
-        valid_operations = ["append", "prepend", "find_replace", "replace_section"]
+        valid_operations = [
+            "append",
+            "prepend",
+            "find_replace",
+            "replace_section",
+            "insert_before_section",
+            "insert_after_section",
+        ]
         if operation not in valid_operations:
             raise ValueError(
                 f"Invalid operation '{operation}'. Must be one of: {', '.join(valid_operations)}"
@@ -266,8 +275,9 @@ async def edit_note(
         # Validate required parameters for specific operations
         if operation == "find_replace" and not find_text:
             raise ValueError("find_text parameter is required for find_replace operation")
-        if operation == "replace_section" and not section:
-            raise ValueError("section parameter is required for replace_section operation")
+        section_ops = ("replace_section", "insert_before_section", "insert_after_section")
+        if operation in section_ops and not section:
+            raise ValueError("section parameter is required for section-based operations")
 
         # Use the PATCH endpoint to edit the entity
         try:
@@ -389,6 +399,10 @@ async def edit_note(
                     summary.append("operation: Find and replace operation completed")
                 elif operation == "replace_section":
                     summary.append(f"operation: Replaced content under section '{section}'")
+                elif operation == "insert_before_section":
+                    summary.append(f"operation: Inserted content before section '{section}'")
+                elif operation == "insert_after_section":
+                    summary.append(f"operation: Inserted content after section '{section}'")
 
             # Count observations by category (reuse logic from write_note)
             categories = {}

src/basic_memory/schemas/request.py

@@ -65,7 +65,14 @@ class EditEntityRequest(BaseModel):
     Supports various operation types for different editing scenarios.
     """
 
-    operation: Literal["append", "prepend", "find_replace", "replace_section"]
+    operation: Literal[
+        "append",
+        "prepend",
+        "find_replace",
+        "replace_section",
+        "insert_before_section",
+        "insert_after_section",
+    ]
     content: str
     section: Optional[str] = None
     find_text: Optional[str] = None
@@ -75,8 +82,16 @@ class EditEntityRequest(BaseModel):
     @classmethod
     def validate_section_for_replace_section(cls, v, info):
         """Ensure section is provided for replace_section operation."""
-        if info.data.get("operation") == "replace_section" and not v:
-            raise ValueError("section parameter is required for replace_section operation")
+        if (
+            info.data.get("operation")
+            in (
+                "replace_section",
+                "insert_before_section",
+                "insert_after_section",
+            )
+            and not v
+        ):
+            raise ValueError("section parameter is required for section-based operations")
         return v
 
     @field_validator("find_text")

src/basic_memory/services/entity_service.py

@@ -888,6 +888,14 @@ def apply_edit_operation(
                 raise ValueError("section cannot be empty or whitespace only")
             return self.replace_section_content(current_content, section, content)
 
+        elif operation in ("insert_before_section", "insert_after_section"):
+            if not section:
+                raise ValueError("section is required for insert section operations")
+            if not section.strip():
+                raise ValueError("section cannot be empty or whitespace only")
+            position = "before" if operation == "insert_before_section" else "after"
+            return self.insert_relative_to_section(current_content, section, content, position)
+
         else:
             raise ValueError(f"Unsupported operation: {operation}")
 
@@ -979,6 +987,73 @@ def replace_section_content(
 
         return "\n".join(result_lines)
 
+    def insert_relative_to_section(
+        self,
+        current_content: str,
+        section_header: str,
+        new_content: str,
+        position: str,
+    ) -> str:
+        """Insert content before or after a section heading without consuming it.
+
+        Unlike replace_section_content, this preserves the section heading and its
+        existing content. The new content is inserted immediately before or after
+        the heading line.
+
+        Args:
+            current_content: The current markdown content
+            section_header: The section header to anchor on (e.g., "## Section Name")
+            new_content: The content to insert
+            position: "before" to insert above the heading, "after" to insert below it
+
+        Returns:
+            The updated content with new_content inserted relative to the heading
+
+        Raises:
+            ValueError: If the section header is not found or appears more than once
+        """
+        # Normalize the section header (ensure it starts with #)
+        if not section_header.startswith("#"):
+            section_header = "## " + section_header
+
+        lines = current_content.split("\n")
+        matching_indices = [
+            i for i, line in enumerate(lines) if line.strip() == section_header.strip()
+        ]
+
+        if len(matching_indices) == 0:
+            raise ValueError(
+                f"Section '{section_header}' not found in document. "
+                f"Use replace_section to create a new section."
+            )
+        if len(matching_indices) > 1:
+            raise ValueError(
+                f"Multiple sections found with header '{section_header}'. "
+                f"Section insertion requires unique headers."
+            )
+
+        idx = matching_indices[0]
+
+        if position == "before":
+            # Insert new content before the section heading
+            before = lines[:idx]
+            after = lines[idx:]
+            # Ensure blank line separation
+            insert_lines = new_content.rstrip("\n").split("\n")
+            if before and before[-1].strip() != "":
+                insert_lines = [""] + insert_lines
+            return "\n".join(before + insert_lines + [""] + after)
+        else:
+            # Insert new content after the section heading line
+            before = lines[: idx + 1]
+            after = lines[idx + 1 :]
+            insert_lines = new_content.rstrip("\n").split("\n")
+            # Ensure blank line separation so inserted text doesn't merge
+            # with existing section content into a single paragraph
+            if after and after[0].strip() != "":
+                insert_lines = insert_lines + [""]
+            return "\n".join(before + insert_lines + after)
+
     def _prepend_after_frontmatter(self, current_content: str, content: str) -> str:
         """Prepend content after frontmatter, preserving frontmatter structure."""
 

test-int/cli/test_cli_tool_edit_note_integration.py

@@ -208,7 +208,7 @@ def test_edit_note_replace_section_fails_without_section(
     )
 
     assert result.exit_code != 0
-    assert "section parameter is required for replace_section operation" in result.output
+    assert "section parameter is required for section-based operations" in result.output
 
 
 def test_edit_note_append_creates_nonexistent_note_cli(

tests/mcp/test_tool_edit_note.py

@@ -322,7 +322,7 @@ async def test_edit_note_replace_section_missing_section(client, test_project):
             content="new content",
         )
 
-    assert "section parameter is required for replace_section operation" in str(exc_info.value)
+    assert "section parameter is required for section-based operations" in str(exc_info.value)
 
 
 @pytest.mark.asyncio
@@ -677,3 +677,96 @@ async def test_edit_note_append_autocreate_not_fuzzy_match(client, test_project)
     content = await read_note("Existing Note Alpha", project=test_project.name)
     assert "Original content" in content
     assert "Brand new content" not in content
+
+
+@pytest.mark.asyncio
+async def test_edit_note_insert_before_section_operation(client, test_project):
+    """Test inserting content before a section heading."""
+    # Create initial note with sections
+    await write_note(
+        project=test_project.name,
+        title="Insert Before Doc",
+        directory="docs",
+        content="# Doc\n\n## Overview\nOverview content.\n\n## Details\nDetail content.",
+    )
+
+    result = await edit_note(
+        project=test_project.name,
+        identifier="docs/insert-before-doc",
+        operation="insert_before_section",
+        content="--- inserted divider ---",
+        section="## Details",
+    )
+
+    assert isinstance(result, str)
+    assert "Edited note (insert_before_section)" in result
+    assert f"project: {test_project.name}" in result
+    assert "Inserted content before section '## Details'" in result
+    assert f"[Session: Using project '{test_project.name}']" in result
+
+
+@pytest.mark.asyncio
+async def test_edit_note_insert_after_section_operation(client, test_project):
+    """Test inserting content after a section heading."""
+    # Create initial note with sections
+    await write_note(
+        project=test_project.name,
+        title="Insert After Doc",
+        directory="docs",
+        content="# Doc\n\n## Overview\nOverview content.\n\n## Details\nDetail content.",
+    )
+
+    result = await edit_note(
+        project=test_project.name,
+        identifier="docs/insert-after-doc",
+        operation="insert_after_section",
+        content="Inserted after overview heading",
+        section="## Overview",
+    )
+
+    assert isinstance(result, str)
+    assert "Edited note (insert_after_section)" in result
+    assert f"project: {test_project.name}" in result
+    assert "Inserted content after section '## Overview'" in result
+    assert f"[Session: Using project '{test_project.name}']" in result
+
+
+@pytest.mark.asyncio
+async def test_edit_note_insert_before_section_missing_section(client, test_project):
+    """Test insert_before_section without section parameter raises ValueError."""
+    await write_note(
+        project=test_project.name,
+        title="Test Note",
+        directory="test",
+        content="# Test\nContent here.",
+    )
+
+    with pytest.raises(ValueError, match="section parameter is required"):
+        await edit_note(
+            project=test_project.name,
+            identifier="test/test-note",
+            operation="insert_before_section",
+            content="new content",
+        )
+
+
+@pytest.mark.asyncio
+async def test_edit_note_insert_before_section_not_found(client, test_project):
+    """Test insert_before_section when section doesn't exist returns error."""
+    await write_note(
+        project=test_project.name,
+        title="Test Note",
+        directory="test",
+        content="# Test\n\n## Existing\nContent here.",
+    )
+
+    result = await edit_note(
+        project=test_project.name,
+        identifier="test/test-note",
+        operation="insert_before_section",
+        content="new content",
+        section="## Nonexistent",
+    )
+
+    assert isinstance(result, str)
+    assert "# Edit Failed" in result

tests/schemas/test_schemas.py

@@ -345,7 +345,7 @@ def test_edit_entity_request_find_replace_empty_find_text():
 def test_edit_entity_request_replace_section_empty_section():
     """Test that replace_section operation requires non-empty section parameter."""
     with pytest.raises(
-        ValueError, match="section parameter is required for replace_section operation"
+        ValueError, match="section parameter is required for section-based operations"
     ):
         EditEntityRequest.model_validate(
             {
@@ -356,6 +356,46 @@ def test_edit_entity_request_replace_section_empty_section():
         )
 
 
+def test_edit_entity_request_insert_before_section():
+    """Test insert_before_section is a valid operation."""
+    edit_request = EditEntityRequest.model_validate(
+        {
+            "operation": "insert_before_section",
+            "content": "content to insert",
+            "section": "## Target Section",
+        }
+    )
+    assert edit_request.operation == "insert_before_section"
+    assert edit_request.section == "## Target Section"
+
+
+def test_edit_entity_request_insert_after_section():
+    """Test insert_after_section is a valid operation."""
+    edit_request = EditEntityRequest.model_validate(
+        {
+            "operation": "insert_after_section",
+            "content": "content to insert",
+            "section": "## Target Section",
+        }
+    )
+    assert edit_request.operation == "insert_after_section"
+    assert edit_request.section == "## Target Section"
+
+
+def test_edit_entity_request_insert_before_section_empty_section():
+    """Test that insert_before_section requires non-empty section parameter."""
+    with pytest.raises(
+        ValueError, match="section parameter is required for section-based operations"
+    ):
+        EditEntityRequest.model_validate(
+            {
+                "operation": "insert_before_section",
+                "content": "content",
+                "section": "",
+            }
+        )
+
+
 # New tests for timeframe parsing functions
 class TestTimeframeParsing:
     """Test cases for parse_timeframe() and validate_timeframe() functions."""