fix(falkordb): respect reference_time in retrieve_episodes

[pcy06]

Summary

Fixes FalkorDB episode retrieval so retrieve_episodes(reference_time=...) does not return episodes whose valid_at is after the requested reference time.

The FalkorDB query now projects e.valid_at <= $reference_time into a boolean with WITH and filters on that value. This avoids a FalkorDB direct WHERE e.valid_at <= $reference_time path that can return rows even when the same predicate projects as False.

Type of Change

• Bug fix
• New feature
• Performance improvement
• Documentation/Tests

Objective

This is a bug fix for the FalkorDB driver. Point-in-time episode retrieval is documented to return only episodes at or before reference_time; future episodes leaking into the result can affect the context Graphiti uses for subsequent episode ingestion.

The change is intentionally limited to FalkorEpisodeNodeOperations.retrieve_episodes and the corresponding driver tests.

Testing

• Unit tests added/updated
• Integration tests added/updated
• All existing tests pass

Commands run:

uv run pytest tests/driver/test_falkordb_driver.py -q
DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1 uv run pytest tests/driver/test_falkordb_driver.py -q -m 'not integration'
make lint

Breaking Changes

• No breaking changes

If this is a breaking change, describe:

• Not applicable

Checklist

• Code follows project style guidelines (make lint passes)
• Self-review completed
• Documentation updated where necessary - no docs change needed for this bug fix
• No secrets or sensitive information committed

Related Issues

Closes #1625

[zep-cla-assistant]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[pcy06]

I have read the CLA Document and I hereby sign the CLA behalf on myself, e-mail: pcy06@kakao.com

[pcy06]

recheck

[Naseem77]

@pcy06 Good catch on reference_time! The legacy retrieve_episodes path in utils/maintenance has the same bug and isn't covered. Patching that too would make this complete.