fix: build_context related_results schema validation failure (#627)

Related results in build_context responses were losing required identifying
fields (title, file_path, created_at) because _slim_context() stripped them
post-serialization, creating a gap between the Pydantic schema and the actual
response payload. This caused schema validation failures in Claude Desktop.

Replace post-hoc dict stripping with Pydantic Field(exclude=True) on
internal-only fields so the models themselves control what gets serialized:

- EntitySummary: exclude entity_id, keep created_at (🐛 the bug fix)
- RelationSummary: exclude internal IDs, keep title/file_path/created_at
- ObservationSummary: exclude parent-redundant fields
- MemoryMetadata: exclude generated_at and total_results

Delete _slim_context(), _slim_summary(), and all _*_STRIP sets from
build_context.py — one set of models, one serialization path.

Add get_load_options() to ObservationRepository for eager entity loading.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/mcp/tools/build_context.py

@@ -22,74 +22,6 @@
     RelationSummary,
 )
 
-# --- Fields to strip from each model (redundant with parent entity) ---
-
-_OBSERVATION_STRIP = {
-    "observation_id",
-    "entity_id",
-    "entity_external_id",
-    "title",
-    "file_path",
-    "created_at",
-}
-_RELATION_STRIP = {
-    "relation_id",
-    "entity_id",
-    "from_entity_id",
-    "from_entity_external_id",
-    "to_entity_id",
-    "to_entity_external_id",
-    "title",
-    "file_path",
-    "created_at",
-}
-_ENTITY_STRIP = {"entity_id", "created_at"}
-_METADATA_STRIP = {"total_results", "generated_at"}
-
-
-def _slim_summary(summary: EntitySummary | RelationSummary | ObservationSummary) -> dict:
-    """Strip redundant fields from a summary model based on its type."""
-    if isinstance(summary, ObservationSummary):
-        strip = _OBSERVATION_STRIP
-    elif isinstance(summary, RelationSummary):
-        strip = _RELATION_STRIP
-    else:
-        strip = _ENTITY_STRIP
-
-    data = summary.model_dump()
-    for key in strip:
-        data.pop(key, None)
-    return data
-
-
-def _slim_context(graph: GraphContext) -> dict:
-    """Transform GraphContext into a slimmed dict, stripping redundant fields.
-
-    Reduces payload size ~40% by removing fields on nested objects that
-    duplicate information already present on the parent entity (IDs,
-    timestamps, file paths).
-    """
-    slimmed_results = []
-    for result in graph.results:
-        slimmed_results.append(
-            {
-                "primary_result": _slim_summary(result.primary_result),
-                "observations": [_slim_summary(obs) for obs in result.observations],
-                "related_results": [_slim_summary(rel) for rel in result.related_results],
-            }
-        )
-
-    metadata = graph.metadata.model_dump()
-    for key in _METADATA_STRIP:
-        metadata.pop(key, None)
-
-    return {
-        "results": slimmed_results,
-        "metadata": metadata,
-        "page": graph.page,
-        "page_size": graph.page_size,
-    }
-
 
 def _format_entity_block(result: ContextResult) -> str:
     """Format a single context result as a markdown block."""
@@ -194,7 +126,7 @@ def _format_context_markdown(graph: GraphContext, project: str) -> str:
     - Or standard formats like "7d", "24h"
 
     Format options:
