test: Add integration test for issue #416 (read_note with underscored folders)

[phernandez]

Summary

Adds an integration test to reproduce the bug reported in issue #416 where read_note fails to find notes when given permalinks from underscored folder names.

Changes

• Added test_read_note_underscored_folder_by_permalink to test-int/mcp/test_read_note_integration.py

Test Scenario

The test reproduces the exact scenario from the bug report:

1. Creates a note in _archive/articles/ folder
2. Verifies the permalink is normalized (underscores stripped)
3. Attempts to read the note using its permalink
4. Expects this to succeed

If the bug exists, this test will fail. If it passes, it confirms that the database-based lookup is working correctly.

Related Issue

Fixes #416

---

Generated with Claude Code

[github-actions]

Claude finished @phernandez's task in 1m 45s —— View job

---

PR Review: Integration Test for Issue #416

I've completed my review of this PR against the Basic Memory team checklist. Overall, this is a well-crafted test that effectively reproduces the reported issue. Below are my findings:

---

✅ Strengths

1. Excellent Test Design: The test precisely reproduces the bug scenario described in issue [BUG] read_note doesn't normalize underscored folder names in permalinks #416, following the exact workflow a user would experience
2. Clear Documentation: Comprehensive docstring explains the bug being tested and references the issue
3. Proper Structure: Follows existing integration test patterns in the codebase
4. Good Assertions: Validates both the setup (file path with underscores) and expected behavior (permalink normalization)
5. Inline Comments: Helpful comments explain the test logic, particularly around permalink normalization

---

📋 Team Checklist Review

Code Quality & Standards ✅

• Follows Basic Memory's coding conventions: Yes, matches patterns in CLAUDE.md
• Python 3.12+ type annotations and async patterns: Correct async/await usage with @pytest.mark.asyncio
• 100-character line length limit maintained: All lines are well under 100 characters
• No commented-out code blocks: Clean code with no commented blocks

Testing & Documentation ✅

• Integration test for new scenario: This adds an integration test for the underscored folder bug
• Test coverage for edge cases: Covers the specific edge case of underscored folders (_archive/, _drafts/, etc.)
• Documentation updated: The docstring clearly documents what's being tested and why

Basic Memory Architecture ✅

• MCP tools follow atomic, composable design: Test uses write_note and read_note as atomic operations
• Knowledge graph operations maintain consistency: Tests permalink generation and lookup consistency
• Markdown file handling preserves integrity: Validates that underscored folders are handled correctly

Security & Performance ✅

• No hardcoded secrets or credentials: Uses test fixtures appropriately
• Proper error handling and logging: Test will properly fail if the bug exists
• Performance considerations addressed: Single test, no performance concerns

Compatibility ✅

• File path comparisons must be windows compatible: Uses forward slashes in paths (cross-platform)
• Avoid using emojis and unicode characters: No emojis or special unicode in test code

---

🔍 Code Analysis

Test Flow (test-int/mcp/test_read_note_integration.py:52-103)

The test follows this logical sequence:

1. Line 62-71: Creates a note in _archive/articles/ using write_note
2. Line 78: Verifies the file path includes the underscore: _archive/articles/Example Note.md
3. Line 81: Verifies the permalink is normalized (underscores stripped): archive/articles/example-note
4. Line 86-92: Attempts to read using the normalized permalink
5. Line 95-102: Asserts the note should be found and content returned

This perfectly mirrors the bug report scenario where:

• User creates a note in _archive/
• System generates permalink with underscores stripped
• User attempts to use that permalink
• read_note fails to find the note

Comparison with Similar Test

The new test follows the same pattern as test_build_context_underscore.py, which tests a similar underscore normalization issue for build_context (fixed in PR #329). This consistency is excellent.

---

💡 Observations & Recommendations

What This Test Reveals

Based on the issue history, this test is designed to verify whether the bug actually exists. As @groksrc noted in the issue comments, the database already stores both permalink (normalized) and file_path (with underscores), so theoretically this should work.

Two possible outcomes:

1. Test passes ✅: The bug doesn't exist or was already fixed - the database lookup is working correctly
2. Test fails ❌: The bug is confirmed and needs fixing

Minor Suggestions (Optional)

While the test is excellent as-is, here are some optional enhancements for consideration:

1. Edge Case Variations: Could add tests for:

   • Multiple underscored folders: _archive/_private/note.md
   • Midword underscores: my_folder/note.md
   • Mixed cases: _Archive/Articles/note.md

2. Error Message Validation: If the test is expected to fail, could assert on the specific error message from issue [BUG] read_note doesn't normalize underscored folder names in permalinks #416

However, these are not necessary for this PR - the current test is sufficient to reproduce and diagnose the reported issue.

---

✅ Final Verdict

This PR is ready to merge. The test is:

• Well-written and follows project conventions
• Properly documented with clear intent
• Consistent with existing test patterns
• Addresses all checklist requirements

The test will provide valuable diagnostic information when run in CI, confirming whether issue #416 is a real bug or a misconception about how the system works.

---

Tasks Completed

• Read the changed test file
• Review test structure and quality
• Check against Basic Memory team checklist
• Provide comprehensive feedback

---