docs: migrate guides and reference to 1.0 MCP tools

CLAUDE.md

@@ -15,7 +15,7 @@ This is the documentation website for Basic Memory (`docs.basicmemory.com`), bui
 **Current Version**: v0.24.1 (released October 2026)
 
 **Key Features**:
-- 17 MCP tools for AI integration (write_note, read_note, edit_note, search_notes, build_context, etc.)
+- Twelve core 1.0 MCP tools (`bm_read`, `bm_write`, `bm_edit`, `bm_search`, `bm_context`, etc.); reference pages are being prepared ahead of release
 - Local markdown files create a semantic knowledge graph
 - Multi-project support with project switching
 - Integrations with Claude Desktop, VS Code, Cursor, Obsidian
@@ -62,7 +62,7 @@ This documentation site covers both:
 1. **Basic Memory** (local-first product) - Installation, MCP tools, CLI, integrations, knowledge format
 2. **Basic Memory Cloud** (upcoming) - Cloud-specific features, authentication, sync, billing
 
-The site documents the latest v0.24.x release and includes cloud product documentation.
+Release history documents v0.24.x. Current MCP reference pages target the upcoming 1.0 surface and must state that status. Hosted extension documentation retains its separately advertised contract.
 
 ## Development Commands
 

content/01.start-here/1.what-is-basic-memory.md

@@ -3,6 +3,10 @@ title: What is Basic Memory
 description: An overview of what Basic Memory is and how it works.
 ---
 
+::note
+MCP examples on this page target the upcoming 1.0 tools. Check your server’s tool list before switching; see [Migrating to 1.0](/reference/migrating-to-1-0).
+::
+
 Basic Memory is real memory for your AI — a knowledge base you own. It stores notes as plain Markdown files, so your work stays readable, portable, and searchable.
 
 Instead of losing valuable insights in conversation history, you build a persistent knowledge base that every AI tool you use can read, write, and enhance — Claude, ChatGPT, Codex, OpenClaw, Hermes, and all your team's agents, working from one shared memory.
@@ -65,7 +69,7 @@ Use the hosted cloud service or run everything locally - your choice.
 
 ## How it works
 
-Basic Memory stores your notes as Markdown files and keeps a search index over them. Your AI assistant connects through MCP and calls tools like `search_notes`, `read_note`, and `write_note` to work with your notes.
+Basic Memory stores your notes as Markdown files and keeps a search index over them. Your AI assistant connects through MCP and calls tools like `bm_search`, `bm_read`, and `bm_write` to work with your notes.
 
 ::mermaid
 ---
@@ -191,9 +195,9 @@ When you ask a question, the AI doesn't just return one note. It traverses the g
 ---
 code: |
   flowchart LR
-      Q[Your question] --> S[search_notes]
+      Q[Your question] --> S[bm_search]
       S --> M[Matching notes]
-      M --> B[build_context]
+      M --> B[bm_context]
       B --> R[Related notes]
       R --> C[Full context]
       C --> A[AI answer]
@@ -203,7 +207,7 @@ code: |
 **The flow:**
 
 1. **Search** - Your question triggers a search across all notes
-2. **Expand** - The AI uses `build_context` to follow relations and gather connected notes
+2. **Expand** - The AI uses `bm_context` to follow relations and gather connected notes
 3. **Synthesize** - With the full context loaded, the AI can give a complete answer
 
 This recursive traversal means asking about "API authentication" automatically pulls in related decisions, dependencies, and connected topics - giving your AI the full picture.
@@ -334,13 +338,14 @@ The open-source local version provides:
 Basic Memory uses the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to connect with AI assistants. MCP is an open standard that lets AI assistants use external tools.
 
 **Available tools:**
-- `write_note` - Create or update notes
-- `read_note` - Read notes with context
-- `search_notes` - Full-text and semantic search
-- `edit_note` - Incremental editing
-- `build_context` - Load related notes
-- `list_memory_projects` - List your projects
-- `cat`, `grep`, `ls`, `find`, `tail`, `man` - Familiar read-only tools for browsing notes like files
+- `bm_write` - Create or update notes
+- `bm_read` - Read notes with context
+- `bm_search` - Full-text and semantic search
+- `bm_edit` - Incremental editing
+- `bm_context` - Load related notes
+- `bm_project(command="list")` - List your projects
+- `bm_list` and `bm_find` - Browse directories and discover paths
+- `bm_man` - Read or search the built-in manual
 - ...and many more
 
 **Compatible assistants:**

content/01.start-here/2.quickstart-cloud.md

@@ -3,6 +3,10 @@ title: "Quickstart: Cloud"
 description: Connect Basic Memory Cloud and create your first note in 2 minutes.
 ---
 
