Repository navigation
Support sorting in the directory listing API #1267
Description
Activity
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 thecloudcomponent 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 indirectory_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.Cloud consumer and one-read navigation context: basicmachines-co/basic-memory-cloud#1764
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_descupdated_ascupdated_descThe 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
Context
This unblocks removing the hosted MCP notes-only sorting fallback while preserving its one-directory-read navigation contract.