fix: rework lifecycle management to optimize cloud deployment

[phernandez]

Summary

This PR reworks the lifecycle management architecture to solve critical cloud deployment performance issues while maintaining proper initialization for different deployment modes.

Problems Solved

1. MCP Recycling Overhead in Cloud

Issue: In cloud deployments, MCP gets recycled for every request, causing the app_lifespan to run repeatedly

• initialize_app() running on every request
• File sync setup happening repeatedly
• Migration checks on every request
• Massive performance overhead

Solution: Removed all lifecycle complexity from MCP server

• MCP server is now just a plain FastMCP instance
• No per-request initialization overhead
• Much faster response times in cloud proxy scenarios

2. FastAPI Not Loading Projects

Issue: FastAPI app wasn't properly calling initialize_app()

• Projects from config weren't being loaded
• Missing database initialization for web context
• Broken project reconciliation

Solution: FastAPI explicitly handles full lifecycle

• Added initialize_app(app_config) call in FastAPI lifespan
• Proper project loading when running as web API
• Database and project setup happens once on startup

Architecture Changes

MCP CLI Command (mcp.py)

• Now handles initialization before starting MCP
• Calls initialize_file_sync() to set up file watching
• Starts sync in background thread, then runs clean MCP server

MCP Server (server.py)

• Significantly simplified - removed app_lifespan completely
• No background task management
• Just a pure FastMCP instance

FastAPI App (app.py)

• Enhanced lifecycle management for web API mode
• Explicit initialize_app() call ensures project loading
• Clear separation: lifecycle only runs when needed

Deployment Mode Optimization

MCP CLI Mode:

• Initialize once → Run lightweight MCP server
• No per-request overhead

FastAPI Mode:

• Full lifecycle management with project loading
• Proper database and project setup

Cloud Proxy Mode:

• FastAPI handles initialization
• MCP requests are now lightweight and fast

Performance Impact

• Before: Every MCP request triggered full initialization cycle
• After: MCP requests have minimal overhead
• Cloud performance: Should see significant improvement in response times
• Resource usage: Reduced CPU and memory overhead per request

Testing

• Verified MCP CLI mode still works correctly
• Confirmed FastAPI mode properly loads projects
• Architecture supports both local and cloud deployments

This change should resolve the cloud performance issues identified in recent deployments.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[github-actions]

Claude finished @phernandez's task —— View job

---

PR Review: Lifecycle Management Optimization

I've completed my review of this PR against our Basic Memory team checklist. This is a well-architected refactoring that successfully addresses the cloud deployment performance issues while maintaining proper initialization for different deployment modes.

Review Checklist Results

✅ Code Quality & Standards

• Follows Basic Memory's coding conventions in CLAUDE.md
• Python 3.12+ type annotations and async patterns maintained
• SQLAlchemy 2.0 best practices (using existing patterns)
• FastAPI and Typer conventions followed
• 100-character line length limit maintained
• No commented-out code blocks

⚠️ Testing & Documentation

• Unit tests for new functions/methods - No tests added for lifecycle changes
• Integration tests for new MCP tools - N/A (no new tools)
• Test coverage for edge cases - Missing tests for new initialization flow
• Documentation updated (docstring in app.py:30)
• CLAUDE.md updated if conventions change - N/A (no convention changes)

✅ Basic Memory Architecture

• MCP tools follow atomic, composable design - Excellent simplification
• Database changes include Alembic migrations - N/A (no schema changes)
• Preserves local-first architecture principles
• Knowledge graph operations maintain consistency
• Markdown file handling preserves integrity
• AI-human collaboration patterns followed

✅ Security & Performance

• No hardcoded secrets or credentials
• Input validation for MCP tools - N/A (no new tools)
• Proper error handling and logging maintained
• Performance considerations addressed - Major performance win
• No sensitive data in logs or commits

Detailed Analysis

Strengths

1. Clean Architectural Separation - The removal of app_lifespan from the MCP server (server.py) creates a much cleaner separation of concerns. The MCP server is now just a plain FastMCP instance, which is exactly what it should be.

2. Performance Optimization - The cloud deployment issue is elegantly solved by removing per-request initialization overhead. This should dramatically improve response times in cloud proxy scenarios.

3. Proper Lifecycle Management - FastAPI now explicitly calls initialize_app(app_config) in its lifespan context (app.py:35), ensuring projects are loaded correctly when running as a web API.

4. Thread-Based Sync - The MCP CLI command (mcp.py) properly handles file sync in a background thread with its own event loop, preventing blocking issues.

Areas for Improvement

1. Missing Test Coverage - The PR lacks tests for:

   • FastAPI lifespan with initialize_app call
   • MCP CLI thread-based file sync behavior
   • Verification that MCP server no longer has lifecycle overhead

   Consider adding tests like:

   # Test FastAPI initialization
   async def test_fastapi_lifespan_initializes_app():
       # Verify initialize_app is called with correct config
       
   # Test MCP server has no lifecycle
   def test_mcp_server_no_lifespan():
       assert not hasattr(mcp, 'lifespan')

2. Error Handling in Thread - The file sync thread in mcp.py catches exceptions but only logs them. Consider if there should be any recovery mechanism or status reporting.

3. Documentation - While the docstring was updated, consider adding a comment in server.py explaining why there's no lifespan (for future maintainers).

Code-Specific Comments

src/basic_memory/api/app.py:30

"""Lifecycle manager for the FastAPI app. Not called in stdio mcp mode"""

Good clarification, but consider expanding to explain when it IS called.

src/basic_memory/cli/commands/mcp.py:56-66
The thread-based sync implementation is clean, but consider:

• Adding a mechanism to check if the sync thread is still alive
• Potentially exposing sync status via the MCP server

src/basic_memory/mcp/server.py
The simplification here is excellent - from 40 lines to 10 lines while improving performance.

Summary

This is a high-quality PR that solves real performance issues with a clean architectural approach. The code changes are minimal but impactful, following the principle of "make it simpler to make it better."

Recommended Actions:

1. Add tests for the new lifecycle behavior before merging
2. Consider adding brief inline comments explaining the architectural decisions
3. Monitor cloud deployment metrics after deployment to validate performance improvements

The PR achieves its stated goals effectively and should provide significant performance benefits in cloud deployments. With test coverage added, this is ready to merge.

---

✅ Review completed successfully