Skip to content

feat: add stable pagination guard and large-note perf follow-ups for read_note #169

@maehwasoo

Description

@maehwasoo

Problem statement

read_note pagination currently uses start_index + max_chars, but paginated reads do not carry a stable note-version guard. If a note changes between page requests, clients can receive mixed-version slices without a deterministic detection path. In addition, large-note pagination can be inefficient because each request can trigger repeated full-text reads.

Proposed solution

Harden read_note pagination consistency and performance while preserving backward compatibility.

  • Stable pagination guard:
    • Return a stable change token in read_note responses (for example, mtime_ms and/or sha256).
    • Accept an optional expected token on subsequent page requests.
    • When token mismatches, return a clear structured error so clients can restart pagination safely.
  • Performance follow-ups for large notes:
    • Reduce repeated full-file reads across sequential page requests.
    • Implement a bounded in-process cache and/or optimized partial-read strategy with clear invalidation semantics.
    • Define memory/performance limits so optimization is predictable under load.
  • API/contract handling:
    • Keep existing fields (text, truncated, next_start_index) intact for compatibility.
    • Document continuation flow and mismatch recovery in MCP tool docs.
  • Validation and tests:
    • Add tests for unchanged-note pagination, mid-stream note edits (mismatch path), and large-note performance behavior.
    • Verify no regression on path traversal and vault-root safety constraints.

Constraints / context (optional)

  • Keep read_note read-only semantics; no write-side behavior.
  • Preserve current clients by making new guard fields/options additive.
  • Maintain strict vault-relative path handling and existing security checks.

Metadata

Metadata

Assignees

Labels

coreCore packageenhancementNew feature or requestmcpMCP server

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions