fix: recent_activity dedup + pagination across MCP tools

A user reported that recent_activity returns only 1 distinct note even
though 9 were modified. Root cause: the API defaults to returning ALL
types (entity, observation, relation), so a single well-connected entity
fills the entire page with its observations and relations.

Changes:
- 🎯 Default to entity-only in recent_activity MCP tool when no type specified
- 📄 Expose page/page_size params on recent_activity (were hardcoded)
- ✅ Add has_more field to GraphContext and SearchResponse (N+1 trick)
- 📝 Show pagination guidance ("Use page=2 to see more") in text output

The API layer stays unchanged — it still accepts all types. This is
purely an MCP tool UX default so LLMs see distinct notes by default.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/api/v2/routers/search_router.py

@@ -47,21 +47,28 @@ async def search(
     Returns:
         SearchResponse with paginated search results
     """
-    limit = page_size
     offset = (page - 1) * page_size
+    # Fetch one extra item to detect whether more pages exist (N+1 trick)
+    fetch_limit = page_size + 1
     try:
-        results = await search_service.search(query, limit=limit, offset=offset)
+        results = await search_service.search(query, limit=fetch_limit, offset=offset)
     except SemanticSearchDisabledError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
     except SemanticDependenciesMissingError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
     except ValueError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    has_more = len(results) > page_size
+    if has_more:
+        results = results[:page_size]
+
     search_results = await to_search_results(entity_service, results)
     return SearchResponse(
         results=search_results,
         current_page=page,
         page_size=page_size,
+        has_more=has_more,
     )
 
 

src/basic_memory/api/v2/utils.py

@@ -146,6 +146,7 @@ def to_summary(item: SearchIndexRow | ContextResultRow):
         metadata=metadata,
         page=page,
         page_size=page_size,
+        has_more=context_result.metadata.has_more,
     )
 
 

src/basic_memory/mcp/tools/project_management.py

@@ -65,9 +65,7 @@ async def list_memory_projects(
         result = "Available projects:\n"
         for project in project_list.projects:
             label = (
-                f"{project.display_name} ({project.name})"
-                if project.display_name
-                else project.name
+                f"{project.display_name} ({project.name})" if project.display_name else project.name
             )
             result += f"• {label}\n"
 

src/basic_memory/mcp/tools/recent_activity.py

@@ -39,6 +39,8 @@ async def recent_activity(
     type: Union[str, List[str]] = "",
     depth: int = 1,
     timeframe: TimeFrame = "7d",
+    page: int = 1,
+    page_size: int = 10,
     project: Optional[str] = None,
     workspace: Optional[str] = None,
     output_format: Literal["text", "json"] = "text",
@@ -70,8 +72,11 @@ async def recent_activity(
             - "observation" or ["observation"] for notes and observations
             Multiple types can be combined: ["entity", "relation"]
             Case-insensitive: "ENTITY" and "entity" are treated the same.
-            Default is an empty string, which returns all types.
+            Default is entity-only. Specify other types explicitly to include
+            observations and relations.
         depth: How many relation hops to traverse (1-3 recommended)
+        page: Page number for pagination (default 1)
+        page_size: Number of items per page (default 10)
         timeframe: Time window to search. Supports natural language:
             - Relative: "2 days ago", "last week", "yesterday"
             - Points in time: "2024-01-01", "January 1st"
@@ -108,8 +113,8 @@ async def recent_activity(
     """
     # Build common parameters for API calls
     params: dict = {
-        "page": 1,
-        "page_size": 10,
+        "page": page,
+        "page_size": page_size,
         "max_related": 10,
     }
     if depth:
@@ -139,6 +144,12 @@ async def recent_activity(
         # Add validated types to params
         params["type"] = [t.value for t in validated_types]  # pyright: ignore
 
+    # Default to entity-only when no explicit type was provided.
+    # This prevents a single well-connected entity from filling the page
+    # with its observations and relations.
+    if "type" not in params:
+        params["type"] = [SearchItemType.ENTITY.value]
+
     # Resolve project parameter using the three-tier hierarchy
     # allow_discovery=True enables Discovery Mode, so a project is not required
     resolved_project = await resolve_project_parameter(project, allow_discovery=True)
@@ -271,7 +282,7 @@ async def recent_activity(
                 return _extract_recent_rows(activity_data)
 
             # Format project-specific mode output
-            return _format_project_output(resolved_project, activity_data, timeframe, type)
+            return _format_project_output(resolved_project, activity_data, timeframe, type, page)
 
 
 async def _get_project_activity(
@@ -424,6 +435,7 @@ def _format_project_output(
     activity_data: GraphContext,
     timeframe: str,
     type_filter: Union[str, List[str]],
+    page: int = 1,
 ) -> str:
     """Format project-specific mode output as human-readable text."""
     lines = [f"## Recent Activity: {project_name} ({timeframe})"]
@@ -504,12 +516,15 @@ def _format_project_output(
 
             lines.append(f"  • {from_link} → {rel_type} → {to_link}")
 
-    # Activity summary
+    # Activity summary with pagination guidance
     total = len(activity_data.results)
-    lines.append(f"\n**Activity Summary:** {total} items found")
-    if hasattr(activity_data, "metadata") and activity_data.metadata:
-        if hasattr(activity_data.metadata, "total_results"):
-            lines.append(f"Total available: {activity_data.metadata.total_results}")
+    if activity_data.has_more:
+        lines.append(
+            f"\n**Activity Summary:** Showing {total} items (page {page}). "
+            f"Use page={page + 1} to see more."
+        )
+    else:
+        lines.append(f"\n**Activity Summary:** {total} items found.")
 
     return "\n".join(lines)
 

src/basic_memory/schemas/memory.py

@@ -238,6 +238,7 @@ class GraphContext(BaseModel):
 
     page: Optional[int] = None
     page_size: Optional[int] = None
+    has_more: bool = False
 
 
 class ActivityStats(BaseModel):

src/basic_memory/schemas/search.py

@@ -141,3 +141,4 @@ class SearchResponse(BaseModel):
     results: List[SearchResult]
     current_page: int
     page_size: int
+    has_more: bool = False

src/basic_memory/services/context_service.py

@@ -57,6 +57,7 @@ class ContextMetadata:
     related_count: int = 0
     total_observations: int = 0
     total_relations: int = 0
+    has_more: bool = False
 
 
 @dataclass
@@ -102,6 +103,9 @@ async def build_context(
             f"Building context for URI: '{memory_url}' depth: '{depth}' since: '{since}' limit: '{limit}' offset: '{offset}'  max_related: '{max_related}'"
         )
 
+        # Fetch one extra item to detect whether more pages exist (N+1 trick)
+        fetch_limit = limit + 1
+
         normalized_path: Optional[str] = None
         if memory_url:
             path = memory_url_path(memory_url)
@@ -118,21 +122,26 @@ async def build_context(
                 normalized_path = "*".join(normalized_parts)
                 logger.debug(f"Pattern search for '{normalized_path}'")
                 primary = await self.search_repository.search(
-                    permalink_match=normalized_path, limit=limit, offset=offset
+                    permalink_match=normalized_path, limit=fetch_limit, offset=offset
                 )
             else:
                 # For exact paths, normalize the whole thing
                 normalized_path = generate_permalink(path, split_extension=False)
                 logger.debug(f"Direct lookup for '{normalized_path}'")
                 primary = await self.search_repository.search(
-                    permalink=normalized_path, limit=limit, offset=offset
+                    permalink=normalized_path, limit=fetch_limit, offset=offset
                 )
         else:
             logger.debug(f"Build context for '{types}'")
             primary = await self.search_repository.search(
-                search_item_types=types, after_date=since, limit=limit, offset=offset
+                search_item_types=types, after_date=since, limit=fetch_limit, offset=offset
             )
 
+        # Trim to requested limit and set has_more flag
+        has_more = len(primary) > limit
+        if has_more:
+            primary = primary[:limit]
+
         # Get type_id pairs for traversal
 
         type_id_pairs = [(r.type, r.id) for r in primary] if primary else []
@@ -171,6 +180,7 @@ async def build_context(
             related_count=len(related),
             total_observations=sum(len(obs) for obs in observations_by_entity.values()),
             total_relations=sum(1 for r in related if r.type == SearchItemType.RELATION),
+            has_more=has_more,
         )
 
         # Build context results list directly with ContextResultItem objects

src/basic_memory/services/project_service.py

@@ -39,9 +39,7 @@ class ProjectService:
 
     repository: ProjectRepository
 
-    def __init__(
-        self, repository: ProjectRepository, file_service: Optional["FileService"] = None
-    ):
+    def __init__(self, repository: ProjectRepository, file_service: Optional["FileService"] = None):
         """Initialize the project service."""
         super().__init__()
         self.repository = repository

tests/api/v2/test_memory_router.py

@@ -288,6 +288,41 @@ async def test_get_memory_context_with_timeframe(
     assert "results" in data
 
 
+@pytest.mark.asyncio
+async def test_recent_context_has_more(
+    client: AsyncClient,
+    test_project: Project,
+    v2_project_url: str,
+    entity_repository,
+    search_service,
+    file_service,
+):
+    """has_more should be True when there are more results beyond the current page."""
+    # Create enough entities to exceed a small page_size
+    for i in range(4):
+        entity_data = {
+            "title": f"HasMore Memory {i}",
+            "entity_type": "note",
+            "content_type": "text/markdown",
+            "file_path": f"hasmore_mem_{i}.md",
+            "checksum": f"hasmoremem{i}",
+        }
+        await create_test_entity(
+            test_project, entity_data, entity_repository, search_service, file_service
+        )
+
+    # Request page_size=2 — with 4 entities, has_more should be True
+    response = await client.get(
+        f"{v2_project_url}/memory/recent",
+        params={"page": 1, "page_size": 2, "type": ["entity"]},
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert "has_more" in data
+    assert data["has_more"] is True
+    assert len(data["results"]) == 2
+
+
 @pytest.mark.asyncio
 async def test_v2_memory_endpoints_use_project_id_not_name(
     client: AsyncClient,

tests/api/v2/test_search_router.py

@@ -361,3 +361,70 @@ async def search(self, *args, **kwargs):
 
     assert response.status_code == 400
     assert "Vector retrieval requires a text query" in response.json()["detail"]
+
+
+@pytest.mark.asyncio
+async def test_search_has_more_when_more_results_exist(
+    client: AsyncClient,
+    test_project: Project,
+    v2_project_url: str,
+    entity_repository,
+    search_service,
+    file_service,
+):
+    """has_more should be True when there are more results beyond the current page."""
+    # Create enough entities to exceed a small page_size
+    for i in range(4):
+        entity_data = {
+            "title": f"HasMore Entity {i}",
+            "entity_type": "note",
+            "content_type": "text/markdown",
+            "file_path": f"hasmore_{i}.md",
+            "checksum": f"hasmore{i}",
+        }
+        await create_test_entity(
+            test_project, entity_data, entity_repository, search_service, file_service
+        )
+
+    # Request page_size=2 — with 4 entities, has_more should be True
+    response = await client.post(
+        f"{v2_project_url}/search/",
+        json={"text": "HasMore Entity"},
+        params={"page": 1, "page_size": 2},
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert "has_more" in data
+    assert data["has_more"] is True
+    assert len(data["results"]) == 2
+
+
+@pytest.mark.asyncio
+async def test_search_has_more_false_on_last_page(
+    client: AsyncClient,
+    test_project: Project,
+    v2_project_url: str,
+    entity_repository,
+    search_service,
+    file_service,
+):
+    """has_more should be False when all results fit on the current page."""
+    entity_data = {
+        "title": "Solo Search Entity",
+        "entity_type": "note",
+        "content_type": "text/markdown",
+        "file_path": "solo_search.md",
+        "checksum": "solo123",
+    }
+    await create_test_entity(
+        test_project, entity_data, entity_repository, search_service, file_service
+    )
+
+    response = await client.post(
+        f"{v2_project_url}/search/",
+        json={"text": "Solo Search Entity"},
+        params={"page": 1, "page_size": 10},
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert data["has_more"] is False