fix(redis): coerce list fields in Redis aggregate path; add RecencyAggregationQuery.build_args helper; update tests to use build_args; whitespace fix

Author: abrookins

CLAUDE.md

@@ -5,42 +5,68 @@ This project uses Redis 8, which is the redis:8 docker image.
 Do not use Redis Stack or other earlier versions of Redis.
 
 ## Frequently Used Commands
-Get started in a new environment by installing `uv`:
-```bash
-pip install uv
-```
 
+### Project Setup
+Get started in a new environment by installing `uv`:
 ```bash
-# Development workflow
+pip install uv               # Install uv (once)
 uv venv                      # Create a virtualenv (once)
-source .venv/bin/activate    # Activate the virtualenv (start of terminal session)
 uv install --all-extras      # Install dependencies
 uv sync --all-extras         # Sync latest dependencies
+```
+
+### Activate the virtual environment
+You MUST always activate the virtualenv before running commands:
+
+```bash
+source .venv/bin/activate
+```
+
+### Running Tests
+Always run tests before committing. You MUST have 100% of the tests in the
+code basepassing to commit.
+
+Run all tests like this, including tests that require API keys in the
+environment:
+```bash
+uv run pytest --run-api-tests
+```
+
+### Linting
+
+```bash
 uv run ruff check            # Run linting
 uv run ruff format           # Format code
-uv run pytest --run-api-tests # Run all tests
+
+### Managing Dependencies
 uv add <dependency>          # Add a dependency to pyproject.toml and update lock file
 uv remove <dependency>       # Remove a dependency from pyproject.toml and update lock file
 
+### Running Servers
 # Server commands
 uv run agent-memory api      # Start REST API server (default port 8000)
 uv run agent-memory mcp      # Start MCP server (stdio mode)
 uv run agent-memory mcp --mode sse --port 9000  # Start MCP server (SSE mode)
 
+### Database Operations
 # Database/Redis operations
 uv run agent-memory rebuild-index     # Rebuild Redis search index
 uv run agent-memory migrate-memories  # Run memory migrations
 
+### Background Tasks
 # Background task management
 uv run agent-memory task-worker       # Start background task worker
+# Schedule a specific task
 uv run agent-memory schedule-task "agent_memory_server.long_term_memory.compact_long_term_memories"
 
+### Running All Containers
 # Docker development
 docker-compose up            # Start full stack (API, MCP, Redis)
 docker-compose up redis      # Start only Redis Stack
 docker-compose down          # Stop all services
 ```
 