-    - "json" (default): Slimmed JSON with redundant fields removed
+    - "json" (default): Structured JSON with internal fields excluded
     - "text": Compact markdown text for LLM consumption
     """,
     annotations={"readOnlyHint": True, "openWorldHint": False},
@@ -231,12 +163,12 @@ async def build_context(
         page: Page number of results to return (default: 1)
         page_size: Number of results to return per page (default: 10)
         max_related: Maximum number of related results to return (default: 10)
-        output_format: Response format - "json" for slimmed JSON dict,
+        output_format: Response format - "json" for structured JSON dict,
             "text" for compact markdown text
         context: Optional FastMCP context for performance caching.
 
     Returns:
-        dict (output_format="json"): Slimmed JSON with redundant fields removed
+        dict (output_format="json"): Structured JSON with internal fields excluded
         str (output_format="text"): Compact markdown representation
 
     Examples:
@@ -292,4 +224,4 @@ async def build_context(
         if output_format == "text":
             return _format_context_markdown(graph, active_project.name)
 
-        return _slim_context(graph)
+        return graph.model_dump()

src/basic_memory/repository/observation_repository.py

@@ -2,9 +2,10 @@
 
 from typing import Dict, List, Sequence
 
-
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlalchemy.orm import selectinload
+from sqlalchemy.orm.interfaces import LoaderOption
 
 from basic_memory.models import Observation
 from basic_memory.repository.repository import Repository
@@ -22,6 +23,10 @@ def __init__(self, session_maker: async_sessionmaker, project_id: int):
         """
         super().__init__(session_maker, Observation, project_id=project_id)
 
+    def get_load_options(self) -> List[LoaderOption]:
+        """Eager-load parent entity to prevent N+1 if obs.entity is accessed."""
+        return [selectinload(Observation.entity)]
+
     async def find_by_entity(self, entity_id: int) -> Sequence[Observation]:
         """Find all observations for a specific entity."""
         query = select(Observation).filter(Observation.entity_id == entity_id)

src/basic_memory/schemas/memory.py

@@ -125,7 +125,7 @@ class EntitySummary(BaseModel):
 
     type: Literal["entity"] = "entity"
     external_id: str  # UUID for v2 API routing
-    entity_id: int  # Database ID for v2 API consistency
+    entity_id: Optional[int] = Field(None, exclude=True)  # Internal DB ID
     permalink: Optional[str]
     title: str
     content: Optional[str] = None
@@ -143,18 +143,18 @@ class RelationSummary(BaseModel):
     """Simplified relation representation."""
 
     type: Literal["relation"] = "relation"
-    relation_id: int  # Database ID for v2 API consistency
-    entity_id: Optional[int] = None  # ID of the entity this relation belongs to
+    relation_id: Optional[int] = Field(None, exclude=True)  # Internal DB ID
+    entity_id: Optional[int] = Field(None, exclude=True)  # Internal FK
     title: str
     file_path: str
     permalink: str
     relation_type: str
     from_entity: Optional[str] = None
-    from_entity_id: Optional[int] = None  # ID of source entity
-    from_entity_external_id: Optional[str] = None  # UUID of source entity for v2 API routing
+    from_entity_id: Optional[int] = Field(None, exclude=True)  # Internal FK
+    from_entity_external_id: Optional[str] = Field(None, exclude=True)  # Internal routing ID
     to_entity: Optional[str] = None
-    to_entity_id: Optional[int] = None  # ID of target entity
-    to_entity_external_id: Optional[str] = None  # UUID of target entity for v2 API routing
+    to_entity_id: Optional[int] = Field(None, exclude=True)  # Internal FK
+    to_entity_external_id: Optional[str] = Field(None, exclude=True)  # Internal routing ID
     created_at: Annotated[
         datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
     ]
@@ -168,21 +168,15 @@ class ObservationSummary(BaseModel):
     """Simplified observation representation."""
 
     type: Literal["observation"] = "observation"
-    observation_id: int  # Database ID for v2 API consistency
-    entity_id: Optional[int] = None  # ID of the entity this observation belongs to
-    entity_external_id: Optional[str] = None  # UUID of parent entity for v2 API routing
-    title: str
-    file_path: str
+    observation_id: Optional[int] = Field(None, exclude=True)  # Internal DB ID
+    entity_id: Optional[int] = Field(None, exclude=True)  # Internal FK
+    entity_external_id: Optional[str] = Field(None, exclude=True)  # Internal routing ID
+    title: Optional[str] = Field(None, exclude=True)  # Redundant with parent entity
+    file_path: Optional[str] = Field(None, exclude=True)  # Redundant with parent entity
     permalink: str
     category: str
     content: str
