[BUG] build_context fails schema validation in MCP client (missing fields / date-time format)

[se1961]

Bug Description

Calling basic-memory.build_context with a valid memory://… URI fails schema validation in an MCP client. Other endpoints (search_notes, read_note) work as expected.

Steps To Reproduce

1. Resolve a note:

   • Title: Techniques Elsa Can't Use
   • URI returned by search_notes: memory://conversations/20250429-Techniques_Elsa_Cant_Use

2. Call:

   {"url":"memory://conversations/20250429-Techniques_Elsa_Cant_Use"}

via basic-memory.build_context

Expected Behavior

Response conforms to the tool’s declared output schema; client can render context.

Actual Behavior

Client error:

MCP error -32602: Structured content does not match the tool's output schema:
data.results[0].primary_result.created_at should match format "date-time",
data.results[0].primary_result should have required property 'relation_type',
data.results[0].primary_result should have required property 'category',
data.results[0].primary_result should match some schema in anyOf

Environment

• Basic Memory: v0.14.3 (installed via uv)
• Server command: uv tool run basic-memory mcp
• OS/CPU: macOS (Apple Silicon)
• MCP client: ChatWise (stdio; tools auto-run)
• Project path: /Users/shelley/basic-memory
• Fresh DB after basic-memory reset; ~84 notes indexed

Additional Context

• Reproduces consistently after reset and full app restart.

• search_notes and read_note succeed for the same memory:// target.

• Same behavior across different models (provider kept constant per thread).

Client config (for completeness)

{
"mcpServers": {
"basic-memory": {
"command": "uv",
"args": ["tool", "run", "basic-memory", "mcp"],
"transport": "stdio"
}
}
}

Workaround

Temporarily avoid build_context and emulate context with search_notes → read_note → related notes (1–2).

[phernandez]

@claude can you investigate this?

[claude]

Claude finished @phernandez's task —— View job • claude/issue-263-20250821-2347 • Create PR ➔

---

✅ Fixed build_context schema validation issue

Tasks

• Set up development environment
• Locate and examine build_context tool implementation
• Compare declared schema with actual output
• Fix schema validation issues
• Test the fix
• Commit and push changes

Analysis

The issue was that the MCP tool's GraphContext schema contained union types (EntitySummary | RelationSummary | ObservationSummary) with different required fields:

• EntitySummary: Missing relation_type and category
• RelationSummary: Has relation_type but missing category
• ObservationSummary: Has category but missing relation_type

When MCP clients validated the schema, they expected all union members to have the same required fields, causing validation failures.

Fix Applied

I updated the schema to use Pydantic's discriminated unions:

1. Changed type literals: type: str = "entity" → type: Literal["entity"] = "entity"
2. Added discriminator fields: Used Annotated[Union[...], Field(discriminator="type")]
3. Proper schema generation: This generates correct anyOf/oneOf schemas that MCP clients can validate

The fix ensures each union variant is properly distinguished by its type field, allowing MCP clients to validate the correct schema for each object type.

Changes

• src/basic_memory/schemas/memory.py - Updated union handling for EntitySummary, RelationSummary, ObservationSummary

---

[se1961]

Update: Retested on git@main via:
uvx --from "git+https://github.com/basicmachines-co/basic-memory@main" basic-memory mcp

In ChatWise (macOS), after deleting/re-adding the MCP entry and restarting,
build_context still fails schema validation. First-line error indicates
issues with created_at (date-time) and a …type field.

Other endpoints (search_notes, read_note) continue to work.

Client: ChatWise (stdio; tools auto-run)
Server path: git@main (still prints 0.14.3)
Project: /Users/shelley/basic-memory

Happy to provide the tool card screenshot / log snippet.

[jope-bm]

@claude Take a look at @se1961 's comment and see if you can find the root cause.

[claude]

Claude finished @jope-bm's task —— View job • claude/issue-263-20250822-1824 • Create PR ➔

---

✅ Fixed MCP schema validation issue for build_context

Tasks

• Set up development environment
• Examine current build_context implementation and schema
• Run tool locally to identify actual vs declared schema mismatch
• Fix schema validation issues (date-time format, missing type field)
• Test the fix
• Run linting and type checking
• Commit and push changes

Root Cause Found

The issue was with datetime serialization in the Pydantic models. MCP clients expect datetime fields to be serialized as ISO format strings to match the JSON schema "date-time" format, but the models weren't properly configured for this.

The original discriminated unions fix addressed the union type validation but didn't solve the datetime serialization problem.

Fix Applied

Added model_config = ConfigDict(json_encoders={datetime: lambda dt: dt.isoformat()}) to all models with datetime fields:

• EntitySummary - for entity created_at fields
• RelationSummary - for relation created_at fields
• ObservationSummary - for observation created_at fields
• MemoryMetadata - for generated_at field

This ensures datetime fields are serialized as ISO format strings (e.g. "2025-08-22T18:28:13") instead of Python datetime objects, which should resolve the MCP client validation errors.

Changes Made

Updated src/basic_memory/schemas/memory.py to add proper datetime JSON encoding configuration to all affected Pydantic models.