feat: use datetime ranges for archival memory query (#4398)

Author: sarahwooders

letta/server/rest_api/routers/v1/agents.py

@@ -993,8 +993,8 @@ async def search_archival_memory(
         "any", description="How to match tags - 'any' to match passages with any of the tags, 'all' to match only passages with all tags"
     ),
     top_k: Optional[int] = Query(None, description="Maximum number of results to return. Uses system default if not specified"),
-    start_datetime: Optional[str] = Query(None, description="Filter results to passages created after this datetime. ISO 8601 format"),
-    end_datetime: Optional[str] = Query(None, description="Filter results to passages created before this datetime. ISO 8601 format"),
+    start_datetime: Optional[datetime] = Query(None, description="Filter results to passages created after this datetime"),
+    end_datetime: Optional[datetime] = Query(None, description="Filter results to passages created before this datetime"),
     server: "SyncServer" = Depends(get_letta_server),
     actor_id: str | None = Header(None, alias="user_id"),
 ):
@@ -1008,6 +1008,10 @@ async def search_archival_memory(
     actor = await server.user_manager.get_actor_or_default_async(actor_id=actor_id)
 
     try:
+        # convert datetime to string in ISO 8601 format
+        start_datetime = start_datetime.isoformat() if start_datetime else None
+        end_datetime = end_datetime.isoformat() if end_datetime else None
+
         # Use the shared agent manager method
         formatted_results, count = await server.agent_manager.search_agent_archival_memory_async(
             agent_id=agent_id,

pyproject.toml

@@ -45,7 +45,7 @@ dependencies = [
     "llama-index>=0.12.2",
     "llama-index-embeddings-openai>=0.3.1",
     "anthropic>=0.49.0",
-    "letta_client>=0.1.301",
+    "letta-client==0.1.307",
     "openai>=1.99.9",
     "opentelemetry-api==1.30.0",
     "opentelemetry-sdk==1.30.0",

tests/test_sdk_client.py

@@ -558,6 +558,48 @@ def test_insert_archival_memory(client: LettaSDKClient, agent: AgentState):
     assert "This is a test passage" not in passage_texts, f"Memory was not deleted: {passage_texts}"
 
 
+def test_search_archival_memory(client: LettaSDKClient, agent: AgentState):
+    from datetime import datetime, timezone
+
+    client.agents.passages.create(
+        agent_id=agent.id,
+        text="This is a test passage",
+    )
+    client.agents.passages.create(
+        agent_id=agent.id,
+        text="This is another test passage",
+    )
+    client.agents.passages.create(agent_id=agent.id, text="cats")
+    # insert old passage: 09/03/2001
+    old_passage = "OLD PASSAGE"
+    client.agents.passages.create(
+        agent_id=agent.id,
+        text=old_passage,
+        created_at=datetime(2001, 9, 3, 0, 0, 0, 0, timezone.utc),
+    )
+
+    # test seaching for old passage
+    search_results = client.agents.passages.search(agent_id=agent.id, query="cats", top_k=1)
+    assert len(search_results.results) == 1
+    assert search_results.results[0].content == "cats"
+
+    # test seaching for old passage
+    search_results = client.agents.passages.search(agent_id=agent.id, query="cats", top_k=4)
+    assert len(search_results.results) == 4
+    assert search_results.results[0].content == "cats"
+
+    # search for old passage
+    search_results = client.agents.passages.search(
+        agent_id=agent.id,
+        query="cats",
+        top_k=4,
+        start_datetime=datetime(2001, 8, 3, 0, 0, 0, 0, timezone.utc),
+        end_datetime=datetime(2001, 10, 3, 0, 0, 0, 0, timezone.utc),
+    )
+    assert len(search_results.results) == 1
+    assert search_results.results[0].content == old_passage
+
+
 def test_function_return_limit(disable_e2b_api_key, client: LettaSDKClient, agent: AgentState):
     """Test to see if the function return limit works"""