-    created_at: Annotated[
-        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
-    ]
-
-    @field_serializer("created_at")
-    def serialize_created_at(self, dt: datetime) -> str:
-        return dt.isoformat()
+    created_at: Optional[datetime] = Field(None, exclude=True)  # Redundant with parent entity
 
 
 class MemoryMetadata(BaseModel):
@@ -192,19 +186,13 @@ class MemoryMetadata(BaseModel):
     types: Optional[List[SearchItemType]] = None
     depth: int
     timeframe: Optional[str] = None
-    generated_at: Annotated[
-        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
-    ]
+    generated_at: Optional[datetime] = Field(None, exclude=True)  # Internal timing
     primary_count: Optional[int] = None  # Changed field name
     related_count: Optional[int] = None  # Changed field name
-    total_results: Optional[int] = None  # For backward compatibility
+    total_results: Optional[int] = Field(None, exclude=True)  # Internal counter
     total_relations: Optional[int] = None
     total_observations: Optional[int] = None
 
-    @field_serializer("generated_at")
-    def serialize_generated_at(self, dt: datetime) -> str:
-        return dt.isoformat()
-
 
 class ContextResult(BaseModel):
     """Context result containing a primary item with its observations and related items."""

tests/mcp/test_tool_build_context.py

@@ -9,7 +9,7 @@
 
 @pytest.mark.asyncio
 async def test_get_basic_discussion_context(client, test_graph, test_project):
-    """Test getting basic discussion context returns slimmed JSON dict."""
+    """Test getting basic discussion context returns JSON dict with excluded fields removed."""
     result = await build_context(project=test_project.name, url="memory://test/root")
 
     assert isinstance(result, dict)
@@ -19,7 +19,7 @@ async def test_get_basic_discussion_context(client, test_graph, test_project):
     assert primary["permalink"] == f"{test_project.name}/test/root"
     assert len(result["results"][0]["related_results"]) > 0
 
-    # Verify metadata — stripped fields should be absent
+    # Verify metadata — excluded fields should be absent
     meta = result["metadata"]
     assert meta["uri"] == f"{test_project.name}/test/root"
     assert meta["depth"] == 1  # default depth
@@ -28,16 +28,38 @@ async def test_get_basic_discussion_context(client, test_graph, test_project):
     assert "generated_at" not in meta
     assert "total_results" not in meta
 
-    # Verify entity-level stripped fields
+    # Entity: entity_id excluded, created_at kept (needed for related results)
     assert "entity_id" not in primary
-    assert "created_at" not in primary
+    assert "created_at" in primary
 
-    # Verify observation-level stripped fields
+    # Verify observation-level excluded fields
     if result["results"][0]["observations"]:
         obs = result["results"][0]["observations"][0]
         assert "observation_id" not in obs
         assert "entity_id" not in obs
         assert "file_path" not in obs
+        assert "title" not in obs
+        assert "created_at" not in obs
+        # Kept fields
+        assert "permalink" in obs
+        assert "category" in obs
+        assert "content" in obs
+
+    # Verify related_results item structure — entities have identifying fields
+    for related in result["results"][0]["related_results"]:
+        item_type = related["type"]
+        if item_type == "entity":
+            assert "title" in related
+            assert "file_path" in related
+            assert "created_at" in related
+            assert "entity_id" not in related  # excluded
+        elif item_type == "relation":
+            assert "relation_type" in related
+            assert "title" in related
+            assert "file_path" in related
+            assert "created_at" in related
+            assert "relation_id" not in related  # excluded
+            assert "entity_id" not in related  # excluded
 
 
 @pytest.mark.asyncio