feat: expose external_id in EntityResponse and link resolver (#569)

Signed-off-by: Drew Cain <groksrc@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

src/basic_memory/schemas/response.py

@@ -195,6 +195,7 @@ class EntityResponse(SQLAlchemyModel):
     entity_metadata: Optional[Dict] = None
     checksum: Optional[str] = None
     content_type: ContentType
+    external_id: Optional[str] = None
     observations: List[ObservationResponse] = []
     relations: List[RelationResponse] = []
     created_at: datetime

src/basic_memory/services/link_resolver.py

@@ -1,5 +1,6 @@
 """Service for resolving markdown links to permalinks."""
 
+import uuid as uuid_mod
 from typing import Optional, Tuple, Dict
 
 from loguru import logger
@@ -63,6 +64,19 @@ class LinkResolver:
         explicit_project_reference = "::" in clean_text
         clean_text = normalize_project_reference(clean_text)
 
+        # --- External ID Resolution ---
+        # Try external_id first if identifier looks like a UUID.
+        # Canonicalize to lowercase-hyphen form so uppercase or unhyphenated
+        # UUIDs also match the stored external_id values.
+        try:
+            canonical_id = str(uuid_mod.UUID(clean_text))
+            entity = await self.entity_repository.get_by_external_id(canonical_id)
+            if entity:
+                logger.debug(f"Found entity by external_id: {entity.permalink}")
+                return entity
+        except ValueError:
+            pass
+
         # Trigger: link uses project namespace syntax (project::note)
         # Why: treat it as an explicit cross-project reference
         # Outcome: resolve only within the referenced project scope