`write_note` doesn't expose/document workspace targeting — agents can't disambiguate same-named projects across workspaces

[groksrc]

Problem

When projects of the same name exist in different workspaces (Teams vs. local vs. other cloud workspaces), agents (e.g. Codex) can't figure out how to target the right one with write_note. They expect a workspace argument or automatic selection, and can't intuit that the routing pattern is <workspace>/<project>.

The routing machinery already supports this — it's a tool-surface/documentation gap, and write_note is inconsistent with edit_note.

Details

• write_note has no workspace parameter and doesn't document the qualified syntax. Its project docstring only says "Project name to write to… server will resolve using the hierarchy" and points at project_id for collisions (src/basic_memory/mcp/tools/write_note.py:25-41, docstring :82-87). Nothing tells the agent that project accepts workspace/project.
• edit_note already does it right. It has a dedicated workspace parameter and documents the pattern: "Use workspace/project to route to a project in a specific cloud workspace" (src/basic_memory/mcp/tools/edit_note.py:284-291).
• The resolver supports <workspace>/<project> (mcp/project_context.py:398-407 _split_qualified_project_identifier, :801-868 resolve_workspace_project_identifier), and list_memory_projects already returns qualified_name (workspace-slug/project-name), workspace_slug, and external_id (mcp/tools/project_management.py:163-181) — the agent just isn't told to use them.
• Silent collision fallback adds to the confusion: on an ambiguous bare name, the resolver silently prefers the project in the default workspace and only errors if there's no default (mcp/project_context.py:893-906). So an agent intending a Teams-workspace project can have its note land in the default/local workspace with no signal.

Suggested fix

Bring write_note to parity with edit_note (and ideally audit the other note tools — read_note, move_note, delete_note — for the same gap):

1. Add a workspace parameter to write_note, mirroring edit_note (workspace slug/name/tenant_id; combines with project as workspace/project; mutually exclusive with project_id).
2. Document the workspace/project syntax in the project docstring, matching edit_note's wording.
3. Reconsider the silent default-workspace fallback on collisions: when a bare name is ambiguous, prefer raising the disambiguation error (with qualified_name choices) over silently picking the default workspace — or at least surface which workspace was chosen in the success response so the agent can detect a mismatch.

Related

• move_note falsely reports success for unsupported cross-workspace/cross-project moves #881 (move_note false success on cross-workspace moves — same workspace-routing confusion)

[claude]

Claude finished @groksrc's task in 8m 33s —— View job

---

Issue Triage & Implementation

Classification: Enhancement — MCP tools surface/documentation gap
Priority: Medium — agents silently route to wrong workspace on bare project name collisions
Complexity: Medium
Components: mcp, mcp-tool

• Analyze issue and gather context
• Read relevant source files — confirmed the parity gap between write_note and edit_note
• Add enhancement label to issue
• Move _compose_workspace_project_route to project_context.py as compose_workspace_project_route
• Add workspace parameter to write_note
• Add workspace parameter to read_note
• Add workspace parameter to delete_note
• Add workspace parameter to move_note
• Update edit_note.py to import the shared helper (removed local duplicate)
• Add workspace validation tests to test_tool_write_note.py
• Update stale test references in test_tool_edit_note.py
• Push to remote (GitHub Actions bot lacks write access to this branch)

Summary

All 5 note-manipulation MCP tools (write_note, read_note, delete_note, move_note, edit_note) now have a consistent workspace parameter and document the workspace/project qualified routing syntax in their project docstrings — matching the pattern edit_note already had.

Key changes (commit 9861e14):

File	Change
mcp/project_context.py	Added public compose_workspace_project_route() helper
mcp/tools/write_note.py	Added workspace param + docstring + route composition call
mcp/tools/read_note.py	Same
mcp/tools/delete_note.py	Same
mcp/tools/move_note.py	Same
mcp/tools/edit_note.py	Removed local duplicate; imports shared helper
tests/mcp/test_tool_edit_note.py	Updated to test compose_workspace_project_route from project_context
tests/mcp/test_tool_write_note.py	Added 6 new workspace validation/routing tests

Not addressed in this PR (marked as separate concern in the issue):

• Item 3 from the issue ("reconsider the silent default-workspace fallback on collisions") — changing the resolver's fallback behaviour is a more significant change to project_context.py:893-906 that warrants its own discussion/PR.

⚠️ The GitHub Actions token for this run doesn't have write permission to push to claude/issue-882-20260602-1500. A maintainer can pick up the changes from commit 9861e14.