feat: add context-aware wiki link resolution with source_path support

[groksrc]

Summary

• Add source_path parameter to resolve_link() for context-aware wiki link resolution
• Implement relative path resolution: [[nested/deep-note]] from testing/link-test.md → testing/nested/deep-note.md
• Add proximity-based resolution for duplicate titles (prefers notes in same folder)
• Support strict mode to disable fuzzy search fallback for wiki links
• Update get_by_title() to return results ordered by shortest path first

Changes

• link_resolver.py: Added source_path parameter and _find_closest_entity() method
• knowledge_router.py: Pass source_path and strict=True to resolve endpoint
• entity.py: Added source_path field to EntityResolveRequest schema
• entity_repository.py: Order get_by_title() results by path length

Test plan

• Unit tests for relative path resolution (5 tests)
• Unit tests for context-aware resolution (10 tests)
• Unit tests for strict mode / no fuzzy matching (2 API tests)
• All 84 tests pass

🤖 Generated with Claude Code

[github-actions]

Claude finished @groksrc's task in 1m 31s —— View job

---

PR Review: Context-Aware Wiki Link Resolution

Reviewed this PR against the Basic Memory team checklist. Overall this is a solid enhancement with excellent test coverage. Found a few areas for improvement related to Windows compatibility and code documentation.

---

Code Quality & Standards ✅

• Follows Basic Memory's coding conventions - Code adheres to style guidelines
• Python 3.12+ type annotations - Full type annotations present
• SQLAlchemy 2.0 best practices - Repository methods follow established patterns
• FastAPI conventions followed - Router updates are correct
• 100-character line length - Maintained throughout
• No commented-out code - Clean implementation

Issues found:
None significant

---

Testing & Documentation ⚠️

• Unit tests for new functions - Comprehensive coverage in test_link_resolver.py (17 new tests)
• Test coverage for edge cases - Context-aware, relative path, strict mode all tested
• 100% test coverage maintained - All new code paths covered
• Documentation updated - Docstrings added for new methods

Issues found:

1. Missing literate programming comments in link_resolver.py:src/basic_memory/services/link_resolver.py:179-239 - The _find_closest_entity() method has good algorithmic documentation, but the complex proximity logic could benefit from decision point comments explaining why descendants get priority 100+ vs ancestors getting levels_up. Per CLAUDE.md literate programming style:

# Trigger: entity is in descendant folder of source
# Why: descendants are less contextually relevant than ancestors
# Outcome: gets lower priority (100+) to prefer same-folder/ancestor matches
return (100 + levels_down, len(entity_path))

---

Basic Memory Architecture ✅

• MCP tools follow atomic design - Not applicable (service layer change)
• Database changes include migrations - No schema changes required
• Preserves local-first architecture - File-based resolution maintained
• Knowledge graph consistency - Link resolution logic is sound
• AI-human collaboration patterns - Well-designed feature

---

Security & Performance ✅

• No hardcoded secrets - None present
• Input validation - Pydantic schemas validate source_path
• Proper error handling - Returns None on failure
• Performance considerations - Uses existing repository methods efficiently

---

Windows Compatibility ⚠️

• File path comparisons must be Windows compatible

Critical Issue - Windows path separator incompatibility:

The code uses hardcoded / for path operations throughout link_resolver.py:src/basic_memory/services/link_resolver.py:51-238, which will break on Windows:

# Line 56: Will fail on Windows paths like "testing\link-test.md"
source_folder = source_path.rsplit("/", 1)[0] if "/" in source_path else ""

# Line 59: Creates Unix-only paths
relative_path = f"{source_folder}/{clean_text}"

# Line 198: String-based folder extraction
source_folder = source_path.rsplit("/", 1)[0] if "/" in source_path else ""

# Lines 209, 214, 224: Path comparison logic assumes forward slashes
if entity_folder == source_folder:
if source_folder.startswith(entity_folder + "/"):
if entity_folder.startswith(source_folder + "/"):

