Skip to content

fix(mcp): resolve projects by external_id, remove workspace from MCP tools #777

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
phernandez merged 5 commits into from
May 1, 2026
Merged

fix(mcp): resolve projects by external_id, remove workspace from MCP tools #777

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4915e13
Resolve projects by external_id, remove workspace from MCP tools
phernandez Apr 30, 2026
4e8a62b
Remove workspace param from CLI tool commands, fix formatting
phernandez Apr 30, 2026
25be29e
Add project_id parameter to MCP tools for cloud workspace disambiguation
phernandez May 1, 2026
6c7d7d5
Include external_id in create_memory_project response
phernandez May 1, 2026
03881f6
Add --project-id passthrough to CLI tool commands
phernandez May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion docs/ai-assistant-guide-extended.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,17 +91,19 @@ SQLite Database (Index)
# List all projects
projects = await list_memory_projects()

# Response structure:
# Response structure (each entry includes external_id you can pass as project_id):
# [
# {
# "name": "main",
# "external_id": "550e8400-e29b-41d4-a716-446655440000",
# "path": "/Users/name/notes",
# "is_default": True,
# "note_count": 156,
# "last_synced": "2025-01-15T10:30:00Z"
# },
# {
# "name": "work",
# "external_id": "9f86d081-884c-42a3-b5e3-1c0c5b4c8e52",
# "path": "/Users/name/work-notes",
# "is_default": False,
# "note_count": 89,
Expand Down Expand Up @@ -164,6 +166,44 @@ active_project = "main"
results = await search_notes(query="topic", project=active_project)
```

### `project` vs `project_id`

Every project has two identifiers:

- **`project`** — human-readable name (e.g., `"main"`). Easy to use, but can collide across cloud workspaces.
- **`project_id`** — stable `external_id` UUID. Always unambiguous; takes precedence over `project` when both are passed.

**When to prefer `project_id`:**

1. **Cloud multi-workspace setups.** If the user belongs to more than one workspace (personal + organization, or several organizations) and the same project name might exist in more than one of them, pass `project_id` to route to the exact project. Without it, name resolution falls back to the default workspace, which may not be the one the user means.
2. **After `list_memory_projects()`.** Once you have the `external_id`, prefer using it — it's the same number of characters in JSON and saves a name-resolution round-trip.
3. **When persisting a project choice across a long session.** UUIDs are stable; names can be renamed.

**When `project` (name) is fine:**

- Local single-workspace setups (no collision risk).
- One-off operations where the name is clearly visible to the user (e.g., quick `search_notes(project="main", ...)`).
- The user explicitly references a project by name in their message.

**Example — cloud multi-workspace pattern:**

```python
# Discover and pick the right project for this user
projects = await list_memory_projects()
target = next(p for p in projects if p["name"] == "research" and p["workspace"]["slug"] == "acme")

