bm doctor fails on 0.23.0: "API note file missing" — note materialization raises EntityNotFoundError / StaleDataError

[scarabone]

Summary

On v0.23.0, bm doctor fails at its first real check — the note written through the API never appears on disk:

Running Basic Memory doctor checks...
OK Created doctor project: doctor-cad70399
Doctor failed: API note file missing: doctor/Doctor API Note.md

The log shows the new local materialization step failing because the entity row it tries to update does not exist yet. The same check passes on v0.22.1 in the identical harness.

Environment

• basic-memory 0.23.0 (from PyPI, --prerelease=allow for the fastmcp 4.0.0b1 pin)
• macOS 27.0 (26A5416b), Apple Silicon
• Python 3.12.13 (also reproduced on 3.13.14)
• uv 0.12.5
• SQLite backend, default config, local mode (no cloud credentials)

Reproduction (clean, isolated HOME)

mkdir -p /tmp/bm-repro
HOME=/tmp/bm-repro uvx --python 3.12 --prerelease=allow --from 'basic-memory==0.23.0' bm doctor

Result: Doctor failed: API note file missing: doctor/Doctor API Note.md

Control, same harness:

mkdir -p /tmp/bm-repro-22
HOME=/tmp/bm-repro-22 uvx --python 3.12 --from 'basic-memory==0.22.1' bm doctor

Result: OK API write created file, OK Manual file written, OK Sync indexed manual file, OK Search confirmed manual file, OK Status clean after sync (it then fails only at cleanup because the doctor project is the sole project in the empty HOME — unrelated).

Log excerpt (~/.basic-memory/basic-memory.log, clean HOME)

ERROR | basic_memory.index.note_content_materialization:_run:128 - Local note materialization failed
  File ".../basic_memory/cli/commands/doctor.py", line 215, in doctor
  File ".../basic_memory/cli/commands/command_utils.py", line 53, in run_with_cleanup
> File ".../basic_memory/index/note_content_materialization.py", line 126, in _run
  File ".../basic_memory/index/note_content_materialization.py", line 706, in _materialize_write_now
  File ".../basic_memory/index/local_dependencies.py", line 285, in index_file
  File ".../basic_memory/index/local_dependencies.py", line 318, in index_markdown_file
  File ".../basic_memory/index/local_dependencies.py", line 542, in index_current_markdown_file
  File ".../basic_memory/index/local_dependencies.py", line 603, in index_changed_markdown_file
  File ".../basic_memory/indexing/batch_indexer.py", line 273, in index_markdown_file
  File ".../basic_memory/indexing/batch_indexer.py", line 776, in _persist_markdown_file
  File ".../basic_memory/services/entity_service.py", line 726, in update_markdown_entity_fields
    raise EntityNotFoundError(f"Entity not found for file path: {file_path}")
basic_memory.services.exceptions.EntityNotFoundError: Entity not found for file path: doctor/Doctor API Note.md

On an existing install upgraded from 0.22.1 (memory.db migrated by 0.23.0's auto-migrations), the same call path fails with a different exception at the same point:

sqlalchemy.orm.exc.StaleDataError: UPDATE statement on table 'entity' expected to update 1 row(s); 0 were matched.

Both point at _materialize_write_now → index_file → update_markdown_entity_fields expecting an entity row for the freshly written note that is not there (or is not visible to that session) yet.

Notes

• bm doctor --local gives the same result.
• Writing a note with bm tool write-note directly does create the file on disk, so this may be specific to how the doctor drives the API write, or to timing between the row insert and the materialization worker.
• Happy to test a fix or provide the full log.

[scarabone]

Additional data from a fuller 0.23.0 trial against a real vault (876 markdown notes, isolated HOME + UV_TOOL_DIR, Python 3.12.13, macOS, SQLite backend, semantic search enabled with fastembed):

The failure is deterministic, not a flaky race — bm doctor failed 5/5 consecutive runs with API note file missing: doctor/Doctor API Note.md.

Normal API writes are unaffected. In the same install, bm tool write-note materializes the file on disk correctly, both:

• into a long-lived existing project (the 876-note one), and
• into a project created moments earlier with bm project add (persistent path, not a temp dir).

So the write/materialization path works in ordinary use; the failure appears confined to doctor's specific flow — create_project(set_default=False) into a tempfile.TemporaryDirectory() followed immediately by create_entity. The API response for that create is 202 and the log shows indexing of doctor/Doctor API Note.md starting ~16ms after the response, but the file-existence check in doctor.py (line ~136) has already run and failed by then, after which cleanup removes the project.

Everything else in 0.23.0 held up in the same trial, for what it's worth: full reindex of the vault from an empty db (876/876), the MCP server on fastmcp 4.0.0b1 serving streamable-http, and the file watcher writing watch-status.json normally.