Replace polymorphic project resolve identifier with explicit lookup contracts

[phernandez]

Problem

POST /v2/projects/resolve accepts one opaque identifier string and resolves it by trying external ID, permalink, and case-insensitive name. If that misses, it parses an MCP-suggested workspace/project value and retries the project segment.

That compatibility contract makes identifier meaning implicit. Cloud authorization and API-key scope enforcement must mirror the same lookup order before forwarding the request, and UUID-shaped names cannot be understood from string syntax alone.

The route is retained for now because MCP callers begin with human project references and existing disambiguation hints tell models to retry with workspace/project. This compatibility behavior is explicit and temporary; it should not spread to path authorization.

The Core app also registers the v2 project router under the obsolete /proxy/projects prefix, producing duplicate /proxy/projects/projects/... routes. A read-only Logfire audit found zero uses of that alias across four consecutive 14-day windows ending 2026-08-16. Cloud #1763 denies the alias at its gateway edge while its pinned Core revision still contains it.

Desired design

• Introduce an explicit project lookup contract, either separate routes or a closed request shape such as { "kind": "name" | "permalink" | "external_id", "value": "..." }.
• Keep workspace selection in the workspace routing context instead of encoding it into a project identifier string.
• Migrate MCP project resolution and Cloud authorization/API-key scope callers to the explicit contract.
• Instrument remaining use of the polymorphic compatibility route.
• Deprecate and remove the external-ID → permalink → name lookup chain and workspace/project retry.
• Delete the unused /proxy/projects/projects/... router alias; /v2/projects/... is the only project path contract.

Acceptance criteria

• UUID-shaped project names are resolved as names without probing external IDs.
• External-ID lookups perform one exact external-ID lookup and never retry as another identifier kind.
• Workspace-qualified input is represented by separate workspace and project fields.
• The legacy polymorphic route and Cloud's mirrored resolver can be deleted after callers migrate.
• The duplicate /proxy/projects/projects/... route registration is removed.

Related Cloud cleanup: https://github.com/basicmachines-co/basic-memory-cloud/issues/1761
Related PR: https://github.com/basicmachines-co/basic-memory-cloud/pull/1763

[claude]

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

---

Triage

Type: Enhancement — architectural cleanup of an existing API contract, not a defect.

Component: MCP client project resolution (src/basic_memory/mcp/clients/project.py, src/basic_memory/mcp/project_context.py) and the v2 API route POST /v2/projects/resolve (src/basic_memory/api/v2/routers/project_router.py), with a directly-linked Cloud counterpart (auth/API-key scope enforcement mirrors the same lookup order, per the linked basic-memory-cloud issue/PR). Labeled component:cloud since the migration explicitly spans Cloud authorization callers.

Priority: Medium — no breakage today; this is a design-debt/consistency risk (implicit identifier semantics, UUID-shaped names being probed as external IDs, authz logic that must mirror route-resolution order) rather than a live bug.

Complexity: Complex — spans a new explicit lookup contract (schema/route design), migrating MCP resolution and the linked Cloud repo's authorization/API-key scope callers, instrumenting the legacy route before removal, and only then deleting the polymorphic identifier chain and workspace/project retry. Cross-repo coordination with basicmachines-co/basic-memory-cloud (issue #1761, PR #1763) is a dependency.

Verified the current implementation matches the issue's description: _resolve_project_identifier/_resolve_project_identifier_candidate in project_router.py:67-120 do try external_id → permalink → case-insensitive name, then split on / and retry the project segment against the same chain — confirming the polymorphic/implicit-ordering problem as described.

No duplicate open issues found for this proposal.

Labels applied: enhancement, component:cloud.

Per triage scope, no implementation, branch, or code changes were made — this issue includes a detailed design and acceptance criteria, so it's ready for someone to pick up as an implementation task when prioritized.