feat(core): index Markdown links to project files (#1514)

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

docs/MARKDOWN_RELATIONS.md

@@ -0,0 +1,27 @@
+# Markdown path links
+
+Basic Memory indexes ordinary Markdown links to files in the same project as
+`links_to` relations, alongside existing wikilinks:
+
+```markdown
+See [the guide](../guides/Getting%20Started.md#installation).
+```
+
+The destination is resolved relative to the note containing the link. A leading
+`/` addresses the project root. Percent-encoded filenames are decoded; fragments
+and query strings do not change which file the relation targets. Reference-style
+Markdown links work too.
+
+These are exact file paths. Basic Memory does not guess a title, add `.md`, apply
+filename aliases, or search another project when the target is missing. The graph
+stores a normalized project-root target such as `/guides/Getting Started.md`;
+missing targets remain unresolved and can resolve when indexed later.
+
+External URLs, `mailto:` and `file:` links, fragment-only links, paths that escape
+the project, images, and links inside code do not create relations. Ordinary
+Markdown links always create `links_to` edges; typed relation syntax continues to
+use wikilinks. Notes with `bm_parse_semantics: false` remain graph-silent.
+
+The authored Markdown is preserved. Existing notes gain these relations on their
+next edit or reindex. This supports interoperable Markdown navigation; it does not
+by itself declare full Open Knowledge Format conformance or add an export format.

src/basic_memory/markdown/entity_parser.py

@@ -14,6 +14,7 @@
 from markdown_it import MarkdownIt
 
 from basic_memory.markdown.plugins import observation_plugin, relation_plugin
+from basic_memory.markdown.path_links import markdown_link_target
 from basic_memory.markdown.schemas import (
     EntityFrontmatter,
     EntityMarkdown,
@@ -154,7 +155,7 @@ class EntityContent:
     relations: list[Relation] = field(default_factory=list)
 
 
-def parse(content: str) -> EntityContent:
+def parse(content: str, *, source_path: str | None = None) -> EntityContent:
     """Parse markdown content into EntityMarkdown."""
 
     # Parse content for observations and relations using markdown-it
@@ -163,6 +164,17 @@ def parse(content: str) -> EntityContent:
 
     if content:
         for token in md.parse(content):
+            # MarkdownIt owns link syntax, including escapes, reference links and
+            # code exclusion. Rooted targets retain exact project-path semantics
+            # through deferred resolution without changing the authored body.
+            if source_path is not None:
+                for child in token.children or []:
+                    if child.type == "link_open":
+                        href = child.attrGet("href")
+                        assert isinstance(href, str)
+                        target = markdown_link_target(href, source_path) if href else None
+                        if target is not None:
+                            relations.append(Relation(type="links_to", target=target))
             # check for observations and relations
             if token.meta:
                 if "observation" in token.meta:
@@ -349,7 +361,16 @@ async def parse_markdown_content(
             or (isinstance(semantic_setting, str) and semantic_setting.lower() == "false")
         )
         entity_content = (
-            parse(post.content) if parse_semantics else EntityContent(content=post.content)
+            parse(
+                post.content,
+                source_path=(
+                    file_path.relative_to(self.base_path).as_posix()
+                    if file_path.is_absolute()
+                    else file_path.as_posix()
+                ),
+            )
+            if parse_semantics
+            else EntityContent(content=post.content)
         )
 
         # The parser reports only a qualifier the author plainly meant: an unknown kind,

src/basic_memory/markdown/path_links.py

@@ -0,0 +1,29 @@
+"""Project-local targets carried by ordinary Markdown links."""
+
+from pathlib import PurePosixPath
+from urllib.parse import unquote, urlsplit
+
+
+def markdown_link_target(href: str, source_path: str) -> str | None:
+    """Return a project-root path, excluding URLs and paths escaping the project."""
+    try:
+        parsed = urlsplit(href)
+    except ValueError:
+        # A malformed URL remains authored prose, not a failed note write.
+        return None
+    if parsed.scheme or parsed.netloc or not parsed.path:
+        return None
+    path = unquote(parsed.path)
+    if "\\" in path or "\x00" in path:
+        return None
+    parts = [] if path.startswith("/") else list(PurePosixPath(source_path).parent.parts)
+    for part in path.split("/"):
+        if part in {"", "."}:
+            continue
+        if part == "..":
+            if not parts:
+                return None
+            parts.pop()
+        else:
+            parts.append(part)
+    return "/" + "/".join(parts) if parts else None

src/basic_memory/services/bulk_link_resolver.py

@@ -34,6 +34,8 @@ class RelationTargetReference:
     @classmethod
     def parse(cls, link_text: str) -> "RelationTargetReference":
         """Normalize wikilink syntax once for the whole bulk-resolution pass."""
+        if link_text.startswith("/"):
+            return cls(original=link_text, identifier=link_text, explicitly_qualified=False)
         clean_text, _ = normalize_link_text(link_text)
         return cls(
             original=link_text,
@@ -206,6 +208,11 @@ def resolve(self, target: RelationTargetReference) -> Entity | None:
         """Resolve one parsed target without additional I/O."""
         current_index = self.entity_indexes[self.current_project_id]
 
+        # Rooted Markdown targets are file identities, never title/permalink or
+        # cross-project guesses, including while their target is still absent.
+        if target.identifier.startswith("/"):
+            return current_index.by_file_path.get(target.identifier[1:])
+
         try:
             external_id = str(uuid_mod.UUID(target.identifier))
         except ValueError:

src/basic_memory/services/link_resolver.py

@@ -183,6 +183,14 @@ async def resolve_link(
         """
         logger.trace(f"Resolving link: {link_text} (source: {source_path})")
 
+        # Markdown hrefs are normalized to project-root paths by the parser.
+        # They must not fall through to aliases, titles or another project.
+        if link_text.startswith("/"):
+            async with db.scoped_session(self.session_maker, session) as active_session:
+                return await self.entity_repository.get_by_file_path(
+                    active_session, link_text[1:], load_relations=load_relations
+                )
+
         # Clean link text and extract any alias
         clean_text, alias = self._normalize_link_text(link_text)
         explicit_project_reference = "::" in clean_text

src/basic_memory/services/note_preparation.py

@@ -950,6 +950,10 @@ async def resolve_deferred_self_relation(
     entity: Entity,
     session: AsyncSession | None = None,
 ) -> Entity | None:
+    # Background resolution excludes self-edges, so exact Markdown paths must
+    # resolve here before wikilink alias parsing can reinterpret filename bytes.
+    if target.startswith("/"):
+        return entity if target[1:] == entity.file_path else None
     clean_target = target.strip()
     if clean_target.startswith("[[") and clean_target.endswith("]]"):
         clean_target = clean_target[2:-2].strip()

test-int/mcp/test_markdown_path_relations_integration.py

@@ -0,0 +1,81 @@
+"""Markdown links reach the project graph without changing authored content."""
+
+from pathlib import Path
+
+import pytest
+from fastmcp import Client
+
+from basic_memory import db
+from basic_memory.repository.entity_repository import EntityRepository
+from basic_memory.repository.relation_repository import RelationRepository
+from basic_memory.services.bulk_link_resolver import BulkLinkResolver
+
+
+@pytest.mark.asyncio
+async def test_markdown_paths_are_indexed_and_resolved_exactly(
+    mcp_server, app, app_config, test_project, engine_factory
+):
+    body = "See [target](../targets/Guide.md#details) and [web](https://example.com).\n"
+    async with Client(mcp_server) as client:
+        for title, directory, content in [
+            ("Guide", "targets", "# Guide\n\n## Details\nContent."),
+            ("Source", "notes", body),
+        ]:
+            result = await client.call_tool(
+                "write_note",
+                {
+                    "title": title,
+                    "directory": directory,
+                    "content": content,
+                    "project": test_project.name,
+                },
+            )
+            assert not result.is_error
+
+    _, session_maker = engine_factory
+    entities = EntityRepository(project_id=test_project.id)
+    relations = RelationRepository(project_id=test_project.id)
+    async with db.scoped_session(session_maker) as session:
+        target = await entities.get_by_file_path(session, "targets/Guide.md")
+        assert target is not None
+        edges = await relations.find_by_type(session, "links_to")
+        assert [edge.to_name for edge in edges] == ["/targets/Guide.md"]
+        assert edges[0].to_id == target.id
+        resolved = await BulkLinkResolver(entities, app_config).resolve_relation_targets(
+            [edges[0].to_name, "/Guide", "/targets/guide.md"], session=session
+        )
+        resolved_target = resolved[edges[0].to_name]
+        assert resolved_target is not None
+        assert resolved_target.id == target.id
+        assert resolved["/Guide"] is None
+        assert resolved["/targets/guide.md"] is None
+
+    assert body.strip() in (Path(test_project.path) / "notes" / "Source.md").read_text()
+
+
+@pytest.mark.asyncio
+async def test_markdown_self_link_is_resolved_when_written(
+    mcp_server, app, test_project, engine_factory
+):
+    async with Client(mcp_server) as client:
+        await client.call_tool(
+            "write_note",
+            {
+                "title": "Self",
+                "directory": "notes",
+                "content": "[self](Self.md)",
+                "project": test_project.name,
+            },
+        )
+    _, session_maker = engine_factory
+    async with db.scoped_session(session_maker) as session:
+        source = await EntityRepository(project_id=test_project.id).get_by_file_path(
+            session, "notes/Self.md"
+        )
+        assert source is not None
+        edges = await RelationRepository(project_id=test_project.id).find_by_type(
+            session, "links_to"
+        )
+        assert len(edges) == 1
+        assert edges[0].to_name == "/notes/Self.md"
+        assert edges[0].to_id == source.id

tests/markdown/test_path_links.py

@@ -0,0 +1,55 @@
+"""Ordinary Markdown links retain exact project-local path semantics."""
+
+import pytest
+
+from basic_memory.markdown.entity_parser import EntityParser, parse
+from basic_memory.markdown.path_links import markdown_link_target
+
+
+@pytest.mark.parametrize(
+    ("href", "expected"),
+    [
+        ("../Guide%20One.md#section", "/Guide One.md"),
+        ("same.md", "/notes/same.md"),
+        ("./nested/../same.md", "/notes/same.md"),
+        ("/root.md", "/root.md"),
+        ("../../outside.md", None),
+        ("https://example.com/note.md", None),
+        ("//example.com/note.md", None),
+        ("mailto:me@example.com", None),
+        ("file:///tmp/note.md", None),
+        ("https://[broken", None),
+        ("#section", None),
+        ("../", None),
+        ("bad%00.md", None),
+        ("bad%5Cpath.md", None),
+    ],
+)
+def test_markdown_target_is_bounded_to_project(href, expected):
+    assert markdown_link_target(href, "notes/source.md") == expected
+
+
+def test_markdown_parser_uses_real_links_without_rewriting_content():
+    content = """See [guide](../Guide%20One.md#section) and [reference][ref].
+![image](picture.png) and `[code](code.md)` and [web](https://example.com).
+[[Existing Wiki]]
+
+[ref]: next.md
+"""
+    parsed = parse(content, source_path="notes/source.md")
+    assert parsed.content == content
+    assert [(relation.type, relation.target) for relation in parsed.relations] == [
+        ("links_to", "/Guide One.md"),
+        ("links_to", "/notes/next.md"),
+        ("links_to", "Existing Wiki"),
+    ]
+
+
+@pytest.mark.asyncio
+async def test_remote_content_parsing_respects_semantic_opt_out(tmp_path):
+    parser = EntityParser(tmp_path)
+    body = "[not indexed](target.md)"
+    content = "---\nbm_parse_semantics: false\n---\n" + body
+    parsed = await parser.parse_markdown_content(tmp_path / "absent.md", content)
+    assert parsed.content == body
+    assert parsed.relations == []

tests/services/test_markdown_path_resolution.py

@@ -0,0 +1,32 @@
+"""Rooted path relations cannot resolve to semantic aliases."""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from basic_memory import db
+from basic_memory.models import Entity
+
+
+@pytest.mark.asyncio
+async def test_rooted_path_resolves_only_exact_file(
+    link_resolver, entity_repository, test_project, session_maker
+):
+    now = datetime.now(timezone.utc)
+    entity = Entity(
+        title="Guide",
+        note_type="note",
+        content_type="text/markdown",
+        file_path="notes/Guide.md",
+        permalink="guide",
+        created_at=now,
+        updated_at=now,
+        project_id=test_project.id,
+    )
+    async with db.scoped_session(session_maker) as session:
+        await entity_repository.add(session, entity)
+    resolved = await link_resolver.resolve_link("/notes/Guide.md")
+    assert resolved is not None
+    assert resolved.id == entity.id
+    assert await link_resolver.resolve_link("/guide") is None
+    assert await link_resolver.resolve_link("/notes/guide.md") is None