---
title: "MCP tools (local)"
description: "Use MCP tools against local projects."
canonical_url: "https://docs.basicmemory.com/local/mcp-tools-local"
---
# MCP tools (local)

> Use MCP tools against local projects.

MCP tools are the same in Cloud and Local. In local mode, they operate on folders on your machine.

## Use tools in local mode

Once your MCP client runs the local server (see [Local install](https://docs.basicmemory.com/local/local-install#connect-your-mcp-client)), tools read and write your local project folders — unless you've routed a project through cloud with [per-project routing](https://docs.basicmemory.com/cloud/routing).

## Common tools

- `bm_search` to find notes (keyword, semantic, and hybrid search)
- `bm_read` to load a note
- `bm_write` to create or update a note
- `bm_edit` to append or replace sections
- `bm_schema(command="validate")`, `bm_schema(command="infer")`, `bm_schema(command="diff")` for schema workflows
- `bm_context` for graph traversal via [memory:// URLs](https://docs.basicmemory.com/concepts/memory-urls)

Most tools default to `output_format="text"` (human-readable) and also accept `"json"` (machine-readable); `bm_context` defaults to `"json"` — see the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference) for per-tool defaults.

## Navigation and project routing

The 1.0 MCP surface consolidates the old rich and POSIX tools. Use `bm_list` for one directory level, `bm_find` for recursive paths or frontmatter queries, `bm_search` for ranked results and matching lines, and `bm_read` for full or sliced content.

```python
bm_list(path="/")
bm_find(path="research", filters={"status": "active"})
bm_search(query="retry", project="main", mode="text", lines=3)
bm_read(identifier="research/specs/auth.md", section="Decisions")
```

Pass `project` as a name, workspace-qualified name, or UUID, or use a project-qualified target such as `research/notes/topic.md`. When several projects are addressable, unqualified note and search calls are refused even if a default project is configured. With only one addressable project, the tools can use it implicitly. A server constrained with `BASIC_MEMORY_MCP_PROJECT` stays in that project. The legacy `enable_posix_tools` setting does not hide the new `bm_*` tools.

## Semantic search

Semantic search is always on in v0.24; the old `semantic_search_enabled` setting is ignored. The first run downloads a small local embedding model and builds vectors for your notes. If the vector runtime cannot load on your Python build (for example python.org Python on macOS), search falls back to keyword-only. See [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search).

## Example

```python
bm_search(query="architecture", project="main")
```

<tip>

Each tool has a manual page built in. Ask your assistant to read `memory://man`, or run `bm man bm-search` in a terminal.

</tip>

See [What's New in v0.24](https://docs.basicmemory.com/whats-new/v0-24) for everything that changed in this release.

## Next steps

<card-group>
<card icon="i-lucide-wrench" title="MCP Tools Reference" to="https://docs.basicmemory.com/reference/mcp-tools-reference">

Complete tool documentation with all parameters.

</card>

<card icon="i-lucide-file-text" title="Knowledge Format" to="https://docs.basicmemory.com/concepts/knowledge-format">

Learn about note structure and semantic patterns.

</card>
</card-group>


## Sitemap

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