feat(integrations): Add LangGraph Adapter for MemU (Track A)

[david-mamani]

Hackathon Submission: Track A - Agent Framework Plugins (#2026NewYearChallenge)

Executive Summary

This Pull Request introduces a production-grade integration between MemU and LangGraph, fulfilling the requirements for Track A. It provides a standardized interface for LangGraph agents to interact with MemU's persistent memory layer without requiring direct service instantiation within the agent loop. Additionally, this PR addresses architectural complexity in the example implementations and introduces a robust testing suite using mock strategies.

Technical Summary of Changes

1. Adapter Pattern Implementation (src/memu/integrations/langgraph.py)

• Design Pattern: Implemented the Adapter Pattern via the MemULangGraphTools class. This adapts the internal MemoryService interface into LangChain-compatible StructuredTool objects, aligning with the target framework's conventions.
• Type Safety: Leveraged Pydantic models (SaveRecallInput and SearchRecallInput) to strictly define the schema for tool arguments. This ensures that the LLM's structured output is validated against a rigorous type contract.
• Closures for Async Execution: Utilized inner async functions wrapped by StructuredTool.from_function to bridge the synchronous tool definition API with MemU's asynchronous core.

2. Cyclomatic Complexity Refactoring (examples/langgraph_demo.py)

• Decomposition: The monolithic run_demo function was decomposed into single-responsibility units (initialize_infrastructure, process_conversation, process_retrieval), ensuring C901 compliance.
• Orchestration: Reduced run_demo to a high-level orchestrator, significantly improving readability and maintainability.

3. Isolated Integration Testing (tests/integrations/test_langgraph.py)

• Mocking Strategy: Employed unittest.mock.AsyncMock to mock asynchronous methods of MemoryService. This allows strict verification of integration logic without requiring a running database.
• Behavioral Verification: Tests assert both the outcome (tool return strings) and the interaction (validating specific call arguments).

4. Resilient Error Handling (src/memu/integrations/langgraph.py)

• Graceful Failure Recovery: Wrapped core interactions within try/except blocks. Tools return descriptive error strings instead of raising exceptions, allowing the Agent to self-correct and improving stability.
• Resource Management: Implemented strict finally clauses to ensure temporary files are deleted, preventing storage leaks.

5. Dependency Management & Usability

• Explicit Resolution: Managed dependencies (langgraph, langchain-openai) via uv for reproducible builds.
• User-Centric Feedback: The demo entry point includes conditional imports with error messages providing the exact uv sync command needed, directly addressing usability criteria.

---

🛠️ How to Verify (Usability & Testing)

To validate this submission locally as per the "Runnable outcome" requirement:

1. Install Dependencies:
   uv sync --all-extras

2. Run the integration tests:
   uv run pytest tests/integrations/test_langgraph.py -v

3. Run the Demo
   Requires OPENAI_API_KEY env var
   uv run python examples/langgraph_demo.py

[ankaisen]

@david-mamani Thank you! LGTM 👍