+### Committing Changes
 IMPORTANT: This project uses `pre-commit`. You should run `pre-commit`
 before committing:
 ```bash

agent_memory_server/utils/redis_query.py

@@ -43,7 +43,10 @@ def from_vector_query(
         *,
         filter_expression: Any | None = None,
     ) -> RecencyAggregationQuery:
-        return cls(vq.query, filter_expression=filter_expression)
+        agg = cls(vq.query)
+        if filter_expression is not None:
+            agg.filter(filter_expression)
+        return agg
 
     def load_default_fields(self) -> RecencyAggregationQuery:
         self.load(self.DEFAULT_RETURN_FIELDS)
@@ -60,15 +63,13 @@ def apply_recency(
         hl_la = float(params.get("half_life_last_access_days", 7.0))
         hl_cr = float(params.get("half_life_created_days", 30.0))
 
-        self.apply(
-            f"max(0, ({now_ts} - @last_accessed)/86400.0)", AS="days_since_access"
-        ).apply(
-            f"max(0, ({now_ts} - @created_at)/86400.0)", AS="days_since_created"
-        ).apply(f"pow(2, -@days_since_access/{hl_la})", AS="freshness").apply(
-            f"pow(2, -@days_since_created/{hl_cr})", AS="novelty"
-        ).apply(f"{wf}*@freshness+{wa}*@novelty", AS="recency").apply(
-            "1-(@__vector_score/2)", AS="sim"
-        ).apply(f"{w_sem}*@sim+{w_rec}*@recency", AS="boosted_score")
+        self.apply(days_since_access=f"max(0, ({now_ts} - @last_accessed)/86400.0)")
+        self.apply(days_since_created=f"max(0, ({now_ts} - @created_at)/86400.0)")
+        self.apply(freshness=f"pow(2, -@days_since_access/{hl_la})")
+        self.apply(novelty=f"pow(2, -@days_since_created/{hl_cr})")
+        self.apply(recency=f"{wf}*@freshness+{wa}*@novelty")
+        self.apply(sim="1-(@__vector_score/2)")
+        self.apply(boosted_score=f"{w_sem}*@sim+{w_rec}*@recency")
 
         return self
 
@@ -79,3 +80,7 @@ def sort_by_boosted_desc(self) -> RecencyAggregationQuery:
     def paginate(self, offset: int, limit: int) -> RecencyAggregationQuery:
         self.limit(offset, limit)
         return self
+
+    # Compatibility helper for tests that inspect the built query
+    def build_args(self) -> list:
+        return super().build_args()

agent_memory_server/vectorstore_adapter.py

@@ -376,13 +376,13 @@ def parse_datetime(dt_val: str | float | None) -> datetime | None:
             updated_at=updated_at,
             pinned=pinned_bool,
             access_count=access_count_val,
-            topics=metadata.get("topics"),
-            entities=metadata.get("entities"),
+            topics=self._parse_list_field(metadata.get("topics")),
+            entities=self._parse_list_field(metadata.get("entities")),
             memory_hash=metadata.get("memory_hash"),
             discrete_memory_extracted=metadata.get("discrete_memory_extracted", "f"),
             memory_type=metadata.get("memory_type", "message"),
             persisted_at=persisted_at,
-            extracted_from=metadata.get("extracted_from"),
+            extracted_from=self._parse_list_field(metadata.get("extracted_from")),
             event_date=event_date,
             dist=score,
         )
@@ -898,14 +898,14 @@ async def search_memories(
                             vector_field_name="vector",
                             filter_expression=redis_filter,
                             distance_threshold=float(distance_threshold),
-                            k=limit,
+                            num_results=limit,
                         )
                     else:
                         knn = VectorQuery(
                             vector=embedding_vector,
                             vector_field_name="vector",
                             filter_expression=redis_filter,
-                            k=limit,
+                            num_results=limit,
                         )
 
                     # Aggregate with APPLY/SORTBY boosted score via helper

tests/test_recency_aggregation.py

@@ -12,7 +12,7 @@ async def test_recency_aggregation_query_builds_and_paginates():
     from redisvl.query import VectorQuery
 
     dummy_vec = [0.0, 0.0, 0.0]
-    vq = VectorQuery(vector=dummy_vec, vector_field_name="vector", k=10)
+    vq = VectorQuery(vector=dummy_vec, vector_field_name="vector", num_results=10)
 
     # Build aggregation
     agg = (
@@ -33,13 +33,13 @@ async def test_recency_aggregation_query_builds_and_paginates():
         .paginate(5, 7)
     )
 
-    # Implementation detail: AggregationQuery has a private builder we can sanity-check
-    # We only assert key substrings to avoid coupling to exact formatting
-    qs = agg._build_query_string()  # type: ignore[attr-defined]
-    assert "APPLY" in qs
-    assert "boosted_score" in qs
-    assert "SORTBY" in qs
-    assert "LIMIT" in qs
+    # Validate the aggregate request contains APPLY, SORTBY, and LIMIT via build_args
+    args = agg.build_args()
+    args_str = " ".join(map(str, args))
+    assert "APPLY" in args_str
+    assert "boosted_score" in args_str
+    assert "SORTBY" in args_str
+    assert "LIMIT" in args_str
 
 
 @pytest.mark.asyncio
@@ -82,6 +82,10 @@ def __init__(self, rows):
 
     mock_vectorstore = MagicMock()
     mock_vectorstore._index = mock_index
+    # If the adapter falls back, ensure awaited LC call is defined
+    mock_vectorstore.asimilarity_search_with_relevance_scores = AsyncMock(
+        return_value=[]
+    )
 
     # Mock embeddings
     mock_embeddings = MagicMock()