add link_resolver.py

src/basic_memory/models/knowledge.py

@@ -1,7 +1,10 @@
 """Knowledge graph models."""
 
+import re
+import os
 from datetime import datetime
 from typing import Optional
+from unidecode import unidecode
 
 from sqlalchemy import (
     Integer,
@@ -14,12 +17,49 @@ from sqlalchemy import (
     Index,
     JSON,
 )
-from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.orm import Mapped, mapped_column, relationship, validates
 
 from basic_memory.models.base import Base
 from enum import Enum
 
 
+def generate_permalink(file_path: str) -> str:
+    """Generate a stable permalink from a file path.
+    
+    Args:
+        file_path: Original file path
+        
+    Returns:
+        Normalized permalink that matches validation rules
+        
+    Examples:
+        >>> generate_permalink("docs/My Feature.md")
+        'docs/my-feature'
+        >>> generate_permalink("specs/API (v2).md")
+        'specs/api-v2'
+    """
+    # Remove extension
+    base = os.path.splitext(file_path)[0]
+    
+    # Transliterate unicode to ascii
+    ascii_text = unidecode(base)
+    
+    # Convert to lowercase
+    lower_text = ascii_text.lower()
+    
+    # Replace spaces and invalid chars with hyphens
+    clean_text = re.sub(r'[^a-z0-9/\-_]', '-', lower_text)
+    
+    # Collapse multiple hyphens
+    clean_text = re.sub(r'-+', '-', clean_text)
+    
+    # Clean each path segment
+    segments = clean_text.split('/')
+    clean_segments = [s.strip('-') for s in segments]
+    
+    return '/'.join(clean_segments)
+
+
 class Entity(Base):
     """
     Core entity in the knowledge graph.
@@ -35,6 +75,7 @@ class Entity(Base):
     __table_args__ = (
         UniqueConstraint("permalink", name="uix_entity_permalink"),  # Make permalink unique
         Index("ix_entity_type", "entity_type"),
+        Index("ix_entity_title", "title"),
         Index("ix_entity_created_at", "created_at"),  # For timeline queries
         Index("ix_entity_updated_at", "updated_at"),  # For timeline queries
     )
@@ -83,6 +124,23 @@ class Entity(Base):
     def relations(self):
         return self.incoming_relations + self.outgoing_relations
 
+    @validates('permalink')
+    def validate_permalink(self, key, value):
+        """Validate permalink format.
+        
+        Requirements:
+        1. Must be valid URI path component
+        2. Only lowercase letters, numbers, hyphens, and underscores
+        3. Path segments separated by forward slashes
+        4. No leading/trailing hyphens in segments
+        """
+        if not re.match(r'^[a-z0-9][a-z0-9\-_/]*[a-z0-9]$', value):
+            raise ValueError(
+                f"Invalid permalink format: {value}. "
+                "Use only lowercase letters, numbers, hyphens, and underscores."
+            )
+        return value
+
     def __repr__(self) -> str:
         return f"Entity(id={self.id}, name='{self.title}', type='{self.entity_type}', summary='{self.summary}')"
 
@@ -169,4 +227,4 @@ class Relation(Base):
     to_entity = relationship("Entity", foreign_keys=[to_id], back_populates="incoming_relations")
 
     def __repr__(self) -> str:
-        return f"Relation(id={self.id}, from_id={self.from_id}, to_id={self.to_id}, type='{self.relation_type}')"
+        return f"Relation(id={self.id}, from_id={self.from_id}, to_id={self.to_id}, type='{self.relation_type}')"

src/basic_memory/repository/entity_repository.py

@@ -23,6 +23,11 @@ class EntityRepository(Repository[Entity]):
         query = self.select().where(Entity.permalink == permalink).options(*self.get_load_options())
         return await self.find_one(query)
 
+    async def get_by_title(self, title: str) -> Optional[Entity]:
+        """Get entity by title."""
+        query = self.select().where(Entity.title == title).options(*self.get_load_options())
+        return await self.find_one(query)
+
     async def list_entities(
         self,
         entity_type: Optional[str] = None,

src/basic_memory/services/link_resolver.py

@@ -0,0 +1,84 @@
+"""Service for resolving markdown links to permalinks."""
+
+from typing import Optional, List
+
+from loguru import logger
+
+from basic_memory.services.service import BaseService
+from basic_memory.repository.entity_repository import EntityRepository
+from basic_memory.models import Entity
+from basic_memory.services.exceptions import EntityNotFoundError
+
+
+class LinkResolver(BaseService[Entity]):
+    """Service for resolving markdown links to permalinks.
+    
+    Handles both exact and fuzzy link resolution using a combination of
+    direct permalink lookup and search-based matching.
+    """
+
+    def __init__(self, entity_repository: EntityRepository):
+        """Initialize with repositories."""
+        super().__init__(entity_repository)
+        
+    async def resolve_link(
+        self,
+        link_text: str,
+        source_permalink: Optional[str] = None
+    ) -> str:
+        """Resolve a markdown link to a permalink.
+        
+        Args:
+            link_text: The text content of the link (without brackets)
+            source_permalink: Optional permalink of the source document for context
+            
+        Returns:
+            Resolved permalink, or original link text if no match found
+        """
+        logger.debug(f"Resolving link: {link_text} from source: {source_permalink}")
+        
+        # Clean link text
+        clean_text = self._normalize_link_text(link_text)
+        
+        try:
+            # Try exact permalink match first
+            entity = await self.repository.get_by_permalink(clean_text)
+            if entity:
+                logger.debug(f"Found exact permalink match: {entity.permalink}")
+                return entity.permalink
+                
+            # Fall back to title match if needed
+            entity = await self.repository.get_by_title(clean_text)
+            if entity:
+                logger.debug(f"Found title match: {entity.permalink}")
+                return entity.permalink
+                
+            # No match found - will be created
+            logger.debug(f"No match found for link: {link_text}")
+            return clean_text
+            
+        except Exception as e:
+            logger.error(f"Error resolving link {link_text}: {e}")
+            return clean_text
+
+    def _normalize_link_text(self, link_text: str) -> str:
+        """Normalize link text for matching.
+        
+        Args:
+            link_text: Raw link text from markdown
+            
+        Returns:
+            Normalized form for matching
+        """
+        # Strip whitespace
+        text = link_text.strip()
+        
+        # Remove enclosing brackets if present
+        if text.startswith('[[') and text.endswith(']]'):
+            text = text[2:-2]
+            
+        # Handle Obsidian-style aliases
+        if '|' in text:
+            text = text.split('|')[0]
+            
+        return text