fix: add tool use doc to write note for using empty string or "/" for root folder

[phernandez]

No description provided.

[github-actions]

Claude finished @phernandez's task —— View job

---

PR #339 Code Review

I've reviewed this PR against the Basic Memory team checklist. This is a small documentation improvement to clarify how to use the folder parameter in the write_note tool.

Change Summary

The PR updates the docstring for the folder parameter in write_note() to explicitly document that an empty string ("") can be used to write to the project root.

Modified: src/basic_memory/mcp/tools/write_note.py:65-67

# Before:
folder: Folder path relative to project root where the file should be saved.
        Use forward slashes (/) as separators. Examples: "notes", "projects/2025", "research/ml"

# After:
folder: Folder path relative to project root where the file should be saved.
        Use forward slashes (/) as separators. Use empty string ("") to write to project root.
        Examples: "notes", "projects/2025", "research/ml", "" (root)

Code Quality & Standards ✅

• Follows Basic Memory's coding conventions in CLAUDE.md
• Python 3.12+ type annotations and async patterns - N/A (documentation only)
• SQLAlchemy 2.0 best practices - N/A (documentation only)
• FastAPI and Typer conventions followed - N/A (documentation only)
• 100-character line length limit maintained
• No commented-out code blocks

Testing & Documentation ✅

• Unit tests for new functions/methods - Existing tests cover this functionality (test_write_note_empty_folder_security, test_write_note_none_folder_security)
• Integration tests for new MCP tools - N/A (existing tool)
• Test coverage for edge cases - Already tested in tests/mcp/test_tool_write_note.py:908-924
• Documentation updated (README, docstrings) - This PR updates the docstring
• CLAUDE.md updated if conventions change - N/A (no convention changes)

Basic Memory Architecture ✅

• MCP tools follow atomic, composable design - N/A (documentation only)
• Database changes include Alembic migrations - N/A (no schema changes)
• Preserves local-first architecture principles - N/A (documentation only)
• Knowledge graph operations maintain consistency - N/A (documentation only)
• Markdown file handling preserves integrity - N/A (documentation only)
• AI-human collaboration patterns followed - Yes, improves LLM understanding of the tool

Security & Performance ✅

• No hardcoded secrets or credentials - N/A
• Input validation for MCP tools - Existing validation at line 130 handles empty folder correctly
• Proper error handling and logging - Existing implementation is secure
• Performance considerations addressed - N/A (documentation only)
• No sensitive data in logs or commits - N/A

Review Summary

Recommendation: ✅ Approve

This is a helpful documentation improvement that makes the write_note tool more discoverable for LLM users. The functionality is already implemented and tested - this PR simply documents the existing behavior more clearly.

Strengths:

1. Clear and concise documentation enhancement
2. Adds practical example showing empty string usage
3. Functionality is already tested and secure (validated in security test suite)
4. Maintains consistency with existing documentation style

Observations:

• The empty string folder functionality is well-tested with comprehensive security validation (lines 908-943 in test file)
• Security validation at line 130 properly handles empty folders without triggering path traversal warnings
• This change aligns with the MCP tools' goal of being atomic and composable with clear interfaces

No issues found. This PR is ready to merge.

---

Branch: tool-usage-write-note-empty-folder

[github-actions]

Claude finished @phernandez's task —— View job

---

PR #339 Code Review

I've reviewed this PR against the Basic Memory team checklist. This PR adds documentation and support for using "/" as an alias for the project root folder in write_note().

Summary of Changes

Modified: src/basic_memory/mcp/tools/write_note.py

• Lines 65-67: Updated docstring to document that both "/" and "" can be used for project root
• Lines 128-130: Added normalization logic to convert "/" to "" before validation

Modified: test-int/mcp/test_write_note_integration.py

• Line 400: Added test case for "/" folder path

---

Code Quality & Standards ✅

• Follows Basic Memory's coding conventions in CLAUDE.md
• Python 3.12+ type annotations and async patterns - N/A (documentation + simple logic)
• SQLAlchemy 2.0 best practices - N/A
• FastAPI and Typer conventions followed - N/A
• 100-character line length limit maintained
• No commented-out code blocks

Testing & Documentation ✅

• Unit tests for new functions/methods - Existing security tests cover empty folder (test_write_note_empty_folder_security)
• Integration tests for new MCP tools - Test case added at line 400
• Test coverage for edge cases - Comprehensive coverage exists
• Documentation updated (README, docstrings) - Docstring updated in this PR
• CLAUDE.md updated if conventions change - N/A (no convention changes)

Basic Memory Architecture ✅

• MCP tools follow atomic, composable design - N/A (existing tool enhancement)
• Database changes include Alembic migrations - N/A (no schema changes)
• Preserves local-first architecture principles - N/A
• Knowledge graph operations maintain consistency - N/A
• Markdown file handling preserves integrity - N/A
• AI-human collaboration patterns followed - Yes, improves LLM discoverability

Security & Performance ✅

• No hardcoded secrets or credentials - N/A
• Input validation for MCP tools - Proper validation: "/" normalized before security check
• Proper error handling and logging - Existing error handling applies
• Performance considerations addressed - N/A (trivial operation)
• No sensitive data in logs or commits - N/A

---

Review Findings

✅ Recommendation: Approve

This is a well-implemented enhancement that makes the write_note tool more intuitive for LLM users. The change is minimal, properly tested, and securely implemented.

Strengths:

1. Clear documentation: Explicitly documents both "/" and "" as valid root folder indicators
2. Secure implementation: Normalization happens before path validation (line 128-130), maintaining security
3. Good test coverage: Integration test added, existing security tests cover the underlying functionality
4. Minimal code change: Simple, focused enhancement with low risk
5. User experience: Makes the API more intuitive - "/" is a natural choice for root

Technical Details:

• The normalization at write_note.py:128-130 converts "/" to "" before the validate_project_path() check at line 134
• This ensures the security validation logic remains unchanged and robust
• The empty string is already well-tested in the security test suite (tests/mcp/test_tool_write_note.py)
• Integration test at line 400 validates the "/" alias works correctly

No issues found. This PR is ready to merge.

---

Branch: tool-usage-write-note-empty-folder