feat: implement SPEC-11 API performance optimizations

[phernandez]

Summary

Implements comprehensive performance optimizations for MCP tool response times, addressing GitHub issue #82.

🎯 Performance Gains Achieved

• 95-99% improvement in read operations (350ms-2.6s → 20ms)
• 75-92% improvement in edit operations (350ms-2.6s → 218ms)
• Zero overhead for project switching
• Database connection overhead eliminated (0ms vs 50-100ms)

🔧 Key Changes

• Cache database connections in app.state during API lifespan
• Update dependency injection to use cached connections
• Remove project reconciliation from API startup
• Add skip_initialization_sync configuration option

✅ Validation

• Live testing performed with comprehensive MCP tool validation
• All Tier 1 tools performing under 500ms target
• Backwards compatibility maintained - no breaking changes
• Integration tests passing - type checking and linting clear

📋 Technical Details

• Modified FastAPI lifespan to cache engine/session_maker in app.state
• Updated get_engine_factory() to use cached connections instead of get_or_create_db()
• Preserved CLI fallback for non-API contexts
• Added performance configuration flag for cloud deployments

🚀 Impact

This optimization directly addresses basic-memory-cloud issue #82 and will significantly improve performance for all cloud tenants and local usage.

Resolves: #82 (Basic Memory API Performance Optimization)
Implements: SPEC-11 API Performance Optimization

Test plan

• Live testing with real MCP tools completed
• Performance benchmarks validated (95-99% improvement)
• Integration tests passing
• Type checking and linting clear
• Backwards compatibility verified

🤖 Generated with Claude Code

[github-actions]

Claude finished @phernandez's task —— View job

---

Code Review for PR #315: SPEC-11 API Performance Optimization

I've completed my review of this PR implementing comprehensive performance optimizations for MCP tool response times. Here's my assessment against the Basic Memory team checklist:

✅ Code Quality & Standards

• Follows Basic Memory's coding conventions in CLAUDE.md - Code adheres to project conventions
• Python 3.12+ type annotations and async patterns - Proper async/await usage throughout
• SQLAlchemy 2.0 best practices - Correctly uses async_sessionmaker and AsyncEngine
• FastAPI and Typer conventions followed - FastAPI lifespan context manager properly implemented
• 100-character line length limit maintained - All changes respect line limits
• No commented-out code blocks - Clean implementation

✅ Testing & Documentation

• Unit tests for new functions/methods - Tests updated for chatgpt_tools changes
• Integration tests for new MCP tools - Integration tests modified to match new structure
• Test coverage for edge cases - Error cases handled in chatgpt_tools
• Documentation updated - Comprehensive SPEC-11 document added with performance metrics
• CLAUDE.md updated if conventions change - No convention changes requiring updates

✅ Basic Memory Architecture

• MCP tools follow atomic, composable design - ChatGPT tools properly wrap existing tools
• Database changes include Alembic migrations - No schema changes, only connection handling
• Preserves local-first architecture principles - CLI fallback preserved in deps.py:96-100
• Knowledge graph operations maintain consistency - No changes to graph operations
• Markdown file handling preserves integrity - File operations unchanged
• AI-human collaboration patterns followed - Implementation follows established patterns

✅ Security & Performance

• No hardcoded secrets or credentials - No security issues found
• Input validation for MCP tools - Existing validation preserved
• Proper error handling and logging - Error handling in chatgpt_tools with appropriate logging
• Performance considerations addressed - 95-99% improvement achieved per SPEC-11
• No sensitive data in logs or commits - Logging is appropriate

🎯 Key Observations

Strengths:

1. Exceptional performance gains - 95-99% improvement in read operations, 75-92% in edits
2. Backwards compatibility - CLI fallback mechanism preserves existing functionality (deps.py:96-100)
3. Clean implementation - Database connections cached in app.state during lifespan
4. Comprehensive documentation - SPEC-11 provides detailed rationale and validation metrics
5. Proper error handling - ChatGPT tools handle edge cases gracefully

Minor Suggestions:

1. Consider adding a comment in app.py:36-41 explaining why project reconciliation was removed (performance optimization per SPEC-11)
2. The skip_initialization_sync config flag in config.py:96-99 could benefit from a reference to SPEC-11 in its docstring

Performance Validation:
The PR achieves its stated goals with measured improvements:

• Read operations: 350ms-2.6s → 20ms (95-99% faster)
• Edit operations: 350ms-2.6s → 218ms (75-92% faster)
• Database connection overhead eliminated
• All Tier 1 tools now perform under 500ms target

✅ Verdict

This PR successfully implements critical performance optimizations that will significantly improve the user experience for both cloud and local deployments. The implementation is clean, well-documented, and maintains full backwards compatibility. The performance gains exceed the original targets, making this a valuable contribution to the codebase.

Recommendation: Ready to merge after considering the minor documentation suggestions above.

---

✅ All review tasks completed successfully.