Feature: edit-note recovery when note exists on disk but is not indexed yet

[phernandez]

Problem

edit-note fails with "Entity not found" when a markdown file exists on disk but has not been indexed yet.

This breaks a common workflow:

1. Write file directly to disk.
2. Immediately call bm tool edit-note ....
3. Edit fails even though file exists.

Related downstream issue: basicmachines-co/openclaw-basic-memory#19

Why this looks upstream

Current edit flow resolves identifier to entity ID first and fails hard when index is behind:

• src/basic_memory/cli/commands/tool.py (_edit_note_json)
• src/basic_memory/mcp/tools/edit_note.py (resolve_entity before patch)

Requested fix

Add an optional recovery path when identifier resolution fails:

1. Attempt targeted sync/index for matching file candidate(s) when identifier looks like a permalink/path.
2. Retry entity resolution once after sync.
3. Return a structured error code when recovery fails (e.g. ENTITY_NOT_FOUND_AFTER_SYNC) so clients can handle it deterministically.

Alternative acceptable fix: explicit edit-note flag (for example --sync-if-missing) that enables this behavior.

Acceptance criteria

• If note exists on disk but is temporarily unindexed, edit-note can recover without manual watcher restart.
• CLI JSON mode returns machine-readable failure code for non-recoverable misses.
• Behavior is opt-in or clearly documented to avoid unexpected expensive sync calls.

[claude]

Claude finished @phernandez's task in 1m 15s —— View job

---

Issue Triage Analysis

• Read relevant source files
• Classify issue type and priority
• Check for duplicate issues
• Add appropriate labels
• Provide triage feedback

---

Classification

Field	Value
Type	Enhancement
Priority	Medium
Component	MCP tools + CLI
Complexity	Medium

Labels added: enhancement

---

Analysis

This is a valid and well-scoped enhancement request. The reported failure behavior is confirmed by reading the source code.

Current flow in edit_note.py (line 240) and _edit_note_json in tool.py (line 197):

# Resolve identifier to entity ID - fails hard if not indexed
entity_id = await knowledge_client.resolve_entity(identifier)

When resolve_entity fails (entity not in DB index), the MCP tool catches the exception and returns a formatted error string beginning with # Edit Failed. The CLI's _edit_note_json doesn't catch this and raises directly. Neither path has a recovery mechanism.

No duplicate issues found in the repository for this specific scenario.

---

Implementation Considerations

The requested fix has two reasonable implementation approaches:

Option A: Automatic recovery with targeted sync

• When resolve_entity fails, check if a matching file exists on disk
• Trigger a targeted sync/index for that file
• Retry resolve_entity once
• Return ENTITY_NOT_FOUND_AFTER_SYNC error code if still failing

Option B: Explicit --sync-if-missing flag

• Opt-in behavior to avoid unexpected expensive sync on every miss
• Cleaner semantics: caller must explicitly request the recovery attempt
• Better for automation/scripting where deterministic behavior is expected

Key questions for implementation:

1. Is there a targeted per-file sync API already available? The sync service is in src/basic_memory/sync/ - a targeted sync would need to call into this without triggering a full project scan.
2. The MCP tool currently catches all exceptions and returns a formatted string - the structured error code (ENTITY_NOT_FOUND_AFTER_SYNC) would either need to be embedded in the formatted response or require a separate code path for JSON mode.
3. The _edit_note_json path (CLI JSON mode) hits resolve_entity directly and would need its own recovery logic.

Complexity factors:

• The sync layer needs to support targeted single-file indexing (may already exist via the file watcher path)
• Recovery behavior must be opt-in to avoid latency surprises in automated workflows
• JSON mode needs a machine-readable failure code, which is a separate concern from the recovery mechanism

---

Recommendation

The --sync-if-missing flag approach (Option B) is cleaner for the CLI use case and avoids silent performance surprises. For the MCP tool, the existing error message already suggests using write_note first as a fallback - adding an optional sync_if_missing parameter to edit_note would align well with the existing parameter pattern.

A good implementation would:

1. Add sync_if_missing: bool = False parameter to the MCP edit_note tool
2. When set, attempt a targeted file sync before retrying resolution
3. In _edit_note_json, surface a structured {"error": "ENTITY_NOT_FOUND_AFTER_SYNC", ...} dict on failure
4. Document the behavior clearly in the tool docstring

[phernandez]

Downstream tracking

• Downstream: BUG: bm_edit fails for notes not yet indexed by watcher openclaw-basic-memory#19
• Related root-cause track: BUG: watch service can go stale while process stays alive (self-heal + heartbeat) #580