# Use the UUID for all subsequent operations — no ambiguity
await write_note(
title="Meeting Notes",
content="...",
folder="meetings",
project_id=target["external_id"],
)
results = await search_notes(query="kickoff", project_id=target["external_id"])
```

**Precedence rule:** When both are passed, `project_id` wins. This lets you safely supply `project="main"` for backward compatibility while still routing precisely with `project_id`.

### Cross-Project Operations

**Some tools work across all projects when project parameter omitted:**
Expand Down
8 changes: 2 additions & 6 deletions src/basic_memory/cli/commands/db.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,7 @@ def _abort_if_mcp_processes_alive() -> None:
if not zombies:
return

console.print(
"[red]Refusing to reset:[/red] basic-memory MCP processes are still running."
)
console.print("[red]Refusing to reset:[/red] basic-memory MCP processes are still running.")
console.print(
"[yellow]On macOS/Linux these would keep reading the deleted memory.db inode "
"and return phantom search results (see #765).[/yellow]"
Expand All @@ -117,9 +115,7 @@ def _abort_if_mcp_processes_alive() -> None:
"Where-Object {$_.CommandLine -like '*basic-memory*mcp*'}[/green]"
)
else:
console.print(
" 2. Verify nothing remains: [green]pgrep -fa 'basic-memory mcp'[/green]"
)
console.print(" 2. Verify nothing remains: [green]pgrep -fa 'basic-memory mcp'[/green]")
console.print(" 3. Re-run [green]bm reset[/green].")
raise typer.Exit(1)

Expand Down
81 changes: 54 additions & 27 deletions src/basic_memory/cli/commands/tool.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,12 @@ def write_note(
help="The project to write to. If not provided, the default project will be used."
),
] = None,
workspace: Annotated[
project_id: Annotated[
Optional[str],
typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
typer.Option(
"--project-id",
help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
),
] = None,
local: bool = typer.Option(
False, "--local", help="Force local API routing (ignore cloud mode)"
Expand Down Expand Up @@ -106,7 +109,7 @@ def write_note(
content=content,
directory=folder,
project=project,
Comment on lines 109 to 111
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Add project_id passthrough to CLI tool commands

Removing --workspace from bm tool without adding a project_id alternative leaves these commands unable to disambiguate same-named projects across cloud workspaces. In multi-workspace accounts, project name resolution now falls back to the default workspace, so write-note (and the other wrappers following this pattern) can read/write the wrong tenant with no way for the CLI caller to force the intended project. Expose --project-id and forward it to the MCP tool call.

Useful? React with 👍 / 👎.

workspace=workspace,
project_id=project_id,
tags=tags,
output_format="json",
)
Expand All @@ -132,9 +135,12 @@ def read_note(
Optional[str],
typer.Option(help="The project to use. If not provided, the default project will be used."),
] = None,
workspace: Annotated[
project_id: Annotated[
Optional[str],
typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
typer.Option(
"--project-id",
help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
),
] = None,
local: bool = typer.Option(
False, "--local", help="Force local API routing (ignore cloud mode)"
Expand All @@ -156,7 +162,7 @@ def read_note(
mcp_read_note(
identifier=identifier,
project=project,
workspace=workspace,
project_id=project_id,
include_frontmatter=include_frontmatter,
output_format="json",
)
Expand Down Expand Up @@ -195,9 +201,12 @@ def edit_note(
help="The project to edit. If not provided, the default project will be used."
),
] = None,
workspace: Annotated[
project_id: Annotated[
Optional[str],
typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
typer.Option(
"--project-id",
help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
),
] = None,
local: bool = typer.Option(
False, "--local", help="Force local API routing (ignore cloud mode)"
Expand All @@ -222,7 +231,7 @@ def edit_note(
operation=operation,
content=content,
project=project,
workspace=workspace,
project_id=project_id,
section=section,
find_text=find_text,
expected_replacements=expected_replacements,
Expand Down Expand Up @@ -260,9 +269,12 @@ def build_context(
Optional[str],
typer.Option(help="The project to use. If not provided, the default project will be used."),
] = None,
workspace: Annotated[
project_id: Annotated[
Optional[str],
typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
typer.Option(
"--project-id",
help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
),
] = None,
local: bool = typer.Option(
False, "--local", help="Force local API routing (ignore cloud mode)"
Expand All @@ -284,7 +296,7 @@ def build_context(
mcp_build_context(
url=url,
project=project,
workspace=workspace,
project_id=project_id,
depth=depth,
timeframe=timeframe,
page=page,
Expand Down Expand Up @@ -317,9 +329,12 @@ def recent_activity(
Optional[str],
typer.Option(help="The project to use. If not provided, the default project will be used."),
] = None,
workspace: Annotated[
project_id: Annotated[
Optional[str],
typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
typer.Option(
"--project-id",
help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
),
] = None,
local: bool = typer.Option(
False, "--local", help="Force local API routing (ignore cloud mode)"
Expand All @@ -346,7 +361,7 @@ def recent_activity(
page=page,
page_size=page_size,
project=project,
workspace=workspace,
project_id=project_id,
output_format="json",
)
)
Expand Down Expand Up @@ -408,9 +423,12 @@ def search_notes(
Optional[str],
typer.Option(help="The project to use. If not provided, the default project will be used."),
] = None,
workspace: Annotated[
project_id: Annotated[
Optional[str],
typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
typer.Option(
"--project-id",
help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
),
] = None,
local: bool = typer.Option(
False, "--local", help="Force local API routing (ignore cloud mode)"
Expand Down Expand Up @@ -482,7 +500,7 @@ def search_notes(
mcp_search(
query=query or None,
project=project,
workspace=workspace,
project_id=project_id,
search_type=search_type,
output_format="json",
page=page,
Expand Down Expand Up @@ -592,9 +610,12 @@ def schema_validate(
Optional[str],
typer.Option(help="The project to use. If not provided, the default project will be used."),
] = None,
workspace: Annotated[
project_id: Annotated[
Optional[str],
typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
typer.Option(
"--project-id",
help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
),
] = None,
local: bool = typer.Option(
False, "--local", help="Force local API routing (ignore cloud mode)"
Expand Down Expand Up @@ -629,7 +650,7 @@ def schema_validate(
note_type=note_type,
identifier=identifier,
project=project,
workspace=workspace,
project_id=project_id,
output_format="json",
)
)
Expand Down Expand Up @@ -660,9 +681,12 @@ def schema_infer(
Optional[str],
typer.Option(help="The project to use. If not provided, the default project will be used."),
] = None,
workspace: Annotated[
project_id: Annotated[
Optional[str],
typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
typer.Option(
"--project-id",
help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
),
] = None,
local: bool = typer.Option(
False, "--local", help="Force local API routing (ignore cloud mode)"
Expand All @@ -686,7 +710,7 @@ def schema_infer(
note_type=note_type,
threshold=threshold,
project=project,
workspace=workspace,
project_id=project_id,
output_format="json",
)
)
Expand Down Expand Up @@ -714,9 +738,12 @@ def schema_diff(
Optional[str],
typer.Option(help="The project to use. If not provided, the default project will be used."),
] = None,
workspace: Annotated[
project_id: Annotated[
Optional[str],
typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
typer.Option(
"--project-id",
help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
),
] = None,
local: bool = typer.Option(
False, "--local", help="Force local API routing (ignore cloud mode)"
Expand All @@ -738,7 +765,7 @@ def schema_diff(
mcp_schema_diff(
note_type=note_type,
project=project,
workspace=workspace,
project_id=project_id,
output_format="json",
)
)
Expand Down
Loading
Loading