+::note
+MCP examples on this page target the upcoming 1.0 tools. Check your server’s tool list before switching; see [Migrating to 1.0](/reference/migrating-to-1-0).
+::
+
 Basic Memory Cloud gives you a hosted MCP endpoint and a web app. Connect your AI assistant and start writing notes in minutes - no installation required.
 
 ::docs-video{src="/videos/docs-quickstart.mp4" poster="/videos/posters/docs-quickstart.png" alt="Meet your workspace and write your first notes"}
@@ -108,15 +112,15 @@ Try this prompt:
 Create a note called "My First Note" with a summary of what Basic Memory does.
 ```
 
-Your assistant will use the `write_note` tool to create a Markdown file in your cloud storage.
+Your assistant will use the `bm_write` tool to create a Markdown file in your cloud storage.
 
 **Example conversation:**
 ```bash
 You: Create a note called "My First Note" with a summary of what Basic Memory does.
 
 AI: I'll create a note summarizing Basic Memory for you.
 
-[Uses write_note tool]
+[Uses bm_write tool]
 
 I've created "My First Note" in your knowledge base. The note covers:
 - What Basic Memory is
@@ -186,7 +190,7 @@ AI: [Searches knowledge base, finds your pour-over note]
 
 You: "Add a section about water temperature to my coffee notes"
 
-AI: [Uses edit_note to append new content]
+AI: [Uses bm_edit to append new content]
 ```
 
 ---

content/01.start-here/3.quickstart-local.md

@@ -3,6 +3,10 @@ title: "Quickstart: Local"
 description: Install Basic Memory locally and connect it to your AI assistant.
 ---
 
+::note
+MCP examples on this page target the upcoming 1.0 tools. Check your server’s tool list before switching; see [Migrating to 1.0](/reference/migrating-to-1-0).
+::
+
 Local mode keeps notes on your machine and runs the MCP server locally. It's open-source and free to use.
 
 ::mermaid
@@ -114,7 +118,7 @@ You: Create a note called "My First Note" with a summary of what Basic Memory do
 
 Claude: I'll create a note for you.
 
-[Uses write_note tool]
+[Uses bm_write tool]
 
 Done! I've created "My First Note.md" in your basic-memory folder.
 It includes an overview of Basic Memory's key features:
@@ -193,7 +197,7 @@ Claude: [Searches knowledge base]
 
 You: "Add a section about rate limiting"
 
-Claude: [Uses edit_note to append]
+Claude: [Uses bm_edit to append]
 "I've added a rate limiting section to your API design notes."
 ```
 

content/03.cloud/01.cloud-guide.md

@@ -3,6 +3,10 @@ title: Basic Memory Cloud
 description: Cloud remote MCP setup, web editor, CLI tools, and snapshots for Basic Memory Cloud.
 ---
 
+::note
+MCP examples on this page target the upcoming 1.0 tools. Check your server’s tool list before switching; see [Migrating to 1.0](/reference/migrating-to-1-0).
+::
+
 Basic Memory Cloud provides hosted MCP access with no local installation required. Bring your knowledge to the cloud - all your existing notes, connections, and context accessible from anywhere.
 
 ::docs-video{src="/videos/hero.mp4" poster="/videos/posters/hero.png" alt="What Basic Memory is, in one minute"}
