fix: resolve entity relations in background to prevent cold start blocking (#319)

Signed-off-by: phernandez <[email protected]>
Co-authored-by: Claude <[email protected]>

Author: phernandez

src/basic_memory/api/routers/knowledge_router.py

@@ -27,6 +27,26 @@
 
 router = APIRouter(prefix="/knowledge", tags=["knowledge"])
 
+
+async def resolve_relations_background(sync_service, entity_id: int, entity_permalink: str) -> None:
+    """Background task to resolve relations for a specific entity.
+
+    This runs asynchronously after the API response is sent, preventing
+    long delays when creating entities with many relations.
+    """
+    try:
+        # Only resolve relations for the newly created entity
+        await sync_service.resolve_relations(entity_id=entity_id)
+        logger.debug(
+            f"Background: Resolved relations for entity {entity_permalink} (id={entity_id})"
+        )
+    except Exception as e:
+        # Log but don't fail - this is a background task
+        logger.warning(
+            f"Background: Failed to resolve relations for entity {entity_permalink}: {e}"
+        )
+
+
 ## Create endpoints
 
 
@@ -88,15 +108,12 @@ async def create_or_update_entity(
     # reindex
     await search_service.index_entity(entity, background_tasks=background_tasks)
 
-    # Attempt immediate relation resolution when creating new entities
-    # This helps resolve forward references when related entities are created in the same session
+    # Schedule relation resolution as a background task for new entities
+    # This prevents blocking the API response while resolving potentially many relations
     if created:
-        try:
-            await sync_service.resolve_relations()
-            logger.debug(f"Resolved relations after creating entity: {entity.permalink}")
-        except Exception as e:  # pragma: no cover
-            # Don't fail the entire request if relation resolution fails
-            logger.warning(f"Failed to resolve relations after entity creation: {e}")
+        background_tasks.add_task(
+            resolve_relations_background, sync_service, entity.id, entity.permalink or ""
+        )
 
     result = EntityResponse.model_validate(entity)
 

src/basic_memory/repository/relation_repository.py

@@ -73,5 +73,18 @@ async def find_unresolved_relations(self) -> Sequence[Relation]:
         result = await self.execute_query(query)
         return result.scalars().all()
 
+    async def find_unresolved_relations_for_entity(self, entity_id: int) -> Sequence[Relation]:
+        """Find unresolved relations for a specific entity.
+
+        Args:
+            entity_id: The entity whose unresolved outgoing relations to find.
+
+        Returns:
+            List of unresolved relations where this entity is the source.
+        """
+        query = select(Relation).filter(Relation.from_id == entity_id, Relation.to_id.is_(None))
+        result = await self.execute_query(query)
+        return result.scalars().all()
+
     def get_load_options(self) -> List[LoaderOption]:
         return [selectinload(Relation.from_entity), selectinload(Relation.to_entity)]

src/basic_memory/schemas/base.py

@@ -14,7 +14,7 @@
 import os
 import mimetypes
 import re
-from datetime import datetime, time, timedelta
+from datetime import datetime, timedelta
 from pathlib import Path
 from typing import List, Optional, Annotated, Dict
 

src/basic_memory/services/entity_service.py

@@ -422,34 +422,47 @@ async def update_entity_relations(
         # Clear existing relations first
         await self.relation_repository.delete_outgoing_relations_from_entity(db_entity.id)
 
-        # Process each relation
-        for rel in markdown.relations:
-            # Resolve the target permalink
-            target_entity = await self.link_resolver.resolve_link(
-                rel.target,
-            )
-
-            # if the target is found, store the id
-            target_id = target_entity.id if target_entity else None
-            # if the target is found, store the title, otherwise add the target for a "forward link"
-            target_name = target_entity.title if target_entity else rel.target
-
-            # Create the relation
-            relation = Relation(
-                from_id=db_entity.id,
-                to_id=target_id,
-                to_name=target_name,
-                relation_type=rel.type,
-                context=rel.context,
-            )
-            try:
-                await self.relation_repository.add(relation)
-            except IntegrityError:
-                # Unique constraint violation - relation already exists
-                logger.debug(
-                    f"Skipping duplicate relation {rel.type} from {db_entity.permalink} target: {rel.target}"
+        # Batch resolve all relation targets in parallel
+        if markdown.relations:
+            import asyncio
+
+            # Create tasks for all relation lookups
+            lookup_tasks = [
+                self.link_resolver.resolve_link(rel.target) for rel in markdown.relations
+            ]
+
+            # Execute all lookups in parallel
+            resolved_entities = await asyncio.gather(*lookup_tasks, return_exceptions=True)
+
+            # Process results and create relation records
+            for rel, resolved in zip(markdown.relations, resolved_entities):
+                # Handle exceptions from gather and None results
+                target_entity: Optional[Entity] = None
+                if not isinstance(resolved, Exception):
+                    # Type narrowing: resolved is Optional[Entity] here, not Exception
+                    target_entity = resolved  # type: ignore
+
+                # if the target is found, store the id
+                target_id = target_entity.id if target_entity else None
+                # if the target is found, store the title, otherwise add the target for a "forward link"
+                target_name = target_entity.title if target_entity else rel.target
+
+                # Create the relation
+                relation = Relation(
+                    from_id=db_entity.id,
+                    to_id=target_id,
+                    to_name=target_name,
+                    relation_type=rel.type,
+                    context=rel.context,
                 )
-                continue
+                try:
+                    await self.relation_repository.add(relation)
+                except IntegrityError:
+                    # Unique constraint violation - relation already exists
+                    logger.debug(
+                        f"Skipping duplicate relation {rel.type} from {db_entity.permalink} target: {rel.target}"
+                    )
+                    continue
 
         return await self.repository.get_by_file_path(path)
 

src/basic_memory/sync/sync_service.py

@@ -585,12 +585,27 @@ async def handle_move(self, old_path, new_path):
             # update search index
             await self.search_service.index_entity(updated)
 
-    async def resolve_relations(self):
-        """Try to resolve any unresolved relations"""
+    async def resolve_relations(self, entity_id: int | None = None):
+        """Try to resolve unresolved relations.
 
-        unresolved_relations = await self.relation_repository.find_unresolved_relations()
+        Args:
+            entity_id: If provided, only resolve relations for this specific entity.
+                      Otherwise, resolve all unresolved relations in the database.
+        """
 
-        logger.info("Resolving forward references", count=len(unresolved_relations))
+        if entity_id:
+            # Only get unresolved relations for the specific entity
+            unresolved_relations = (
+                await self.relation_repository.find_unresolved_relations_for_entity(entity_id)
+            )
+            logger.info(
+                f"Resolving forward references for entity {entity_id}",
+                count=len(unresolved_relations),
+            )
+        else:
+            # Get all unresolved relations (original behavior)
+            unresolved_relations = await self.relation_repository.find_unresolved_relations()
+            logger.info("Resolving all forward references", count=len(unresolved_relations))
 
         for relation in unresolved_relations:
             logger.trace(

tests/api/test_async_client.py

@@ -35,9 +35,9 @@ def test_create_client_configures_extended_timeouts():
         # Verify timeout configuration
         assert isinstance(client.timeout, Timeout)
         assert client.timeout.connect == 10.0  # 10 seconds for connection
-        assert client.timeout.read == 30.0     # 30 seconds for reading
-        assert client.timeout.write == 30.0    # 30 seconds for writing
-        assert client.timeout.pool == 30.0     # 30 seconds for pool
+        assert client.timeout.read == 30.0  # 30 seconds for reading
+        assert client.timeout.write == 30.0  # 30 seconds for writing
+        assert client.timeout.pool == 30.0  # 30 seconds for pool
 
     # Also test with proxy URL
     with patch.dict("os.environ", {"BASIC_MEMORY_PROXY_URL": "http://localhost:8000"}):

tests/api/test_relation_background_resolution.py

@@ -0,0 +1,40 @@
+"""Test that relation resolution happens in the background."""
+
+import pytest
+from unittest.mock import AsyncMock
+
+from basic_memory.api.routers.knowledge_router import resolve_relations_background
+
+
+@pytest.mark.asyncio
+async def test_resolve_relations_background_success():
+    """Test that background relation resolution calls sync service correctly."""
+    # Create mocks
+    sync_service = AsyncMock()
+    sync_service.resolve_relations = AsyncMock(return_value=None)
+
+    entity_id = 123
+    entity_permalink = "test/entity"
+
+    # Call the background function
+    await resolve_relations_background(sync_service, entity_id, entity_permalink)
+
+    # Verify sync service was called with the entity_id
+    sync_service.resolve_relations.assert_called_once_with(entity_id=entity_id)
+
+
+@pytest.mark.asyncio
+async def test_resolve_relations_background_handles_errors():
+    """Test that background relation resolution handles errors gracefully."""
+    # Create mock that raises an exception
+    sync_service = AsyncMock()
+    sync_service.resolve_relations = AsyncMock(side_effect=Exception("Test error"))
+
+    entity_id = 123
+    entity_permalink = "test/entity"
+
+    # Call should not raise - errors are logged
+    await resolve_relations_background(sync_service, entity_id, entity_permalink)
+
+    # Verify sync service was called
+    sync_service.resolve_relations.assert_called_once_with(entity_id=entity_id)

tests/schemas/test_base_timeframe_minimum.py

@@ -52,7 +52,9 @@ def test_one_day_returns_one_day(self):
 
         # Should be approximately 1 day ago (within 24 hours)
         diff_hours = abs((result.replace(tzinfo=None) - one_day_ago).total_seconds()) / 3600
-        assert diff_hours < 24, f"Expected ~1 day ago for '1d', got {result} (diff: {diff_hours} hours)"
+        assert diff_hours < 24, (
+            f"Expected ~1 day ago for '1d', got {result} (diff: {diff_hours} hours)"
+        )
 
     @freeze_time("2025-01-15 15:00:00")
     def test_two_days_returns_two_days(self):
@@ -63,7 +65,9 @@ def test_two_days_returns_two_days(self):
 
         # Should be approximately 2 days ago (within 24 hours)
         diff_hours = abs((result.replace(tzinfo=None) - two_days_ago).total_seconds()) / 3600
-        assert diff_hours < 24, f"Expected ~2 days ago for '2d', got {result} (diff: {diff_hours} hours)"
+        assert diff_hours < 24, (
+            f"Expected ~2 days ago for '2d', got {result} (diff: {diff_hours} hours)"
+        )
 
     @freeze_time("2025-01-15 15:00:00")
     def test_one_week_returns_one_week(self):
@@ -74,7 +78,9 @@ def test_one_week_returns_one_week(self):
 
         # Should be approximately 1 week ago (within 24 hours)
         diff_hours = abs((result.replace(tzinfo=None) - one_week_ago).total_seconds()) / 3600
-        assert diff_hours < 24, f"Expected ~1 week ago for '1 week', got {result} (diff: {diff_hours} hours)"
+        assert diff_hours < 24, (
+            f"Expected ~1 week ago for '1 week', got {result} (diff: {diff_hours} hours)"
+        )
 
     @freeze_time("2025-01-15 15:00:00")
     def test_zero_days_returns_one_day_minimum(self):
@@ -95,4 +101,4 @@ def test_timezone_awareness(self):
     def test_invalid_timeframe_raises_error(self):
         """Test that invalid timeframe strings raise ValueError."""
         with pytest.raises(ValueError, match="Could not parse timeframe"):
-            parse_timeframe("invalid_timeframe")
+            parse_timeframe("invalid_timeframe")

tests/schemas/test_schemas.py

@@ -2,7 +2,7 @@
 
 import os
 import pytest
-from datetime import datetime, time, timedelta
+from datetime import datetime, timedelta
 from pydantic import ValidationError, BaseModel
 
 from basic_memory.schemas import (