Recommended fix:
Use pathlib.Path for cross-platform compatibility or os.path operations. Since paths are stored as POSIX strings in the database (per entity_repository.py:line 98 Path(file_path).as_posix()), you should:

1. Document that all paths in the system are stored as POSIX strings (forward slashes)
2. Add a comment explaining this design decision at the top of the path manipulation sections
3. OR normalize paths at function entry using Path().as_posix() to ensure consistency

Example:

# All paths in Basic Memory are stored as POSIX strings (forward slashes)
# for cross-platform compatibility. See entity_repository.py:98
source_path = Path(source_path).as_posix() if source_path else None

---

Summary

Strengths:

• Excellent test coverage (17 new tests covering all scenarios)
• Well-designed context-aware resolution algorithm
• Clean integration with existing API
• Proper use of strict mode to disable fuzzy matching for wiki links

Required Changes:

1. Windows path compatibility - Address hardcoded / separators or document POSIX-only design
2. Enhanced literate comments - Add decision point comments to _find_closest_entity() method

Optional Improvements:

• Consider extracting path manipulation to a utility function for reusability
• Document the proximity scoring algorithm (0, levels_up, 100+levels_down, 1000) in the docstring

Overall this is high-quality work that significantly improves wiki link resolution. The Windows path compatibility issue should be addressed before merging.

---

[github-actions]

Claude finished @groksrc's task in 1m 58s —— View job

---

PR Review: Context-Aware Wiki Link Resolution

Reviewing this PR against the Basic Memory team checklist.

Todo List:

• Read changed files to understand implementation
• Review against Code Quality & Standards checklist
• Review against Testing & Documentation checklist
• Review against Basic Memory Architecture checklist
• Review against Security & Performance checklist
• Review against Compatibility checklist
• Check if previous review comments were addressed
• Post final review summary

---

Code Quality & Standards ✅

• Follows Basic Memory's coding conventions - Code adheres to CLAUDE.md guidelines
• Python 3.12+ type annotations - Full type annotations present (Optional[str], list[Entity], etc.)
• SQLAlchemy 2.0 best practices - Repository methods follow established patterns with proper ordering
• FastAPI conventions followed - Router correctly passes source_path and strict=True to resolve endpoint
• 100-character line length - Maintained throughout (longest line is 100 chars)
• No commented-out code - Clean implementation

Findings: All standards met. Code quality is excellent.

---

Testing & Documentation ✅

• Unit tests for new functions - Comprehensive coverage in test_link_resolver.py (17 new tests added)
• Integration tests for new MCP tools - API tests in test_knowledge_router.py validate strict mode behavior
• Test coverage for edge cases - Tests cover:
  • Relative path resolution ([[nested/deep-note]] from testing/link-test.md)
  • Context-aware resolution for duplicate titles (same folder, ancestors, descendants, unrelated)
  • Strict mode preventing fuzzy search fallback
  • With and without source_path parameter
• 100% test coverage maintained - All new code paths have corresponding tests
• Documentation updated - Excellent literate programming style:
  • Section headers for Path Resolution and Relative Path Resolution
  • Decision point comments explaining trigger/why/outcome for each branch
  • Comprehensive docstring for _find_closest_entity() with proximity scoring algorithm
  • POSIX path compatibility note at line 52-54
• CLAUDE.md updated - Not applicable (no convention changes)

Findings: Testing and documentation are exemplary. The recent commit addressed all previous review feedback.

---

Basic Memory Architecture ✅

• MCP tools follow atomic, composable design - Not applicable (service layer change)
• Database changes include Alembic migrations - No schema changes required
• Preserves local-first architecture - File-based resolution maintained
• Knowledge graph operations maintain consistency - Link resolution logic properly handles:
  • Relative paths from source context
  • Proximity-based duplicate resolution
  • Strict mode for wiki links (no fuzzy matching)
