Bug: read_note pagination parameters have no effect

[bm-clawd]

Bug: read_note pagination parameters have no effect

Description

The read_note MCP tool accepts page and page_size parameters, but they have no effect on the output. The tool always returns the full note content regardless of pagination settings.

This causes issues when:

• Large notes (>50KB) exceed Claude Code's inline display limit
• Users expect to chunk large notes into readable segments
• The tool help text suggests pagination should work

Reproduction

# Test with MEMORY.md (33,928 chars)
bm tool read-note "claw/memory" --page 1 --page-size 1
bm tool read-note "claw/memory" --page 1 --page-size 100
bm tool read-note "claw/memory" --page 1 --page-size 5000

All three commands return identical output: 33,928 characters.

Expected Behavior

• page-size 1 should return a small chunk (e.g., first N lines or chars)
• page-size 100 should return a larger chunk
• Subsequent pages (--page 2, etc.) should return different content

Actual Behavior

All pagination parameters are ignored. Full note content is always returned.

Impact

• Users with large notes (87KB reported in Discord) cannot read them via MCP
• Claude Code truncates to 2KB preview when tool output exceeds display limits
• Workarounds required: split notes, use search_notes, or filesystem access

Environment

• BM CLI version: (latest from uv)
• Tested via: bm tool read-note CLI command
• Project: openclaw-basics-mbp-lan

CLI Help Text (shows pagination params)

--page                       INTEGER  Page number for pagination [default: 1]
--page-size                  INTEGER  Number of results per page [default: 10]

The help text implies pagination should work, but it doesn't.

Suggested Fix

Either:

1. Implement chunked reading for read_note (honor page_size param)
2. Remove pagination params from the tool schema if not supported
3. Document that pagination only applies to search_notes, not read_note

[claude]

Claude finished @bm-clawd's task in 1m 24s —— View job

---

Triage Complete

• Gather context and analyze issue
• Investigate read_note implementation
• Check for duplicate issues
• Apply labels and complete triage

---

Issue Classification

Field	Value
Type	Bug (code defect)
Priority	High — affects usability for large notes; 87KB notes reported in Discord
Component	MCP tools + API router
Complexity	Medium — requires changes at API layer, client, and tool levels

Labels applied: bug, enhancement

---

Root Cause Analysis

The bug is confirmed. The pagination parameters flow correctly through the call stack but are silently ignored by the API endpoint:

1. read_note tool (mcp/tools/read_note.py:252) passes page and page_size to ResourceClient.read()
2. ResourceClient.read() (mcp/clients/resource.py:61-70) correctly adds them as query params
3. get_resource_content endpoint (api/v2/routers/resource_router.py:35-87) — the bug is here

@router.get("/{entity_id}")
async def get_resource_content(
    config: ProjectConfigV2ExternalDep,
    entity_repository: EntityRepositoryV2ExternalDep,
    file_service: FileServiceV2ExternalDep,
    project_id: str = ...,
    entity_id: str = ...,
) -> Response:

The endpoint signature has no page or page_size parameters — FastAPI simply ignores the query params, and the endpoint always reads the full file content via file_service.read_file_bytes().

---

Fix Required

The API endpoint needs to accept page/page_size query params and implement line-based chunking:

Files to modify:

• src/basic_memory/api/v2/routers/resource_router.py — add page/page_size params, implement content chunking
• Tests in tests/ and/or test-int/ — verify pagination behavior

Suggested approach (line-based chunking):

• Split content by lines
• page_size = number of lines per page (default e.g. 200)
• page = 1-based page number
• Return the slice + metadata (total lines, total pages, current page) in headers or response wrapper

Alternative: Change semantics to character-based chunking (more predictable for LLM context limits).

Note: The tool docstring example read_note("work-project", "Project Updates", page=2, page_size=5) implies line-based pagination, but page_size=5 defaulting to 10 lines seems very small — the default should probably be something like 200 lines for useful LLM context.

---

No Duplicates Found

No existing issues for this specific bug were found.

[majiayu000]

Hi, I've been looking into this and traced the root cause.

Proposed approach: 1. Add page (default=1) and page_size (default=200 lines) query params to get_resource_content in resource_router.py. 2. After reading file content, split by lines, compute slice for requested page, return chunked content with pagination metadata in response headers or wrapper. 3. Add unit/integration tests verifying different page/page_size values return correct chunks.

I'll open a draft PR shortly. Happy to adjust based on your preference.