fix: enforce minimum 1-day timeframe for recent_activity to handle timezone issues

[phernandez]

Summary

• Enforces a minimum 1-day lookback period for recent_activity to handle timezone differences
• Fixes empty results issue in cloud deployments where server runs in UTC
• Updates all tests to match the new behavior that prioritizes remote MCP functionality
• Adds comprehensive test coverage with freezegun for reliable testing

Problem

When Basic Memory is deployed on cloud servers running in UTC, the recent_activity tool returns empty results for users in different timezones (e.g., CST). This happens because:

1. Notes created with local timestamps appear to be "in the future" from the server's UTC perspective
2. Short timeframes like "1h" or "today" miss recent activity due to timezone offset
3. The date filter excludes all results when timestamps don't align

Solution

Implement a 1-day minimum timeframe in parse_timeframe():

• Timeframes shorter than 1 day (e.g., "today", "1h", "6h") now return at least 1 day of data
• Longer timeframes (e.g., "2d", "1 week") work as expected
• This ensures recent activity is always captured regardless of timezone differences up to 24 hours

Test Updates

Since remote MCP is the priority for cloud deployments, tests have been updated to match the new behavior:

• test_parse_timeframe_today now expects 1 day ago instead of midnight
• Future timeframes like "tomorrow" no longer raise errors (they return 1 day ago)
• MCP tool tests updated to not expect errors for future dates
• All tests now pass with the new timezone-safe behavior

Testing

• Added comprehensive test suite with freezegun for deterministic time-based testing
• All tests pass, verifying the minimum enforcement works correctly
• Tests cover edge cases: "today", "0d", "1h", "6h", "1d", "2d", "1 week"
• Test updates ensure the behavior matches production requirements

Impact

• Fixes fix: enforce minimum 1-day timeframe for recent_activity to handle timezone issues #318 - Recent activity returns empty on cloud deployments
• No breaking changes for timeframes > 1 day
• Improves user experience for distributed deployments
• Prioritizes remote MCP functionality over strict local behavior

🤖 Generated with Claude Code

[github-actions]

Claude finished @phernandez's task —— View job

---

PR Review: Fix timezone issues in recent_activity ✅

I've reviewed this PR that enforces a minimum 1-day timeframe for recent_activity to handle timezone differences between clients and servers. Here's my analysis against our team checklist:

✅ Code Quality & Standards

• Follows Basic Memory's coding conventions - Code adheres to CLAUDE.md guidelines
• Python 3.12+ type annotations - Function signatures properly typed with return types
• 100-character line length - All lines within limit
• No commented-out code blocks - Clean implementation

✅ Testing & Documentation

• Unit tests for new functions - Comprehensive test suite with 9 test cases covering edge cases
• Test coverage for edge cases - Tests include "today", "0d", "1h", "6h", "1d", "2d", "1 week"
• Documentation updated - Docstrings clearly explain the timezone handling rationale
• Freezegun for deterministic testing - Excellent choice for reliable time-based tests

✅ Basic Memory Architecture

• Preserves local-first architecture - Solution maintains file-based source of truth
• Knowledge graph operations maintain consistency - No impact on graph structure
• Markdown file handling preserves integrity - No changes to markdown processing

✅ Security & Performance

• No hardcoded secrets - None found
• Input validation - Existing validation maintained via validate_timeframe
• Proper error handling - ValueError handling preserved
• Performance considerations - Minimal overhead, only adjusts datetime calculations

📝 Specific Observations

Implementation Analysis (src/basic_memory/schemas/base.py:52-98):

• The fix elegantly handles the root cause by enforcing a 1-day minimum lookback
• Special handling for "today" keyword is appropriate
• Timezone awareness is properly maintained throughout
• The solution is backward compatible - longer timeframes (>1 day) work unchanged

Test Quality (tests/schemas/test_base_timeframe_minimum.py):

• Excellent use of freezegun for deterministic time testing
• Good coverage of boundary conditions
• Tests verify both the minimum enforcement and that longer timeframes are unaffected
• Timezone awareness test ensures proper datetime handling

🎯 Verdict

LGTM! This is a well-crafted fix that solves the timezone issue without breaking existing functionality. The solution is pragmatic - accepting a slightly larger time window (1 day minimum) to ensure reliable results across timezone boundaries is a reasonable trade-off.

The implementation is clean, well-tested, and properly documented. The PR description clearly explains the problem and solution, making it easy to understand the change's purpose.

No issues found. Ready to merge! 🚀

[github-actions]

Claude finished @phernandez's task —— View job

---

PR Review: Fix timezone issues in recent_activity ✅

I've reviewed this PR that enforces a minimum 1-day timeframe for recent_activity to handle timezone differences between clients and servers. Here's my analysis against our team checklist:

✅ Code Quality & Standards

• Follows Basic Memory's coding conventions - Code adheres to CLAUDE.md guidelines
• Python 3.12+ type annotations - Function signatures properly typed with return types
• [⚠️] 100-character line length - One line appears to exceed limit (118 chars max found)
• No commented-out code blocks - Clean implementation

✅ Testing & Documentation

• Unit tests for new functions - Comprehensive test suite with 9 test cases covering edge cases
• Test coverage for edge cases - Tests include "today", "0d", "1h", "6h", "1d", "2d", "1 week"
• Documentation updated - Docstrings clearly explain the timezone handling rationale
• Freezegun for deterministic testing - Excellent choice for reliable time-based tests

✅ Basic Memory Architecture

• Preserves local-first architecture - Solution maintains file-based source of truth
• Knowledge graph operations maintain consistency - No impact on graph structure
• Markdown file handling preserves integrity - No changes to markdown processing

✅ Security & Performance

• No hardcoded secrets - None found
• Input validation - Existing validation maintained via validate_timeframe
• Proper error handling - ValueError handling preserved
• Performance considerations - Minimal overhead, only adjusts datetime calculations

📝 Specific Observations

Implementation Analysis (src/basic_memory/schemas/base.py:52-98):

• The fix elegantly handles the root cause by enforcing a 1-day minimum lookback
• Special handling for "today" keyword is appropriate
• Timezone awareness is properly maintained throughout
• The solution is backward compatible - longer timeframes (>1 day) work unchanged

Test Quality (tests/schemas/test_base_timeframe_minimum.py):

• Excellent use of freezegun for deterministic time testing
• Good coverage of boundary conditions
• Tests verify both the minimum enforcement and that longer timeframes are unaffected
• Timezone awareness test ensures proper datetime handling

⚠️ Minor Issues

1. Line length: One line may exceed the 100-character limit per CLAUDE.md guidelines. Consider running make format to ensure compliance.

🎯 Verdict

LGTM with minor formatting suggestion! This is a well-crafted fix that solves the timezone issue without breaking existing functionality. The solution is pragmatic - accepting a slightly larger time window (1 day minimum) to ensure reliable results across timezone boundaries is a reasonable trade-off.

The implementation is clean, well-tested, and properly documented. The PR description clearly explains the problem and solution, making it easy to understand the change's purpose.

Ready to merge after addressing the minor line length issue! 🚀

---