• Markdown file handling preserves integrity - Uses existing repository methods
• AI-human collaboration patterns followed - Well-designed feature with clear intent

Findings: Architecture principles fully respected.

---

Security & Performance ✅

• No hardcoded secrets - None present
• Input validation - Pydantic schema EntityResolveRequest validates source_path (max 500 chars)
• Proper error handling - Returns None on resolution failure (fail-safe behavior)
• Performance considerations - Efficient approach:
  • Early returns for exact matches
  • Reuses existing repository methods (get_by_title() now ordered by path length)
  • Context-aware resolution only when source_path provided
  • Strict mode prevents expensive fuzzy search for wiki links

Findings: No security issues. Performance optimizations are sound.

---

Compatibility ✅

• File path comparisons must be Windows compatible - ADDRESSED!
  • Lines 52-54 document that all paths are stored as POSIX strings (forward slashes)
  • References entity_repository.py which normalizes paths using Path().as_posix()
  • This design decision ensures cross-platform compatibility
• Avoid emojis and unicode in console/log output - No issues found

Findings: Windows compatibility concerns from previous review have been fully addressed with documentation.

---

Previous Review Comments ✅

The most recent commit (dcc7dcb) specifically addresses both issues from the previous review:

1. Windows path compatibility - ✅ Resolved with POSIX path documentation (lines 52-54)
2. Literate programming comments - ✅ Added decision point comments to _find_closest_entity():
   • Lines 214-218: Same-folder match (priority 0)
   • Lines 220-223: Ancestor folder match (priority = levels_up)
   • Lines 233-236: Descendant folder match (priority = 100 + levels_down)
   • Lines 245-247: Unrelated path match (priority = 1000)

---

Summary

Verdict: APPROVED ✅

This is high-quality work that significantly improves wiki link resolution with excellent test coverage and documentation. All previous review feedback has been addressed.

Strengths:

• ✅ Comprehensive test coverage (17 unit tests, 2 API integration tests)
• ✅ Excellent literate programming style with decision point comments
• ✅ Cross-platform compatibility documented with POSIX path note
• ✅ Context-aware resolution algorithm is well-designed and explained
• ✅ Strict mode properly prevents fuzzy matching for wiki links
• ✅ Repository method get_by_title() now orders by shortest path first

Changes Made:

1. Added source_path parameter to resolve_link() for context-aware resolution
2. Implemented relative path resolution: [[nested/deep-note]] from testing/link-test.md → testing/nested/deep-note.md
3. Added proximity-based resolution for duplicate titles (prefers same folder > ancestors > descendants > unrelated)
4. Strict mode disables fuzzy search fallback for wiki links
5. Updated get_by_title() to return results ordered by shortest path first

No additional changes needed. This PR is ready to merge.

[github-actions]

Claude finished @groksrc's task in 2m 9s —— View job

---

PR Review: Context-Aware Wiki Link Resolution

Reviewing this PR against the Basic Memory team checklist. This PR adds context-aware wiki link resolution with source_path support, enabling relative path resolution and proximity-based matching for duplicate titles.

Todo List:

• Read all changed files to understand implementation
• Review against Code Quality & Standards checklist
• Review against Testing & Documentation checklist
• Review against Basic Memory Architecture checklist
• Review against Security & Performance checklist
• Review against Compatibility checklist
• Post final review summary

---

Code Quality & Standards ✅

• Follows Basic Memory's coding conventions - Code adheres to CLAUDE.md guidelines with excellent literate programming style
• Python 3.12+ type annotations - Full type annotations present (Optional[str], list[Entity], Tuple[int, int], etc.)
• SQLAlchemy 2.0 best practices - Repository methods use proper async patterns and ordering
• FastAPI conventions followed - Router correctly passes source_path and strict=True to resolve endpoint
• 100-character line length - Maintained throughout (verified no lines exceed 100 chars)
• No commented-out code - Clean implementation with no commented code blocks

Findings: All standards met. Code quality is excellent with proper separation of concerns.

---

Testing & Documentation ✅

• Unit tests for new functions - Comprehensive test coverage:

  • test_link_resolver.py: Added 17 new tests covering:
    • 5 tests for relative path resolution (lines 772-832)
    • 10 tests for context-aware resolution (lines 507-677)
    • 2 tests for strict mode (already existed but validate new behavior)
  • test_knowledge_router.py: Added 2 API integration tests for strict mode (lines 54-106)
  • test_entity_repository.py: Added tests for get_by_title() ordering (verified path length ordering)

• Integration tests for API endpoints - API tests validate:

  • Resolve endpoint with strict mode disabled fuzzy matching (line 54-77)
  • Context-aware resolution with source_path and strict mode (line 80-106)

• Test coverage for edge cases - Tests cover:

  • Same folder preference (line 508-517)
  • Ancestor/descendant folder matching (line 547-586)
  • Relative path resolution with fallback (line 773-816)
  • Root-level source files (line 520-529, 807-816)
  • Duplicate titles with proximity scoring (line 629-668)
  • Unique titles ignoring context (line 600-609)
  • Permalink conflicts with context-aware resolution (line 612-626)
  • Non-existent links returning None (line 671-678)

• 100% test coverage maintained - All new code paths have corresponding tests:

  • _find_closest_entity() helper method fully tested
  • Relative path resolution logic tested
  • Context-aware resolution tested with multiple scenarios
  • Strict mode tested in both unit and integration tests

• Documentation updated - Excellent literate programming style:

  • Section headers for Path Resolution and Relative Path Resolution (lines 51-54, 56-60)
  • Decision point comments with trigger/why/outcome pattern:
    • Relative path resolution (lines 57-59)
    • Same folder match (lines 214-217)
    • Ancestor folder match (lines 220-223)
    • Descendant folder match (lines 233-236)
    • Unrelated path match (lines 245-247)
  • Comprehensive docstrings:
    • resolve_link() method documents all parameters (lines 37-45)
    • _find_closest_entity() documents proximity algorithm (lines 184-201)
    • EntityResolveRequest schema documents context-aware resolution (lines 11-37)
  • POSIX path compatibility note (lines 52-54)

• CLAUDE.md updated - Not applicable (no convention changes)

Findings: Testing and documentation are exemplary. The PR demonstrates excellent attention to edge cases and follows literate programming principles.

---

Basic Memory Architecture ✅

• MCP tools follow atomic, composable design - Not applicable (service layer change, not MCP tool)

• Database changes include Alembic migrations - No schema changes required (only added optional parameters)

• Preserves local-first architecture - Yes:

  • File-based resolution maintained
  • No new database dependencies
  • Uses existing repository methods

• Knowledge graph operations maintain consistency - Yes:

  • Link resolution logic properly handles relative paths from source context
  • Proximity-based duplicate resolution maintains semantic meaning
  • Strict mode prevents incorrect fuzzy matches for wiki links

• Markdown file handling preserves integrity - Yes:

  • Uses existing repository methods (get_by_title(), get_by_file_path())
  • No changes to file writing or parsing

• AI-human collaboration patterns followed - Yes:

  • Well-designed feature with clear intent
  • Previous review feedback addressed in subsequent commits
  • Clean implementation with good separation of concerns

Findings: Architecture principles fully respected. The feature integrates cleanly with existing patterns.

---

Security & Performance ✅

• No hardcoded secrets - None present

• Input validation - Proper validation:

  • EntityResolveRequest Pydantic schema validates source_path (max 500 chars) and identifier (max 500 chars)
  • strict parameter is boolean with default False
  • Path operations use POSIX normalization

