feat(mcp): move notes and folders into another project - #2048

Closes #1842.

What it does

bm_move(..., destination_project="research") moves a note (identifier) or a directory (path) into another project. destination is then a path in that project, and a trailing / keeps the name, as it does within a project.

As the issue specifies, a cross-project move is a write in the target followed by a delete in the source:

• The moved note is new in the target: new id, its own version history.
• Links in either project are not rewritten.
• A note already at the destination is never replaced (ALREADY_EXISTS, nothing moved).
• Permalink collisions resolve the way any new write does.
• destination_project naming the source's own project is an ordinary move, which keeps id and history.

Safety

New module: src/basic_memory/mcp/cross_project_move.py.

Order of operations:

1. Take the note's checksum, then read its content.
2. Write the copy in the target project with overwrite=false.
3. Delete the source, guarded by that checksum.

If the note changes at any point, the guarded delete refuses.

When the source delete fails:

• Definite refusal (changed note, 403): the copy is deleted again, guarded by its own checksum, and the move refuses with "Nothing was moved."
• Unknown outcome (no answer): the copy stays and the refusal says where it is, because the source may already be gone. Removing the copy then could lose the note.
• Copy can't be removed: PARTIAL_FAILURE says plainly that the note is now in both projects.

Up-front refusals:

• A locked note (locked: true) is refused before anything is written. Its copy would be locked too and could not be removed.
• A destination that isn't a Markdown note path.

Directories move note by note. Files that aren't notes (attachments, .txt) stay. A directory with anything left behind ends in PARTIAL_FAILURE listing each file that stayed.

Write access: a caller who can't write the target, or delete in the source, is refused through the API's own answers. To support that, refusals.py now maps 403 to a new FORBIDDEN code instead of OUTCOME_UNKNOWN. Before this, a 403 read as "may or may not have happened".

Interface

• New destination_project parameter on bm_move, and --destination-project on bm tool move.
• A destination that starts with another project's name, without destination_project, is still refused. The hint now points at destination_project.
• bm-move(3) describes the behavior and has an example.
• No API changes: the move reuses the write, entity read and delete routes.

Not included

• Attachments and other non-note files don't move between projects.
• Cross-workspace moves.
• Keeping ids, history or links.

Tests

tests/mcp/test_tool_bm_move_across_projects.py, 20 tests on the real ASGI stack. Covers:

• notes and the trailing-slash name
• occupied destination, stale checksum, locked note, non-Markdown destination
• the same-project shortcut, and the refusal hint
• a refused source delete (copy removed), an unanswered source delete (copy kept), a copy that can't be removed, a refused target write
• directories: full, partial, text output, a non-note file, the project root, empty, and paging

The failure cases use an httpx transport in front of the real app that answers 403 or drops the request for one HTTP method. No monkeypatching.

Coverage: 100% for cross_project_move.py and tools/move.py. tests/mcp + tests/cli pass (2,524). The new tests also pass on Postgres. just fast-check passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CMYVL4TcbWdXhdvAzxfqjo