@@ -133,7 +137,7 @@ A configured local sync directory is **kept** unless you pass `--delete-local-fi
 
 Hosted deletion is asynchronous: the project is hidden from cloud workspace operations when deletion is accepted, then a background job removes its database rows and every object under the project's storage prefix.
 
-The MCP `delete_project` tool on a cloud route also always deletes the project's cloud files. From a local stdio MCP session, pass `workspace` to route the request to that cloud workspace. Its `delete_notes` parameter applies only to local projects. MCP deletion never removes a local sync directory; use `bm project remove --delete-local-files` when you want both copies gone. The MCP response reports the pending deletion status and background job ID.
+The MCP `bm_project_delete` tool on a cloud route also always deletes the project's cloud files. From a local stdio MCP session, pass `workspace` to route the request to that cloud workspace. Its `delete_notes` parameter applies only to local projects. MCP deletion never removes a local sync directory; use `bm project remove --delete-local-files` when you want both copies gone. The MCP response reports the pending deletion status and background job ID.
 
 ---
 

content/03.cloud/05.cloud-sync.md

@@ -3,6 +3,10 @@ title: Cloud Sync Guide
 description: Guide to syncing your local Basic Memory projects with Basic Memory Cloud.
 ---
 
+::note
+MCP examples on this page target the upcoming 1.0 tools. Check your server’s tool list before switching; see [Migrating to 1.0](/reference/migrating-to-1-0).
+::
+
 The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using **project-scoped synchronization**. Each project can optionally sync with the cloud, giving you fine-grained control over what syncs and where.
 
 ---
@@ -267,7 +271,7 @@ bm cloud pull --name research --on-conflict keep-both
 | `bm cloud bisync --name research` | `bm cloud pull --name research`, then `bm cloud push --name research` |
 | `bm cloud bisync-reset research` | Nothing — `pull`/`push` keep no baseline to reset |
 
-`push` never deletes cloud files. To remove cloud files that match a newly added `.bmignore` pattern, use `bm cloud prune` (below). To delete individual notes, delete them in the [web app](/cloud/web-app) or with the `delete_note` MCP tool.
+`push` never deletes cloud files. To remove cloud files that match a newly added `.bmignore` pattern, use `bm cloud prune` (below). To delete individual notes, delete them in the [web app](/cloud/web-app) or with the `bm_delete` MCP tool.
 
 ::warning
 Until it is removed, `bm cloud sync` still deletes a previously synced cloud file when it becomes ignored by `.bmignore` (v0.23 behavior). Preview with `--dry-run` if you still run it.

content/03.cloud/08.api-keys.md

@@ -3,6 +3,10 @@ title: API Keys
 description: Create API keys for programmatic access to Basic Memory Cloud without OAuth.
 ---
 
+::note
+MCP examples on this page target the upcoming 1.0 tools. Check your server’s tool list before switching; see [Migrating to 1.0](/reference/migrating-to-1-0).
+::
+
 API keys provide an alternative to OAuth for authenticating with Basic Memory Cloud. Use them for CLI tools, automation scripts, or any MCP client that supports bearer token authentication.
 
 ---
@@ -151,7 +155,7 @@ If you suspect a key has been compromised, revoke it immediately and create a ne
 
 ## Read-only keys
 
-A read-only key can run every read operation — search, read, `build_context`, project status — and is refused on any write. Write tools (`write_note`, `edit_note`, `move_note`, `delete_note`) return an MCP tool error (`isError`) saying the key is read-only, so a client never mistakes a refused write for a saved one.
+A read-only key can run every read operation — search, read, `bm_context`, project status — and is refused on any write. Write tools (`bm_write`, `bm_edit`, `bm_move`, `bm_delete`) return an MCP tool error (`isError`) saying the key is read-only, so a client never mistakes a refused write for a saved one.
 
 ::note
 Use Basic Memory v0.24 or later with read-only keys. Earlier CLI and local MCP versions checked project status with a `POST` request, so a read-only key could get "This API key is read-only" on an ordinary search that returned no results.

content/04.teams/4.team-projects.md

@@ -3,6 +3,10 @@ title: Team Projects
 description: Team and invite-only project access, and working with team projects from the app, MCP, and CLI.
 ---
 
+::note
+MCP examples on this page target the upcoming 1.0 tools. Check your server’s tool list before switching; see [Migrating to 1.0](/reference/migrating-to-1-0).
+::
+
 Projects are how a team organizes its knowledge base. Every project in a team workspace has an access level, and every member's reach into it follows their [role](/teams/members-and-roles).
 
 ---
@@ -77,7 +81,7 @@ bm cloud workspace list
 bm cloud workspace set-default acme
 ```
 
-You can also target a specific workspace when creating a project, either from the CLI (`--workspace`) or from MCP (`create_memory_project(workspace="acme")`).
+You can also target a specific workspace when creating a project, either from the CLI (`--workspace`) or from MCP (`bm_project(command="create", workspace="acme")`).
 
 ### Targeting a team project explicitly
 

content/04.teams/5.join-a-team.md

@@ -3,6 +3,10 @@ title: Joining a Team Workspace
 description: First-time setup for new team members — accept the invite, sign in, switch workspaces, and connect your AI assistant to the shared knowledge base.
 ---
 
+::note
+MCP examples on this page target the upcoming 1.0 tools. Check your server’s tool list before switching; see [Migrating to 1.0](/reference/migrating-to-1-0).
+::
+
 You got an invite to a Basic Memory [team workspace](/teams/about). This page walks through what to do on day one — accept the invite, get into the workspace, find the shared projects, and point your AI assistant at the same knowledge base.
 
 ::note
@@ -62,7 +66,7 @@ bm cloud workspace set-default acme
 bm project list --workspace acme
 ```
 
-From MCP, pass the workspace through `create_memory_project(workspace="acme")`, or reference notes with a workspace-qualified memory URL — `memory://acme/research/note-title`. See [Team Projects](/teams/team-projects) for the full targeting guide.
+From MCP, pass the workspace through `bm_project(command="create", workspace="acme")`, or reference notes with a workspace-qualified memory URL — `memory://acme/research/note-title`. See [Team Projects](/teams/team-projects) for the full targeting guide.
 
 ---
 

content/04.teams/6.copy-between-workspaces.md

