fix(mcp): cap recent_activity rows with explicit truncation footer

The project-mode formatter previously hardcoded a display cap of 5
entities and 5 relations, but the heading and the "Activity Summary"
line both reported the true count returned by the API. The result was a
misleading silent truncation: e.g. a heading of "Recent Notes &
Documents (9)" with only 5 rows below it and no signal that 4 had been
dropped.

This raises the cap to 10 (matching the default page_size) and, when
the cap is hit, appends an explicit "…and N more on this page (raise
page_size to display all)" line so the truncation is visible to the
caller. Below the cap, behavior is unchanged.

Adds two regression tests covering both the below-cap (no footer) and
above-cap (footer present, body truncated to cap) paths.

Closes #784

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Drew Cain <groksrc@gmail.com>

Author: groksrc

src/basic_memory/mcp/tools/recent_activity.py

@@ -25,6 +25,14 @@
 from basic_memory.schemas.search import SearchItemType
 
 
+# Display cap for project-mode entity and relation rows in the formatted output.
+# The API has already paginated to `page_size`; this is a separate readability
+# guardrail that keeps the LLM-facing text compact when callers ask for large
+# pages. When exceeded, `_format_project_output` appends an explicit
+# "…and N more" line so the truncation is visible rather than silent.
+_PROJECT_OUTPUT_DISPLAY_CAP = 10
+
+
 @mcp.tool(
     description="""Get recent activity for a project or across all projects.
 
@@ -187,9 +195,7 @@ async def recent_activity(
     # project_id (UUID) takes precedence over project name — without this fallback,
     # callers passing only project_id would fall into Discovery Mode.
     effective_identifier = project_id if project_id else project
-    resolved_project = await resolve_project_parameter(
-        effective_identifier, allow_discovery=True
-    )
+    resolved_project = await resolve_project_parameter(effective_identifier, allow_discovery=True)
 
     if resolved_project is None:
         # Discovery Mode: Get activity across all projects
@@ -304,9 +310,7 @@ async def recent_activity(
             f"Getting recent activity from project {resolved_project}: type={type}, depth={depth}, timeframe={timeframe}"
         )
 
-        async with get_project_client(
-            resolved_project, context=context, project_id=project_id
-        ) as (
+        async with get_project_client(resolved_project, context=context, project_id=project_id) as (
             client,
             active_project,
         ):
@@ -492,10 +496,16 @@ def _format_project_output(
         elif result.primary_result.type == "observation":
             observations.append(result.primary_result)
 
-    # Show entities (notes/documents)
+    # Show entities (notes/documents).
+    # Trigger: more entities returned than the display cap.
+    # Why: keep formatted output compact for LLM context while still surfacing the
+    # true total in the heading. Previously the cap was silent — the heading said
+    # N items and the body listed only 5, with no signal the body was truncated.
+    # Outcome: render up to `_PROJECT_OUTPUT_DISPLAY_CAP` rows; if any were dropped,
+    # append an explicit "…and N more" line directing the caller to raise page_size.
     if entities:
         lines.append(f"\n**📄 Recent Notes & Documents ({len(entities)}):**")
-        for entity in entities[:5]:  # Show top 5
+        for entity in entities[:_PROJECT_OUTPUT_DISPLAY_CAP]:
             title = entity.title or "Untitled"
             # Get folder from file_path
             folder = ""
@@ -504,6 +514,9 @@ def _format_project_output(
                 if folder_path and folder_path != ".":
                     folder = f" ({folder_path})"
             lines.append(f"  • {title}{folder}")
+        if len(entities) > _PROJECT_OUTPUT_DISPLAY_CAP:
+            hidden = len(entities) - _PROJECT_OUTPUT_DISPLAY_CAP
+            lines.append(f"  …and {hidden} more on this page (raise page_size to display all)")
 
     # Show observations (categorized insights)
     if observations:
@@ -525,10 +538,10 @@ def _format_project_output(
                     content = _truncate_at_word(content, 80)
                 lines.append(f"    - {content}")
 
-    # Show relations (connections)
+    # Show relations (connections). Same cap-with-explicit-truncation pattern as entities.
     if relations:
         lines.append(f"\n**🔗 Recent Connections ({len(relations)}):**")
-        for rel in relations[:5]:  # Show top 5
+        for rel in relations[:_PROJECT_OUTPUT_DISPLAY_CAP]:
             rel_type = rel.relation_type
             from_entity = rel.from_entity or "Unknown"
             to_entity = rel.to_entity
@@ -538,6 +551,9 @@ def _format_project_output(
             to_link = f"[[{to_entity}]]" if to_entity else "[Missing Link]"
 
             lines.append(f"  • {from_link} → {rel_type} → {to_link}")
+        if len(relations) > _PROJECT_OUTPUT_DISPLAY_CAP:
+            hidden = len(relations) - _PROJECT_OUTPUT_DISPLAY_CAP
+            lines.append(f"  …and {hidden} more on this page (raise page_size to display all)")
 
     # Activity summary with pagination guidance
     total = len(activity_data.results)

tests/mcp/test_tool_recent_activity.py

@@ -259,6 +259,159 @@ def test_recent_activity_format_project_output_no_results():
     assert "No recent activity found" in out
 
 
+def test_recent_activity_format_project_output_renders_all_entities_and_relations():
+    """Regression for #784, part 1: when the result count is below the display cap
+    the formatter must render every row. Previously the cap was hardcoded at 5,
+    so a result set of 7 entities would show 5 rows under a heading that claimed 7.
+    """
+    import importlib
+
+    from basic_memory.schemas.memory import RelationSummary
+
+    recent_activity_module = importlib.import_module("basic_memory.mcp.tools.recent_activity")
+    now = datetime.now(timezone.utc)
+
+    entity_titles = [f"Entity {i}" for i in range(7)]
+    relation_titles = [f"Relation {i}" for i in range(6)]
+
+    results = [
+        ContextResult(
+            primary_result=EntitySummary(
+                external_id=f"550e8400-e29b-41d4-a716-44665544{i:04d}",
+                entity_id=i,
+                permalink=f"notes/entity-{i}",
+                title=title,
+                content=None,
+                file_path=f"notes/entity-{i}.md",
+                created_at=now,
+            ),
+            observations=[],
+            related_results=[],
+        )
+        for i, title in enumerate(entity_titles)
+    ] + [
+        ContextResult(
+            primary_result=RelationSummary(
+                relation_id=100 + i,
+                entity_id=i,
+                title=title,
+                file_path=f"notes/entity-{i}.md",
+                permalink=f"notes/entity-{i}",
+                relation_type="references",
+                from_entity=f"Entity {i}",
+                to_entity=f"Entity {i + 1}",
+                created_at=now,
+            ),
+            observations=[],
+            related_results=[],
+        )
+        for i, title in enumerate(relation_titles)
+    ]
+
+    activity = GraphContext(
+        results=results,
+        metadata=MemoryMetadata(depth=1, generated_at=now),
+    )
+
+    out = recent_activity_module._format_project_output(
+        project_name="proj",
+        activity_data=activity,
+        timeframe="7d",
+        type_filter=["entity", "relation"],
+        page=1,
+    )
+
+    for title in entity_titles:
+        assert title in out, f"Entity {title!r} missing from formatter output"
+    for i in range(len(relation_titles)):
+        assert f"[[Entity {i}]] → references → [[Entity {i + 1}]]" in out, (
+            f"Relation {i} missing from formatter output"
+        )
+    # Below-cap path: no truncation footer should appear.
+    assert "more on this page" not in out
+
+
+def test_recent_activity_format_project_output_caps_with_explicit_truncation():
+    """Regression for #784, part 2: above the display cap the formatter must
+    truncate to the cap AND emit an explicit "…and N more" footer so the caller
+    can see that the body is a preview of a longer page (and knows to raise
+    page_size).
+    """
+    import importlib
+
+    from basic_memory.schemas.memory import RelationSummary
+
+    recent_activity_module = importlib.import_module("basic_memory.mcp.tools.recent_activity")
+    cap = recent_activity_module._PROJECT_OUTPUT_DISPLAY_CAP
+    now = datetime.now(timezone.utc)
+
+    entity_count = cap + 2
+    relation_count = cap + 3
+
+    # Use prefixes that don't collide between entities and relation endpoints,
+    # so substring assertions don't accidentally match across rows.
+    results = [
+        ContextResult(
+            primary_result=EntitySummary(
+                external_id=f"550e8400-e29b-41d4-a716-44665544{i:04d}",
+                entity_id=i,
+                permalink=f"notes/entity-{i}",
+                title=f"NoteFile {i}",
+                content=None,
+                file_path=f"notes/entity-{i}.md",
+                created_at=now,
+            ),
+            observations=[],
+            related_results=[],
+        )
+        for i in range(entity_count)
+    ] + [
+        ContextResult(
+            primary_result=RelationSummary(
+                relation_id=1000 + i,
+                entity_id=i,
+                title=f"Relation {i}",
+                file_path=f"notes/entity-{i}.md",
+                permalink=f"notes/entity-{i}",
+                relation_type="references",
+                from_entity=f"FromNode {i}",
+                to_entity=f"ToNode {i}",
+                created_at=now,
+            ),
+            observations=[],
+            related_results=[],
+        )
+        for i in range(relation_count)
+    ]
+
+    activity = GraphContext(
+        results=results,
+        metadata=MemoryMetadata(depth=1, generated_at=now),
+    )
+
+    out = recent_activity_module._format_project_output(
+        project_name="proj",
+        activity_data=activity,
+        timeframe="7d",
+        type_filter=["entity", "relation"],
+        page=1,
+    )
+
+    # Heading reports the true total (independent of truncation).
+    assert f"Recent Notes & Documents ({entity_count})" in out
+    assert f"Recent Connections ({relation_count})" in out
+
+    # Body shows exactly `cap` rows of each.
+    assert f"NoteFile {cap - 1}" in out, "expected last in-cap entity to appear"
+    assert f"NoteFile {cap}" not in out, "entity beyond cap should be truncated"
+    assert f"[[FromNode {cap - 1}]] → references → [[ToNode {cap - 1}]]" in out
+    assert f"[[FromNode {cap}]]" not in out, "relation beyond cap should be truncated"
+
+    # Truncation footer is present and reports the correct hidden count.
+    assert f"…and {entity_count - cap} more on this page" in out
+    assert f"…and {relation_count - cap} more on this page" in out
+
+
 def test_recent_activity_format_project_output_includes_observation_truncation():
     import importlib