[FEATURE] Friendly slugs for Teams shared workspace permalinks

[groksrc]

Feature Description

Allow Teams/shared workspaces to have a human-friendly permalink identifier/slug that is used in workspace-qualified memory:// links and other shared workspace permalink prefixes.

Today our shared workspace identifier is:

basic-memory-7020de4e925843c68c9056c60d101d9e

That works as a stable machine identifier, but it does not exactly roll off the tongue.

Problem This Feature Solves

Workspace identifiers can show up in permalinks, docs, CLI output, MCP arguments, support/debugging notes, and chat. An opaque generated value is hard to read, share, type, recognize, or remember, especially when the meaningful part is buried next to a long suffix.

Proposed Solution

Generate and support short, stable, human-friendly slugs for Teams/shared workspaces, for example basic-memory, basic-memory-team, or another collision-safe variant based on the workspace/team name.

Possible shape:

• Keep the tenant/workspace ID as the immutable internal identifier.
• Treat the friendly slug as a permalink/display alias for workspace-qualified links.
• Let workspace owners/admins edit the slug with validation and collision checks.
• Preserve backwards compatibility by continuing to resolve existing generated identifiers, or by aliasing/redirecting old identifiers after a slug change.
• Surface the active slug in workspace management commands and any docs/examples that show workspace-qualified permalinks.

Alternative Solutions

Keep the opaque identifier as canonical and add an optional share_alias/display alias, or shorten the generated suffix. Those would help, but a first-class friendly slug seems easier for users to understand and use consistently.

Additional Context

Existing code and tests already refer to workspace_slug in canonical permalink contexts with readable examples like team-paul/<project>/..., so this feels aligned with the current workspace-qualified permalink model.

Impact

Friendly workspace slugs would make shared workspace links easier to read, copy, type, troubleshoot, and discuss. They would also make Teams/shared workspace URLs and memory:// identifiers feel polished instead of exposing an implementation-shaped ID.

[claude]

Claude finished @groksrc's task in 1m 13s —— View job

---

Issue Triage

• Gather context and analyze issue
• Check for duplicate issues
• Review existing workspace_slug usage in codebase
• Add appropriate labels
• Provide triage summary

---

Triage Summary

Type: Feature Request — UX/usability improvement for Teams/shared workspace permalinks

Priority: Medium — The current identifiers work fine; this is a polish/readability improvement that would make shared workspace links significantly more user-friendly.

Component: Cloud (primarily) — The local Basic Memory codebase already has full workspace_slug infrastructure in place.

Complexity: Medium/Complex — Mostly cloud-side work, but touches several surfaces.

---

Technical Analysis

The good news: the local codebase is already ready for friendly slugs. The workspace_slug concept is fully implemented in src/basic_memory/workspace_context.py — the cloud layer injects the slug per-request via the X-Basic-Memory-Workspace-Slug HTTP header, and the local API uses it for canonical permalink generation. The slug validation already accepts any [a-z0-9_-]+ string, so a friendly slug like basic-memory-team would pass validation today.

The work needed is primarily cloud-side:

1. Slug generation — Generate an initial friendly slug from the workspace/team name when a workspace is created (e.g. basic-machines → basic-machines).
2. Slug storage & uniqueness — Store the friendly slug in the cloud DB, enforce uniqueness with collision-safe suffix logic.
3. Slug editing — Allow workspace owners/admins to update the slug with validation and collision checks.
4. Backwards compatibility — Old UUID-style identifiers must continue to resolve (either kept as aliases or redirected).
5. Surface the slug — Show the active slug in basic-memory cloud status, basic-memory project info, and relevant docs.
6. CLI/management commands — Potentially basic-memory cloud set-slug <slug> or similar.

The local code change would be minimal: the cloud just needs to start passing a friendly slug in the header instead of the opaque UUID.

---

Duplicate Check

No duplicates found. Related issues for context:

• write_note doesn't expose/document workspace targeting — agents can't disambiguate same-named projects across workspaces #882 — workspace disambiguation in write_note (different problem: same-named projects across workspaces)
• Workspace-qualified memory URLs do not self-route from local active project #836 (closed) — workspace-qualified memory URL routing bug

Labels added: enhancement, cloud