Bound and paginate list_directory MCP results

[phernandez]

Problem

list_directory currently returns every matching directory and file row. Large projects can produce oversized MCP responses even when hosted Cloud decorations are capped.

Discovered while reviewing basicmachines-co/basic-memory-cloud#1470. Cloud now caps its added private note-link rows, but the core tool result remains unbounded.

Proposed change

• Add bounded pagination or an explicit validated limit to list_directory.
• Keep the default response small enough for agent tool use.
• Include continuation guidance or pagination metadata when more rows exist.
• Cover text and structured output, recursive depth, glob filtering, and stable ordering.

This changes the MCP tool surface/behavior, so ship it through the Basic Memory release and ChatGPT app review path rather than folding it into the Cloud trial-funnel hotfix.

[claude]

Claude finished @phernandez's task in 10m 15s —— View job • Create PR ➔

---

Implementation complete — push blocked by repo permissions

Todo list:

• Gather context: read list_directory MCP tool, service, router, schemas, and the codebase's existing pagination conventions (search_notes, recent_activity)
• Understand request: bound + paginate list_directory results
• Propose implementation plan
• Implement pagination for list_directory (service, v2 router, typed client, MCP tool: text + JSON output, stable ordering, depth/glob preserved)
• Update/add tests (service, router, MCP tool client, integration)
• Committed changes locally
• ⚠️ Push branch — blocked, see below
• Run lint/format/typecheck/tests — blocked, see below

What changed

• src/basic_memory/schemas/directory.py: new DirectoryListResponse (nodes, page, page_size, total, has_more).
• src/basic_memory/services/directory_service.py: DirectoryService.list_directory() now sorts results with a stable order (directories before files, then by name) and slices by page/page_size. page_size is clamped to a new MAX_PAGE_SIZE = 200 regardless of what's requested.
• src/basic_memory/api/v2/routers/directory_router.py: /directory/list now takes page (ge=1) and page_size (ge=1, le=200) query params and returns DirectoryListResponse instead of a bare list.
• src/basic_memory/mcp/clients/directory.py: DirectoryClient.list() returns the typed DirectoryListResponse.
• src/basic_memory/mcp/tools/list_directory.py: the MCP tool gains page, page_size (default 10, matching search_notes/recent_activity convention), and output_format ("text"/"json", matching search_notes). Text output now shows page X (page_size Y, Z total) and appends More results available. Call list_directory(..., page=N+1, ...) to continue. when has_more is true. Raises ValueError for non-positive page/page_size, consistent with search_notes.
• Updated/added tests across tests/services/test_directory_service.py, tests/api/v2/test_directory_router.py, tests/mcp/clients/test_clients.py, tests/mcp/test_tool_list_directory.py, and test-int/mcp/test_list_directory_integration.py covering pagination, clamping, stable ordering, and JSON output.

Blockers

1. Test/lint execution: my sandbox in this run only allows read-only/git commands — just fast-check, uv run ruff, just lint, and even plain python3 invocations are rejected with "This command requires approval." I was not able to run the test suite, linter, or type checker. I did a careful manual review (line-length checks via search, diff review) instead, but please run just fast-check and just test locally/in CI before merging.
2. Push permission: git push fails with:

   remote: Permission to basicmachines-co/basic-memory.git denied to github-actions[bot].
   fatal: unable to access '...': The requested URL returned error: 403
   

   The commit (3d982f6, signed off) is sitting locally on claude/issue-1048-20260712-0227 but I cannot push it. This looks like the workflow's GitHub App token doesn't have contents: write for this repo, or branch protection is rejecting the bot. Please check the Actions workflow permissions / app installation, or let me know if you'd like me to retry.

Once pushed, a PR can be opened via: