---
title: "Migrating to 1.0"
description: "Update MCP clients, agent instructions, and integrations for the Basic Memory 1.0 tools."
canonical_url: "https://docs.basicmemory.com/reference/migrating-to-1-0"
---
# Migrating to 1.0

> Update MCP clients, agent instructions, and integrations for the Basic Memory 1.0 tools.

Basic Memory 1.0 replaces the MCP tools with the `bm_*` set. This page covers what changes for MCP clients, agent instructions, and integrations, and how to update them.

## MCP tools: migrate to the bm_* surface

Upgrade your
server and its agent packages together, then restart clients to refresh cached tool
schemas and permission lists. This does not rename the CLI's `bm tool` commands.

<table>
<thead>
  <tr>
    <th>
      Previous MCP tool
    </th>
    
    <th>
      1.0 replacement
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        read_note
      </code>
      
      , <code>
        read_content
      </code>
      
      , <code>
        view_note
      </code>
      
      , <code>
        cat
      </code>
    </td>
    
    <td>
      <code>
        bm_read
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        write_note
      </code>
    </td>
    
    <td>
      <code>
        bm_write
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        edit_note
      </code>
    </td>
    
    <td>
      <code>
        bm_edit
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search_notes
      </code>
      
      , <code>
        grep
      </code>
    </td>
    
    <td>
      <code>
        bm_search
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        build_context
      </code>
    </td>
    
    <td>
      <code>
        bm_context
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_directory
      </code>
      
      , <code>
        ls
      </code>
    </td>
    
    <td>
      <code>
        bm_list
      </code>
      
       for one level; <code>
        bm_find
      </code>
      
       for recursive inventory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        find
      </code>
    </td>
    
    <td>
      <code>
        bm_find
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        recent_activity
      </code>
    </td>
    
    <td>
      <code>
        bm_project(command="recent")
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_memory_projects
      </code>
      
      , <code>
        list_workspaces
      </code>
    </td>
    
    <td>
      <code>
        bm_project(command="list")
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        create_memory_project
      </code>
    </td>
    
    <td>
      <code>
        bm_project(command="create", name=..., path=...)
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        delete_project
      </code>
    </td>
    
    <td>
      <code>
        bm_project_delete
      </code>
      
       (opt-in)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema_validate
      </code>
      
      , <code>
        schema_infer
      </code>
      
      , <code>
        schema_diff
      </code>
    </td>
    
    <td>
      <code>
        bm_schema(command="validate"/"infer"/"diff")
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        move_note
      </code>
    </td>
    
    <td>
      <code>
        bm_move
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        delete_note
      </code>
    </td>
    
    <td>
      <code>
        bm_delete
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        man
      </code>
    </td>
    
    <td>
      <code>
        bm_man
      </code>
    </td>
  </tr>
</tbody>
</table>

### Change arguments and response handling too

- Pass names, workspace-qualified names, or external UUIDs through `project`.
Remove `project_id`; calls do not retain a selected project between requests.
- Search uses `mode`, `filters`, `items`, `since`, and `all_projects` instead of
`search_type`, `metadata_filters`, `entity_types`, `after_date`, and
`search_all_projects`. Use `items=["note"]` for whole notes. Put `tags` and
`status` inside `filters`; `note_types` still filters frontmatter types.
- Edit uses `command` instead of `operation`. `set_metadata` edits frontmatter;
edits never create missing notes.
- Context uses `identifier` instead of `url` and `since` instead of `timeframe`.
It defaults to JSON and a seven-day window. Depth is bounded to 1–5.
- Recent activity uses `command="recent"` and `since`. JSON returns an object
with `results` and paging fields, rather than a bare array.
- Project discovery returns project rows with workspace fields. It does not return
the old standalone workspace role/subscription response.
- Reads use `start_line`, `end_line`, `section`, or `max_tokens`; `page` and
`page_size` do not slice note content. JSON reads include frontmatter by default;
pass `include_frontmatter=False` when a consumer needs the body alone.
- Move uses `destination`. End a folder destination with `/` to preserve the file
name. JSON move/delete receipts identify success through `action` (`moved` or
`deleted`), rather than boolean `moved`/`deleted` fields.
- Refusals set MCP `isError`. JSON error text contains `error`, `message`, and
sometimes `try_instead`. Handle `NOT_FOUND`, `ALREADY_EXISTS`, and
`REVISION_CONFLICT`; do not treat them as successful empty results or expect
legacy `NOTE_*` payload fields. Read again to obtain the current checksum.

For an overwrite, prefer the exact returned `file_path` as `identifier` and pass
`expected_checksum` from a fresh read. Do not reconstruct a filename from a title.

```python
note = await bm_read(identifier="notes/Plan.md", project="research", output_format="json")
await bm_write(
    identifier=note["file_path"],
    content="Updated plan.",
    overwrite=True,
    expected_checksum=note["checksum"],
    project="research",
)
await bm_search(filters={"status": "active", "tags": ["planning"]}, project="research")
await bm_project(command="recent", since="7d", project="research", output_format="json")
```

### Update callers and installed instructions

Update custom agents, hooks, MCP allowlists, tool routers, recorded request fixtures,
and test fakes as well as prompts and skills. Native Hermes and OpenClaw wrappers
may retain their host-facing arguments while translating to the new MCP contract.
Tau preserves the core `bm_` prefix; there is no `bm_bm_write` tool.

Use `bm_man(page="bm-search(3)")` or `bm man bm-search` for the installed reference.
Re-run benchmark baselines after upgrading; historical results describe the tool
surface they were measured against and should not be relabeled as 1.0 results.


## Sitemap

See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.