Permalinks are not workspace-disambiguated (teams launch blocker)

[groksrc]

Summary

Permalinks are scoped only by project name, not by workspace. When the same project name exists in multiple workspaces (e.g., the auto-provisioned getting-started and main in both Personal and an organization workspace), permalinks for notes in those projects are byte-identical across workspaces. The only reliable disambiguator is project_id — but several tools and surfaces only have the permalink.

Reproduction

Account has two workspaces: Personal (default) and drew cain (organization). Both auto-provision getting-started and main projects.

Create a note in drew-cain/getting-started:

• returned permalink: getting-started/notes/org-endpoint-smoke-test

Create a note with the same title in personal/getting-started and you get the identical permalink. Tools that only take a permalink (e.g., fetch) cannot tell which one you mean and silently resolve to whichever project is the default.

Why this blocks teams launch

Once orgs are GA, every account starts with two getting-started projects (one per workspace) and two main projects. Any feature that surfaces a permalink (UI, sharing, citations, agent context) becomes ambiguous on day one. URLs/links shared with teammates may resolve to the wrong note.

Expected

Permalinks should embed the workspace slug (or tenant identifier), e.g.:

• personal/getting-started/notes/org-endpoint-smoke-test
• drew-cain/getting-started/notes/org-endpoint-smoke-test

Or — keep the current format internally but expose a workspace-qualified canonical URL/permalink in any user-facing or cross-tool API surface.

[claude]

Claude finished @groksrc's task in 2m 41s —— View job

---

Issue Triage

• Analyze issue and gather context
• Explore permalink-related code in codebase
• Check for duplicate issues
• Apply appropriate labels
• Provide triage summary

---

Summary

Labels applied: bug, cloud, enhancement

Dimension	Assessment
Type	Bug + Enhancement — silent wrong resolution is a defect; the fix requires new functionality
Priority	High — author explicitly labels it a teams launch blocker; affects every multi-workspace account on day one of GA
Component	Cloud (workspace routing), MCP tools (fetch, read_note, build_context)
Complexity	Complex — architectural change to permalink format with backward-compatibility requirements

No duplicate issues found.

---

Technical Analysis

After exploring the codebase, here is the confirmed root cause and scope:

Root cause: Permalinks are unique per project (DB constraint uix_entity_permalink_project), but project is not unique per workspace. When two workspaces both auto-provision a project named getting-started, their project.permalink values are both getting-started. Any tool or surface that holds only a permalink string (no project_id) cannot distinguish between them.

Where this matters most:

• fetch MCP tool / resolve_entity_id() (src/basic_memory/mcp/tools/utils.py:586-615): POST /v2/projects/{project_id}/knowledge/resolve — the caller must already know the project_id; tools that only have a permalink string fall back to the default project.
• link_resolver.py (src/basic_memory/services/link_resolver.py:44-147): Cross-project fallback uses project/path syntax, which is ambiguous when two workspaces share a project name.
• Shared/cited permalinks in UI or agent context: Any permalink surfaced to users or embedded in notes becomes ambiguous across workspaces.

Existing partial mitigation: There is already a config flag permalinks_include_project (src/basic_memory/config.py) that prefixes entity permalinks with the project slug (e.g., getting-started/notes/foo). This handles same-named notes within different projects in the same workspace, but still does not solve same-named projects across different workspaces.

Proposed solutions (from issue + codebase analysis):

1. Embed workspace slug in permalink — e.g., personal/getting-started/notes/org-endpoint-smoke-test vs drew-cain/getting-started/notes/org-endpoint-smoke-test. This requires:

   • Adding workspace slug to generate_permalink() / build_canonical_permalink() pipeline
   • Updating all memory:// URL parsing to handle 3-segment paths (workspace/project/path)
   • DB migration to update existing permalinks (breaking change for existing installs)
   • Updating the fetch, read_note, build_context, and edit_note tools

2. Keep short permalink internally, expose workspace-qualified canonical URL on all user-facing surfaces — lower blast radius, no DB migration, but requires distinguishing "internal permalink" from "canonical URL" everywhere.

Option 2 is lower risk for a launch blocker fix; option 1 is the correct long-term solution.

Suggested scope for the fix:

• The Project model needs a workspace_id or workspace_slug field (if not already present)
• build_canonical_permalink() (src/basic_memory/utils.py:223-249) should optionally prepend workspace slug
• The resolve endpoint and link_resolver must be workspace-aware when matching by string permalink