From 0aa7bb880daea627784db77c02f7a7381ad14e4f Mon Sep 17 00:00:00 2001 From: phernandez Date: Thu, 16 Jul 2026 01:40:38 -0500 Subject: [PATCH 1/9] docs: explain cloud project data purge Signed-off-by: phernandez --- content/03.cloud/01.cloud-guide.md | 22 +++++++++++++++++++ content/10.reference/1.cli-reference.md | 6 +++-- content/10.reference/2.mcp-tools-reference.md | 5 ++++- 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/content/03.cloud/01.cloud-guide.md b/content/03.cloud/01.cloud-guide.md index 8351aaa..272eaff 100644 --- a/content/03.cloud/01.cloud-guide.md +++ b/content/03.cloud/01.cloud-guide.md @@ -104,6 +104,28 @@ The full command walkthrough — sign-in options, API keys, workspaces, routing, --- +## Remove a Cloud Project and Its Data + +Cloud project removal keeps note files by default. Use `--delete-notes` when you also want to purge the project's active cloud storage: + +```bash +# Stop tracking the project, but retain its cloud files +bm project remove research --cloud + +# Remove the project and purge every object under its cloud storage prefix +bm project remove research --cloud --delete-notes +``` + +The `--cloud` flag is optional when `research` is already configured as a cloud-routed project. Hosted deletion is asynchronous: the project disappears from normal listings when deletion is accepted, then a background job removes its database rows. With `--delete-notes`, that job also removes indexed and unindexed objects under the project's exact storage prefix. + +The MCP `delete_project` tool provides the same behavior with `delete_notes=true`. Its response reports the pending deletion status and background job ID. + +::warning +Deleting with `--delete-notes` is irreversible for active project storage. Existing point-in-time snapshots may still contain historical copies until those snapshots are deleted or expire. +:: + +--- + ## Upload Files to Cloud ::note{icon="i-lucide-upload"} diff --git a/content/10.reference/1.cli-reference.md b/content/10.reference/1.cli-reference.md index 908d70d..f7bdbf0 100644 --- a/content/10.reference/1.cli-reference.md +++ b/content/10.reference/1.cli-reference.md @@ -244,7 +244,7 @@ bm project add research ~/Documents/research --default ### `bm project remove` -Remove a project from configuration. +Remove a project. Files are retained by default; pass `--delete-notes` to remove them too. ```bash bm project remove research @@ -253,10 +253,12 @@ bm project remove research --delete-notes | Flag | Description | |------|-------------| -| `--delete-notes` | Also delete project files from disk | +| `--delete-notes` | Also delete project files: local files for a local project, or all active objects under the project prefix for a cloud project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | +Cloud deletion is accepted asynchronously. Without `--delete-notes`, the project is removed from the hosted database but its cloud files remain. With `--delete-notes`, the background job purges indexed and unindexed objects under the exact project storage prefix before completing the hard delete. Existing cloud snapshots follow their own retention and deletion lifecycle. + ### `bm project default` Set the default project used as fallback when no project is specified. diff --git a/content/10.reference/2.mcp-tools-reference.md b/content/10.reference/2.mcp-tools-reference.md index 41ee0ca..85c06ad 100644 --- a/content/10.reference/2.mcp-tools-reference.md +++ b/content/10.reference/2.mcp-tools-reference.md @@ -202,13 +202,16 @@ Create a project. ### `delete_project` -Remove a project from Basic Memory config. +Remove a project from Basic Memory. Note files are retained by default. | Parameter | Type | Required | Notes | |---|---|---|---| | `project_name` | string | Yes | Name of the project to remove | +| `delete_notes` | boolean | No | Default `false`. Set to `true` to delete local files or purge every active cloud object under the project's storage prefix | | `workspace` | string | No | Cloud workspace selector when deleting from a specific workspace | +Hosted deletion is asynchronous. The tool response reports the project deletion status and background job ID when the cloud backend queues the work. With `delete_notes=false`, cloud objects are retained even though the project and its indexed database rows are removed. With `delete_notes=true`, the background job removes indexed and unindexed objects under the exact project prefix before completing the hard delete. Existing snapshots follow their separate retention lifecycle. + ### `list_directory` List directory contents with optional depth and glob filter. From 19ddf142d1b53e7e84a1c210d10a23c31c381c27 Mon Sep 17 00:00:00 2001 From: phernandez Date: Thu, 16 Jul 2026 01:47:12 -0500 Subject: [PATCH 2/9] docs: warn about local sync deletion Signed-off-by: phernandez --- content/10.reference/1.cli-reference.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/10.reference/1.cli-reference.md b/content/10.reference/1.cli-reference.md index f7bdbf0..31020dd 100644 --- a/content/10.reference/1.cli-reference.md +++ b/content/10.reference/1.cli-reference.md @@ -259,6 +259,10 @@ bm project remove research --delete-notes Cloud deletion is accepted asynchronously. Without `--delete-notes`, the project is removed from the hosted database but its cloud files remain. With `--delete-notes`, the background job purges indexed and unindexed objects under the exact project storage prefix before completing the hard delete. Existing cloud snapshots follow their own retention and deletion lifecycle. +::warning +For a cloud project configured with a local sync path, explicitly passing both `--cloud` and `--delete-notes` also removes that local sync directory. Back up any local files you need before running the command. +:: + ### `bm project default` Set the default project used as fallback when no project is specified. From 17b52530d2bc688778963d5c9c4e4eafd26c9c2e Mon Sep 17 00:00:00 2001 From: phernandez Date: Thu, 16 Jul 2026 02:10:39 -0500 Subject: [PATCH 3/9] docs: warn before deleting local cloud sync files Signed-off-by: phernandez --- content/03.cloud/01.cloud-guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/03.cloud/01.cloud-guide.md b/content/03.cloud/01.cloud-guide.md index 272eaff..1d94fd0 100644 --- a/content/03.cloud/01.cloud-guide.md +++ b/content/03.cloud/01.cloud-guide.md @@ -108,6 +108,10 @@ The full command walkthrough — sign-in options, API keys, workspaces, routing, Cloud project removal keeps note files by default. Use `--delete-notes` when you also want to purge the project's active cloud storage: +::warning +If the project has a configured local sync directory, `--cloud --delete-notes` also removes that local directory. Back up any local files you need before running the destructive command. Deletion is irreversible for active project storage; existing point-in-time snapshots may still contain historical copies until those snapshots are deleted or expire. +:: + ```bash # Stop tracking the project, but retain its cloud files bm project remove research --cloud @@ -120,10 +124,6 @@ The `--cloud` flag is optional when `research` is already configured as a cloud- The MCP `delete_project` tool provides the same behavior with `delete_notes=true`. Its response reports the pending deletion status and background job ID. -::warning -Deleting with `--delete-notes` is irreversible for active project storage. Existing point-in-time snapshots may still contain historical copies until those snapshots are deleted or expire. -:: - --- ## Upload Files to Cloud From 36218d5de306f72e787855e9a4c786f47214def8 Mon Sep 17 00:00:00 2001 From: phernandez Date: Thu, 16 Jul 2026 02:28:13 -0500 Subject: [PATCH 4/9] docs: clarify cloud deletion config entries Signed-off-by: phernandez --- content/03.cloud/01.cloud-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/03.cloud/01.cloud-guide.md b/content/03.cloud/01.cloud-guide.md index 1d94fd0..df47b2b 100644 --- a/content/03.cloud/01.cloud-guide.md +++ b/content/03.cloud/01.cloud-guide.md @@ -120,7 +120,7 @@ bm project remove research --cloud bm project remove research --cloud --delete-notes ``` -The `--cloud` flag is optional when `research` is already configured as a cloud-routed project. Hosted deletion is asynchronous: the project disappears from normal listings when deletion is accepted, then a background job removes its database rows. With `--delete-notes`, that job also removes indexed and unindexed objects under the project's exact storage prefix. +The `--cloud` flag is optional when `research` is already configured as a cloud-routed project. Hosted deletion is asynchronous: the project is hidden from cloud workspace operations when deletion is accepted, then a background job removes its database rows. A local routing or sync configuration entry can still appear as a config-only row in the combined `bm project list`; that does not mean the hosted project remains. With `--delete-notes`, the background job also removes indexed and unindexed objects under the project's exact storage prefix. The MCP `delete_project` tool provides the same behavior with `delete_notes=true`. Its response reports the pending deletion status and background job ID. From 20754bcaeac9ecf5fc9ed5388827fb5eebb210be Mon Sep 17 00:00:00 2001 From: phernandez Date: Thu, 16 Jul 2026 02:50:22 -0500 Subject: [PATCH 5/9] docs: require cloud flag for sync purge Signed-off-by: phernandez --- content/03.cloud/01.cloud-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/03.cloud/01.cloud-guide.md b/content/03.cloud/01.cloud-guide.md index df47b2b..c75b6d6 100644 --- a/content/03.cloud/01.cloud-guide.md +++ b/content/03.cloud/01.cloud-guide.md @@ -120,7 +120,7 @@ bm project remove research --cloud bm project remove research --cloud --delete-notes ``` -The `--cloud` flag is optional when `research` is already configured as a cloud-routed project. Hosted deletion is asynchronous: the project is hidden from cloud workspace operations when deletion is accepted, then a background job removes its database rows. A local routing or sync configuration entry can still appear as a config-only row in the combined `bm project list`; that does not mean the hosted project remains. With `--delete-notes`, the background job also removes indexed and unindexed objects under the project's exact storage prefix. +Keep the explicit `--cloud` flag on the destructive `--delete-notes` command so the CLI also removes any configured local sync directory. Omitting `--cloud` from a cloud-routed project still purges hosted storage, but leaves the local sync copy intact. Hosted deletion is asynchronous: the project is hidden from cloud workspace operations when deletion is accepted, then a background job removes its database rows. A local routing or sync configuration entry can still appear as a config-only row in the combined `bm project list`; that does not mean the hosted project remains. With `--delete-notes`, the background job also removes indexed and unindexed objects under the project's exact storage prefix. The MCP `delete_project` tool provides the same behavior with `delete_notes=true`. Its response reports the pending deletion status and background job ID. From 32522fd5b3d743e69a968795b27b5dfc7fa847d2 Mon Sep 17 00:00:00 2001 From: phernandez Date: Thu, 16 Jul 2026 02:59:37 -0500 Subject: [PATCH 6/9] docs: qualify MCP cloud delete routing Signed-off-by: phernandez --- content/10.reference/2.mcp-tools-reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/10.reference/2.mcp-tools-reference.md b/content/10.reference/2.mcp-tools-reference.md index 85c06ad..8ef7251 100644 --- a/content/10.reference/2.mcp-tools-reference.md +++ b/content/10.reference/2.mcp-tools-reference.md @@ -208,9 +208,9 @@ Remove a project from Basic Memory. Note files are retained by default. |---|---|---|---| | `project_name` | string | Yes | Name of the project to remove | | `delete_notes` | boolean | No | Default `false`. Set to `true` to delete local files or purge every active cloud object under the project's storage prefix | -| `workspace` | string | No | Cloud workspace selector when deleting from a specific workspace | +| `workspace` | string | No | Cloud workspace selector. From a local stdio MCP session, provide this to route deletion to cloud unless the session is already explicitly cloud-routed | -Hosted deletion is asynchronous. The tool response reports the project deletion status and background job ID when the cloud backend queues the work. With `delete_notes=false`, cloud objects are retained even though the project and its indexed database rows are removed. With `delete_notes=true`, the background job removes indexed and unindexed objects under the exact project prefix before completing the hard delete. Existing snapshots follow their separate retention lifecycle. +Cloud purge behavior applies when the MCP session is hosted or factory-routed to cloud, explicitly cloud-routed, or given a `workspace` selector. From a local stdio MCP session, `delete_notes=true` alone does not switch this tool to cloud routing; pass `workspace` to ensure the hosted project and objects are targeted. Hosted deletion is asynchronous. The tool response reports the project deletion status and background job ID when the cloud backend queues the work. With `delete_notes=false`, cloud objects are retained even though the project and its indexed database rows are removed. With `delete_notes=true`, the background job removes indexed and unindexed objects under the exact project prefix before completing the hard delete. Existing snapshots follow their separate retention lifecycle. ### `list_directory` From 6651169f42a45cde346dadfe3eaa6a94cd4f7e36 Mon Sep 17 00:00:00 2001 From: phernandez Date: Thu, 16 Jul 2026 03:08:16 -0500 Subject: [PATCH 7/9] docs: clarify MCP local sync retention Signed-off-by: phernandez --- content/03.cloud/01.cloud-guide.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/03.cloud/01.cloud-guide.md b/content/03.cloud/01.cloud-guide.md index c75b6d6..0df7322 100644 --- a/content/03.cloud/01.cloud-guide.md +++ b/content/03.cloud/01.cloud-guide.md @@ -122,7 +122,10 @@ bm project remove research --cloud --delete-notes Keep the explicit `--cloud` flag on the destructive `--delete-notes` command so the CLI also removes any configured local sync directory. Omitting `--cloud` from a cloud-routed project still purges hosted storage, but leaves the local sync copy intact. Hosted deletion is asynchronous: the project is hidden from cloud workspace operations when deletion is accepted, then a background job removes its database rows. A local routing or sync configuration entry can still appear as a config-only row in the combined `bm project list`; that does not mean the hosted project remains. With `--delete-notes`, the background job also removes indexed and unindexed objects under the project's exact storage prefix. -The MCP `delete_project` tool provides the same behavior with `delete_notes=true`. Its response reports the pending deletion status and background job ID. +The MCP `delete_project` tool provides the same hosted-storage purge with +`delete_notes=true`. It does not remove a configured local sync directory; use the explicit +CLI command above when you need to delete both copies. The MCP response reports the pending +deletion status and background job ID. --- From 4c3f29a86472f6b6762d4cb694e669631a681658 Mon Sep 17 00:00:00 2001 From: phernandez Date: Thu, 16 Jul 2026 03:15:21 -0500 Subject: [PATCH 8/9] docs: qualify cloud sync deletion flags Signed-off-by: phernandez --- content/10.reference/1.cli-reference.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/content/10.reference/1.cli-reference.md b/content/10.reference/1.cli-reference.md index 31020dd..980ac7e 100644 --- a/content/10.reference/1.cli-reference.md +++ b/content/10.reference/1.cli-reference.md @@ -244,11 +244,19 @@ bm project add research ~/Documents/research --default ### `bm project remove` -Remove a project. Files are retained by default; pass `--delete-notes` to remove them too. +Remove a project. Files are retained by default; pass `--delete-notes` to remove them too. For +a cloud project with a configured local sync directory, also pass `--cloud` to remove both the +hosted objects and that local copy. ```bash +# Stop tracking a project while retaining its files bm project remove research + +# Delete a local project's files bm project remove research --delete-notes + +# Purge cloud storage and remove any configured local sync directory +bm project remove research --cloud --delete-notes ``` | Flag | Description | From 96aa925b8912a717bf4835bd74a709e1c20d2ac4 Mon Sep 17 00:00:00 2001 From: phernandez Date: Thu, 16 Jul 2026 09:06:11 -0500 Subject: [PATCH 9/9] docs: qualify MCP cloud deletion routing Signed-off-by: phernandez --- content/03.cloud/01.cloud-guide.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/content/03.cloud/01.cloud-guide.md b/content/03.cloud/01.cloud-guide.md index 0df7322..c9f3064 100644 --- a/content/03.cloud/01.cloud-guide.md +++ b/content/03.cloud/01.cloud-guide.md @@ -123,9 +123,12 @@ bm project remove research --cloud --delete-notes Keep the explicit `--cloud` flag on the destructive `--delete-notes` command so the CLI also removes any configured local sync directory. Omitting `--cloud` from a cloud-routed project still purges hosted storage, but leaves the local sync copy intact. Hosted deletion is asynchronous: the project is hidden from cloud workspace operations when deletion is accepted, then a background job removes its database rows. A local routing or sync configuration entry can still appear as a config-only row in the combined `bm project list`; that does not mean the hosted project remains. With `--delete-notes`, the background job also removes indexed and unindexed objects under the project's exact storage prefix. The MCP `delete_project` tool provides the same hosted-storage purge with -`delete_notes=true`. It does not remove a configured local sync directory; use the explicit -CLI command above when you need to delete both copies. The MCP response reports the pending -deletion status and background job ID. +`delete_notes=true` when the MCP session is hosted or explicitly cloud-routed. From a local +stdio MCP session, also pass `workspace` to route the request to that cloud workspace; +`delete_notes=true` alone does not switch a local request to Cloud. MCP deletion does not +remove a configured local sync directory, so use the explicit CLI command above when you need +to delete both copies. The MCP response reports the pending deletion status and background +job ID. ---