@@ -3,6 +3,10 @@ title: Copy Content Between Workspaces
 description: Move notes, folders, or whole projects between personal, team, and local workspaces using export/import or MCP.
 ---
 
+::note
+MCP examples on this page target the upcoming 1.0 tools. Check your server’s tool list before switching; see [Migrating to 1.0](/reference/migrating-to-1-0).
+::
+
 You'll often want to promote work from your personal workspace into a [team workspace](/teams/about), or pull team content back into a personal one. Today, this is a **copy-then-(optionally)-delete** workflow rather than an atomic move — you export from the source, import into the target, verify, and only then remove the original if you wanted a true move.
 
 ::note{icon="i-lucide-info"}
@@ -84,16 +88,16 @@ Remove the originals from the source project once you're satisfied.
 MCP doesn't expose an atomic cross-project or cross-workspace move. Express it as **read → write → (optionally) delete** instead. Your AI assistant can drive this for you, or you can run the tools directly.
 
 ```text
-read_note("source note", project="source-project")
-write_note("Note Title", "<content from read_note>", "target-folder", project="target-project")
-delete_note("source note", project="source-project")   # optional, only after verifying
+bm_read("source note", project="source-project")
+bm_write(title="Note Title", content="<content from bm_read>", directory="target-folder", project="target-project")
+bm_delete("source note", project="source-project")   # optional, only after verifying
 ```
 
 A few notes on this pattern:
 
 - Pass `project` on each call so the read and write hit the right place. In a team setup, use a [project-prefixed permalink](/concepts/memory-urls) or workspace-qualified routing to be unambiguous.
 - For many notes, loop the read/write pair — there's no batch move, but the pattern is straightforward to script.
-- Don't `delete_note` until the new copy is in place and verified. Treat this as **copy-then-optional-delete**, never as a transactional move.
+- Don't `bm_delete` until the new copy is in place and verified. Treat this as **copy-then-optional-delete**, never as a transactional move.
 
 See the [MCP Tools Reference](/reference/mcp-tools-reference) for full parameter details on each tool.
 
@@ -114,7 +118,7 @@ This is the fastest option when you have lots of notes and both projects already
 
 ## What about renaming or restructuring?
 
-Within a single workspace, you can rename and move notes and folders freely from the app or with `move_note`. Cross-workspace, do the copy first, then reorganize on the target side.
+Within a single workspace, you can rename and move notes and folders freely from the app or with `bm_move`. Cross-workspace, do the copy first, then reorganize on the target side.
 
 ---
 
@@ -124,4 +128,4 @@ Within a single workspace, you can rename and move notes and folders freely from
 - [Web App](/cloud/web-app) — projects, downloads, and imports
 - [Cloud Sync](/cloud/cloud-sync) — push/pull sync setup
 - [Shared Notes](/cloud/shared-notes) — public links for individual notes
-- [MCP Tools Reference](/reference/mcp-tools-reference) — `read_note`, `write_note`, `delete_note`
+- [MCP Tools Reference](/reference/mcp-tools-reference) — `bm_read`, `bm_write`, `bm_delete`

content/06.local/2.getting-started.md

@@ -40,7 +40,7 @@ Create a new project called "my project" in the "/Users/yourname/Documents/Notes
 Then:
 
 ```text
-Set the default project to "my project"
+Use "my project" for subsequent notes and searches.
 ```
 
 Or use the command line:
@@ -54,7 +54,7 @@ basic-memory project default "my project"
 ```
 
 ::warning
-If you change default projects from the command line, new notes will be saved in your chosen folder after restarting Claude Desktop.
+With the upcoming 1.0 tools, multiple addressable projects require the assistant to pass `project` or a project-qualified target on note and search calls. Changing the CLI default does not replace that explicit scope.
 ::
 
 **Want to use Obsidian?** Just open your folder location as a vault. See the [Obsidian Integration](/integrations/obsidian) guide.
@@ -75,7 +75,7 @@ When you start a conversation, the AI will:
 1. Check your available projects
 2. Suggest the most active project based on recent activity
 3. Ask which project to use for this conversation
-4. Remember your choice throughout the session
+4. Pass your chosen project on subsequent tool calls
 
 **Example:**
 ```text
@@ -99,13 +99,13 @@ You: "Create a new project called 'work-notes' in ~/Documents/work"
 
 **For users who primarily work in one project:**
 
-Set a default fallback project — it's the same setting the command above writes:
+Set a default for CLI commands that support fallback — it's the same setting the command above writes:
 
 ```bash
 basic-memory project default "main"
 ```
 
-With this set, the AI uses your default project when no project is specified.
+For 1.0 MCP note and search calls, the assistant still names the project when several are addressable. To constrain an MCP session to one project, start the server with `basic-memory mcp --project main`; see the [User Guide](/local/user-guide#single-project-mode-locked).
 
 ---