Implement MCP schema contracts and serializers

[Atharva-Kanherkar]

Summary

• add a shared mcp_server contract layer with typed request/response models, typed MCP error payloads, bounded forgetting and contradiction responses, and get_memory(memory_type, record_id) routing
• refactor the FastAPI serializer helpers to reuse the shared MCP serializers so the future FastMCP transport consumes the same record/result/report contract
• align the semantic write endpoint and forgetting lock path with the shared contract models, and tighten the remaining request/serializer typing and validation
• update the web API types to match the locked flat-union/null response shape

Breaking API shape changes

• record payloads are now emitted through the shared flat-union MemoryRecordModel, so non-applicable fields are present as null instead of being omitted entirely
• semantic write responses now include bounded contradiction metadata: contradiction_check, contradiction_check_order, total_contradictions, and contradictions_truncated
• forgetting preview/run responses now include displayed_decisions, total_decisions, and decisions_truncated, and the already_running branch is shaped through the same model
• superseded_by is now exposed for semantic records through the shared serializer

Frontend impact

• checked the current playground rendering path; it gates procedural rendering on truthy record.steps, so the new null fields do not break that UI path
• updated web/src/lib/api.ts to reflect the new nullability and contradiction/forgetting metadata fields explicitly

Testing

• ./.venv/bin/python -m pytest -q tests/test_mcp_schemas.py
• timeout 30s ./.venv/bin/python -m pytest -q tests/test_api_runtime_edges.py
• timeout 30s ./.venv/bin/python -m pytest -q tests/test_forgetting_integration.py -k semantic_store_returns_potential_contradictions
• ./.venv/bin/python -m pytest -q tests/test_api.py -k "best_procedures_endpoint_returns_ranked_results or store_semantic_and_query_mixed_results"

Closes #60

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentic-memory	Ready	Preview, Comment	Mar 29, 2026 10:26pm