BUG: build_context empty results on valid note identifiers (fallback resolution + diagnostics)

[phernandez]

Problem

build_context can return empty results for notes that are retrievable via read-note, especially when callers pass path-like identifiers that are valid from user perspective but not exact permalink matches.

Related downstream issue: basicmachines-co/openclaw-basic-memory#17

Why this looks upstream

ContextService.build_context performs exact permalink lookup for non-wildcard URLs and currently has no fallback resolution path:

• src/basic_memory/services/context_service.py
• src/basic_memory/mcp/tools/build_context.py
• src/basic_memory/mcp/project_context.py (resolve_project_and_path)

Requested fix

Improve context identifier resolution and empty-result diagnostics:

1. If exact permalink lookup returns 0 primaries, try a fallback resolver path:
   • alternate project-prefix normalization (with/without project prefix), and/or
   • resolve via entity resolver (same strategy family used by read tooling).
2. Include normalized/resolved lookup path in JSON metadata when results are empty.
3. Return a machine-readable "no primary match" reason (not just empty list) so clients can distinguish "no relations" from "lookup miss".

Acceptance criteria

• build_context finds primary note for common memory URL forms when note exists.
• Empty result payload includes enough diagnostics to debug path mismatch quickly.
• Backward compatibility: existing successful exact lookups behave unchanged.

[claude]

Claude finished @phernandez's task in 9m 3s —— View job • claude/issue-582-20260218-1654 • Create PR ➔

---

Triage + Implementation Complete

Classification: Bug + Enhancement | Priority: Medium-High | Component: MCP / Context Service | Complexity: Medium

Root cause: ContextService.build_context performed a single exact permalink= lookup with no fallback. In contrast, read_note uses a full LinkResolver pipeline (external_id → permalink → title → file path → fuzzy). When path-like identifiers don't exactly match stored permalinks (e.g., due to project-prefix mismatch), build_context returned empty silently.

No duplicates found. Labels added: bug, enhancement.

Implementation checklist:

• Read relevant source files
• Check for duplicate issues
• Add labels and classify issue
• Add no_primary_match and resolved_path diagnostic fields to ContextMetadata + MemoryMetadata
• Add 3-stage fallback to ContextService.build_context: wildcard-prefix → strip-prefix → title FTS search
• Update to_graph_context to pass through new diagnostic fields to API response
• Write tests (5 new test cases) for fallback cases + diagnostics
• Commit and push changes

Changes made

src/basic_memory/services/context_service.py

• Added resolved_path and no_primary_match fields to ContextMetadata dataclass
• When exact permalink lookup returns 0 results, now tries three fallbacks:
  1. Wildcard prefix match */path — for when stored permalink has extra leading segment (e.g. project prefix) that caller omitted
  2. Strip-prefix exact lookup — strips the first path segment and retries, for when caller over-specified the path
  3. Title FTS search on the last path segment — catches normalization drift between caller and stored values
• Sets no_primary_match diagnostic string when all fallbacks are exhausted

src/basic_memory/schemas/memory.py

• Added resolved_path: Optional[str] and no_primary_match: Optional[str] to MemoryMetadata

src/basic_memory/api/v2/utils.py

• to_graph_context now maps the two new diagnostic fields through to the API response

tests/services/test_context_service.py — 5 new tests:

• test_build_context_fallback_wildcard_prefix — missing project prefix case
• test_build_context_fallback_strip_prefix — extra leading prefix case
• test_build_context_fallback_title_search — title FTS fallback case
• test_build_context_diagnostics_no_match — all fallbacks exhausted, diagnostic fields populated
• test_build_context_diagnostics_exact_match_no_diagnostic — exact match, no diagnostics (backward compat)

|

[phernandez]

Downstream tracking

• Downstream: BUG: bm_context returns empty for valid notes openclaw-basic-memory#17

[bm-clawd]

Investigation from current main (v0.18.3)

Confirmed the bug is still present on main. Here's what I found:

Reproduction

# read-note resolves fine (uses full LinkResolver pipeline)
bm tool read-note "2026-02-24" --project claw  ✅ returns note

# build-context fails with the same identifier
bm tool build-context "memory://memory/2026-02-24" --project claw  ❌ empty results
bm tool build-context "memory://2026-02-24" --project claw  ❌ empty results

# Only works with exact title match
bm tool build-context "memory://MEMORY" --project claw  ✅ works

Root Cause Confirmed

The note's frontmatter has permalink: memory/2026-02-24. When build_context processes a memory:// URL, it constructs the lookup path and the project prefix (claw/) gets involved, but the exact permalink match fails because:

1. memory://memory/2026-02-24 → looks for permalink claw/memory/2026-02-24 (over-specified with project prefix)
2. memory://2026-02-24 → looks for permalink claw/2026-02-24 (missing the memory/ path segment)

Meanwhile read_note uses the full LinkResolver pipeline (external_id → permalink → title → file path → fuzzy) which handles all these cases gracefully.

The Gap

build_context does a single exact permalink lookup with no fallback. read_note has robust multi-strategy resolution. This asymmetry means the OpenClaw plugin's build_context tool (used for memory:// URL navigation) silently returns empty on identifiers that read_note handles fine.

Branch Status

Claude's branch claude/issue-582-20260218-1654 has a solid fix (3-stage fallback: wildcard prefix → strip-prefix → title FTS). It's 29 commits behind main though — may need a rebase before PR. The approach looks correct based on my testing.