Support sorting in the directory listing API

[phernandez]

Problem

The hosted MCP project and folder browser needs to render one exact directory with both its child folders and notes. The Core directory contract currently accepts directory, depth, glob, page, and page size, but no sort order.

For Title descending, Newest, or Oldest, Cloud must switch to a notes-only endpoint. That loses folder cards. Calling both endpoints would restore folders but duplicate the directory read and repeat work on every navigation.

Proposed contract

Add an explicit, closed sort option to the directory endpoint and DirectoryClient.list, covering:

• title_asc (existing default behavior)
• title_desc
• updated_asc
• updated_desc

The response should keep directories and files in one exact-depth listing with stable pagination and deterministic tie-breaking. Folder ordering should be defined explicitly, preferably folders first using the same selected direction within the folder group.

Acceptance criteria

• The directory API and typed client accept the supported sort variants.
• A single depth-1 request returns child folders and notes in the requested deterministic order.
• Pagination remains stable across pages for equal titles or timestamps.
• Existing callers retain the current default ordering when sort is omitted.
• Endpoint, client, and pagination behavior have regression coverage.

Context

This unblocks removing the hosted MCP notes-only sorting fallback while preserving its one-directory-read navigation contract.

[claude]

Claude finished @phernandez's task in 40s —— View job

---

Triage

Type: Enhancement (feature request — new sort capability on an existing read endpoint)

Component: Core directory API / MCP (DirectoryClient, directory_router, directory_service). Not Cloud-specific in itself — the Cloud folder/notes browser is the motivating consumer, but the change lives in the shared Core contract (src/basic_memory/api/v2/routers/directory_router.py, src/basic_memory/services/directory_service.py, src/basic_memory/mcp/clients/directory.py), so the cloud component label doesn't apply.

Priority: Medium. Nothing is broken today — Cloud has a working (if duplicative) fallback via the notes-only endpoint — but this blocks removing that fallback and unifies the one-directory-read navigation contract.

Complexity: Medium. Well-scoped: a closed enum of 4 sort variants (title_asc, title_desc, updated_asc, updated_desc) threaded through the API param, DirectoryClient.list, and the underlying query/sort in directory_service.py, plus deterministic tie-breaking for stable pagination and an explicit folders-first ordering rule. Main design decision to nail down before implementation: the exact tie-breaker key (likely path/title as secondary sort) and how folder vs. file precedence composes with each of the four directions — worth confirming in a design comment before coding starts.

Duplicates: No exact duplicate found. Related but distinct: #884 (modeling directories as first-class DB records) and #1048 (bounding/pagination for list_directory) — neither covers sort order.

Labels applied: enhancement.

[phernandez]

Cloud consumer and one-read navigation context: basicmachines-co/basic-memory-cloud#1764