• Proper error handling - Fail-safe behavior:

  • Returns None on resolution failure (no exceptions raised)
  • 404 HTTP status for unresolved identifiers in API endpoint
  • No silent failures or swallowed exceptions

• Performance considerations - Efficient approach:

  • Early returns for exact matches (lines 107-110)
  • Reuses existing repository methods (get_by_title() now orders by path length at database level - line 84)
  • Context-aware resolution only when needed (source_path provided - line 82)
  • Strict mode prevents expensive fuzzy search for wiki links (lines 135-136)
  • Database-level ordering using func.length(Entity.file_path) (repository line 84)

Findings: No security issues. Performance optimizations are sound and leverage database-level operations.

---

Compatibility ✅

• File path comparisons must be Windows compatible - ✅ Properly addressed

  • Lines 52-54 document that all paths are stored as POSIX strings (forward slashes)
  • References entity_repository.py which normalizes paths using Path().as_posix()
  • Design decision ensures cross-platform compatibility by standardizing on POSIX paths in database
  • All path operations use forward slash with documented rationale (line 54)

• Avoid emojis and unicode in console/log output - No issues:

  • Log messages use standard ASCII
  • No emojis in code or docstrings
  • Unicode only in test data (appropriate for testing)

Findings: Windows compatibility properly addressed with POSIX path documentation. No emoji/unicode issues.

---

Additional Observations

Strengths ✨

1. Comprehensive test coverage: 17 unit tests + 2 integration tests covering all scenarios
2. Excellent documentation: Decision point comments, section headers, comprehensive docstrings
3. Clean implementation: Well-factored code with clear separation of concerns
4. Performance optimized: Database-level ordering, early returns, conditional context resolution
5. Backwards compatible: All new parameters are optional with sensible defaults
6. Cross-platform compatibility: POSIX path design documented and implemented correctly

Code Architecture Highlights

1. Proximity scoring algorithm (link_resolver.py:src/basic_memory/services/link_resolver.py:189-248):

   • Priority 0: Same folder (best match)
   • Priority 1-N: Ancestors (N = levels up)
   • Priority 100+N: Descendants (deprioritized)
   • Priority 1000: Unrelated paths (fallback)
   • Ties broken by shortest absolute path

2. Repository optimization (entity_repository.py:src/basic_memory/repository/entity_repository.py:71-88):

   • get_by_title() now orders by func.length(Entity.file_path) at SQL level
   • Provides "shortest path first" resolution for duplicate titles
   • Efficient single-query approach

3. API integration (knowledge_router.py:src/basic_memory/api/v2/routers/knowledge_router.py:109-110):

   • Passes source_path and strict=True to resolve endpoint
   • Enables context-aware resolution for MCP tools
   • Prevents fuzzy matching for wiki links

---

Summary

Verdict: APPROVED ✅

This PR is high-quality work that significantly enhances wiki link resolution. All checklist items are satisfied, and previous review feedback has been fully addressed.

Changes Implemented

1. ✅ Added source_path parameter to resolve_link() for context-aware resolution
2. ✅ Implemented relative path resolution: [[nested/deep-note]] from testing/link-test.md → testing/nested/deep-note.md
3. ✅ Added proximity-based resolution for duplicate titles (prefers same folder > ancestors > descendants > unrelated)
4. ✅ Strict mode disables fuzzy search fallback for wiki links
5. ✅ Updated get_by_title() to return results ordered by shortest path first

Test Coverage Summary

• 84 total tests pass (mentioned in PR body)
• 17 new unit tests in test_link_resolver.py
• 2 new integration tests in test_knowledge_router.py
• 100% coverage maintained with tests for all edge cases

No Issues Found

All previous review comments have been addressed:

• ✅ Windows compatibility documented with POSIX path note
• ✅ Literate programming comments added to _find_closest_entity()
• ✅ Decision point comments explain trigger/why/outcome for each branch
• ✅ Section headers added for logical code organization

This PR is ready to merge. 🚀

---