[BUG] build_context does not support underscore format in memory:// URLs

[BeaconSage]

name: Bug report
about: Create a report to help us improve Basic Memory
title: '[BUG] build_context does not support underscore format in memory:// URLs'
labels: bug
assignees: ''

Bug Description

When using Basic Memory's build_context function with memory:// URLs, it fails to recognize paths that contain underscores in the relation type segment. The function only works with hyphenated format (e.g., part-of) but not with underscore format (e.g., part_of), even when both formats exist in the actual markdown files.

Steps To Reproduce

1. Create markdown files with relation links using both formats:
   • part-of [[target1]] (hyphenated)
   • part_of [[target2]] (underscore)
2. Use build_context with memory:// URL pattern matching:
   • memory://path/to/file/part-of/* → Returns results ✅
   • memory://path/to/file/part_of/* → Returns empty results ❌

Expected Behavior

Both underscore and hyphenated formats should be supported and return matching results, as both are valid markdown link formats that users might naturally use.

Actual Behavior

• memory://workflow/specs/workflow-manager-agent/part-of/* returns 2 results
• memory://workflow/specs/workflow-manager-agent/part_of/* returns 0 results

The underscore format fails silently with empty results, even when matching content exists.

Environment

• OS: macOS 14.5 (Darwin 24.5.0, ARM64)
• Python version: 3.13.5
• Basic Memory version: Latest (via MCP)
• Installation method: MCP server
• Claude Desktop version: Latest

Additional Context

This inconsistency affects user experience as both underscore and hyphenated formats are commonly used in markdown. Users may naturally use either format and expect both to work.

Example of actual file content showing both formats:

- part-of [[Sequence Diagram Operations Guide]] - task parsing syntax, generation standards, participant validation mechanism
- part_of [[Knowledge Deposition Strategy Specification]]

Tested URLs that demonstrate the issue:

• Working: memory://workflow/specs/workflow-manager-agent/part-of/*
• Broken: memory://workflow/specs/workflow-manager-agent/part_of/*

Possible Solution

The URL parsing logic should normalize both underscore and hyphenated formats, or support pattern matching that works with both formats.

[phernandez]

@claude can you research this issue?

[claude]

Claude finished @phernandez's task —— View job

---

Research Complete ✅

I've investigated the issue with build_context not supporting underscore format in memory:// URLs. Here are my findings:

Root Cause

The issue occurs because of how permalinks are generated and stored in the search index. The generate_permalink() function in src/basic_memory/utils.py always converts underscores to hyphens (lines 102, 123):

# replace underscores with hyphens
text_with_hyphens = lower_text.replace("_", "-")

This conversion happens at multiple stages:

1. When relations are indexed, their permalinks are generated using generate_permalink() which converts part_of to part-of
2. When searching with memory:// URLs, the path is used directly without normalization
3. The GLOB pattern matching looks for exact matches in the indexed permalinks

Why This Matters

• User markdown files can contain relations like - part_of [[target]]
• These get indexed with permalink: source/part-of/target (underscore converted)
• When searching with memory://source/part_of/*, it finds nothing because the index contains part-of
• When searching with memory://source/part-of/*, it works because it matches the indexed format

Evidence from Code

1. Relation permalink generation (src/basic_memory/models/knowledge.py:208):

   return generate_permalink(f"{from_permalink}/{self.relation_type}/{to_permalink}")

2. Pattern matching in search (src/basic_memory/services/context_service.py:109):

   primary = await self.search_repository.search(
       permalink_match=path, limit=limit, offset=offset
   )

3. GLOB search uses direct pattern (src/basic_memory/repository/search_repository.py:411):

   if "*" in permalink_match:
       conditions.append("permalink GLOB :permalink")

Tasks Completed

• Search for build_context function implementation
• Examine memory:// URL parsing logic
• Investigate relation type handling in URLs
• Document findings and root cause
• Suggest potential solution

Suggested Solution

Two possible approaches:

1. Normalize memory:// URL paths before searching (Recommended)

   • Apply the same generate_permalink() transformation to the search path
   • This ensures consistency between what's stored and what's searched
   • Minimal code change in context_service.py

2. Store multiple permalink variants in the index

   • Index both part-of and part_of versions
   • More complex but allows both formats to work
   • Requires schema and indexing changes

The first approach would be simpler and maintain backward compatibility while fixing the issue.

---

Job Run · Branch

[phernandez]

@claude make a PR with the fix

• we should support relations with underscores: part_of
• when the memory url is parsed, we should convert _ to -

We should be generous with what we accept as input, and convert it to the format we need internally.

Make sure we have an integration test for this case

[claude]

Claude encountered an error —— View job • claude/issue-304-20250926-1840 • Create PR ➔

---

✅ Fix Implemented

I've successfully implemented the fix to support underscores in memory:// URLs for the build_context function.

Changes Made

1. Modified context_service.py:

   • Added normalization of memory URL paths using generate_permalink() before searching
   • This converts underscores to hyphens to match the stored permalinks format
   • Applied normalization to both pattern matching (*) and exact path lookups
   • Updated metadata to use normalized path for consistency

2. Created comprehensive integration tests (test_build_context_underscore.py):

   • Test underscore normalization with different relation formats (part_of vs part-of)
   • Test wildcard patterns with underscores
   • Test exact paths with underscores
   • Test complex paths with underscores in entity names and relations
   • All test variations (underscore/hyphen combinations) now work correctly

How it Works

The fix implements the principle of being "generous with what we accept as input" by:

• Accepting memory:// URLs with either underscores or hyphens
• Normalizing them internally to the hyphenated format used in the search index
• Ensuring consistent results regardless of the format used

Next Steps

---

Job Run · Branch