[FEATURE] Add a way to update frontmatter fields via edit_note

[phernandez]

Context

While building a help-desk workflow demo in Basic Memory, I needed to add closed_at to a ticket's frontmatter when resolving it. edit_note exposes append, prepend, find_replace, replace_section, insert_before_section, and insert_after_section — none of which directly target the YAML frontmatter.

What I did

edit_note(
  identifier="tickets/2026-06-18-printer-offline-at-downtown-location",
  operation="find_replace",
  find_text="opened_at: '2026-06-18T09:14:00Z'",
  content="opened_at: '2026-06-18T09:14:00Z'\nclosed_at: '2026-06-18T10:42:00Z'",
)

find_replace works, but it requires the agent to read the note first to grab the exact line, and it's fragile — a stale value in find_text silently makes no changes.

What I'd expect

A first-class operation for frontmatter updates — e.g. set_frontmatter / update_frontmatter taking a dict of fields to merge into the YAML:

edit_note(
  identifier="...",
  operation="set_frontmatter",
  content={"closed_at": "2026-06-18T10:42:00Z", "status": "resolved"},
)

Or a metadata parameter on edit_note that always merges (like write_note already accepts), independent of the operation.

Why it matters

Agents updating structured notes (tickets, tasks, projects) need to touch frontmatter routinely. The current find_replace workaround is the kind of papercut that adds up across a long agent session.

Discovered while

Building a help-desk MSP playbook demo for basicmemory.com.

[claude]

Claude finished @phernandez's task in 2m 13s —— View job

---

Issue Triage

• Gather context and analyze issue
• Check for duplicate issues
• Review existing edit_note implementation
• Apply labels and provide triage summary

---

Triage Summary

Type: Enhancement — new operation for existing edit_note MCP tool
Priority: Medium — impacts agent workflows that manage structured notes with frontmatter
Component: MCP tool (edit_note)
Complexity: Medium — requires coordinated changes across 4 layers

No duplicate found. Issue #378 (closed) was about malformed-YAML error logging in update_frontmatter, not adding a new editing operation.

---

Analysis

The feature request is well-scoped and technically feasible. The infrastructure already exists:

• FileService.update_frontmatter() (src/basic_memory/services/file_service.py:517) merges a dict of updates into file frontmatter.
• EntityService calls it in src/basic_memory/services/entity_service.py:1514 during certain write flows.
• write_note already accepts a metadata dict parameter — the pattern exists at the tool layer.

The gap is that edit_note has no path to invoke that frontmatter-update code. The current operations (append, prepend, find_replace, replace_section, insert_before_section, insert_after_section) are all defined in EditEntityRequest (src/basic_memory/schemas/request.py:61) and routed through EntityService.apply_edit_operation() (src/basic_memory/services/entity_service.py:1207), which does pure string manipulation on the full file content — it doesn't have a frontmatter-merge path.

---

Recommended Approach

Two options from the issue:

Option A — metadata parameter on edit_note (recommended)
Add a metadata: Optional[dict] param to edit_note that always merges into frontmatter, independent of operation. This matches the write_note pattern and lets agents combine frontmatter updates with content edits in a single call:

edit_note(identifier="...", operation="append", content="...", metadata={"status": "resolved", "closed_at": "..."})

Requires: updates to EditEntityRequest, edit_entity_by_id API handler, edit_entity_with_content, and edit_note MCP tool signature.

Option B — set_frontmatter as a new operation value
Extend the Literal in EditEntityRequest and add a branch in apply_edit_operation. The content parameter would need to carry JSON-encoded fields (since content: str today), which is awkward. This is more limited since it can't be combined with other operations.

Option A is cleaner and more consistent with the existing codebase. It routes cleanly to the already-tested file_service.update_frontmatter() path.

---

Scope of Change (Option A)

File	Change
src/basic_memory/schemas/request.py	Add metadata: Optional[dict[str, Any]] = None to EditEntityRequest
src/basic_memory/api/v2/routers/knowledge_router.py	Pass metadata to edit_entity_with_content
src/basic_memory/services/entity_service.py	Apply frontmatter merge in edit_entity_with_content when metadata is set
src/basic_memory/mcp/tools/edit_note.py	Add metadata: Optional[dict] = None param; pass through to API
tests/ + test-int/	Unit + integration tests for the new parameter

---

Applied label: enhancement

[phernandez]

@claude please implement this and open a PR.

Add a first-class way to update YAML frontmatter through edit_note, so agents stop having to find_replace on an exact frontmatter line (fragile — a stale find_text silently no-ops).

Design

• Mirror the existing precedent: write_note already accepts a metadata dict that merges into frontmatter. Prefer that shape over the dict-typed content sketch in the issue, because edit_note.content is typed str with AliasChoices and a dict won't fit cleanly. Either add a new operation value (e.g. update_frontmatter) or an optional metadata: dict[str, Any] param that merges regardless of operation. Pick whichever is cleaner against the current tool schema and explain the choice in the PR.
• Merge semantics: set/overwrite the provided keys, leave all other frontmatter untouched. Key deletion can be out of scope for v1 (say so).
• Guardrails: don't let it clobber identity fields (permalink/title) in a way that breaks link resolution — follow whatever write_note already guards. Keep the body/observations/relations of the note unchanged.

Relevant code

• src/basic_memory/mcp/tools/edit_note.py — the tool; operations live in EDIT_OPERATIONS, edits go through knowledge_client.patch_entity.
• src/basic_memory/mcp/tools/write_note.py — the metadata merge precedent to mirror.
• src/basic_memory/services/entity_service.py + the PATCH knowledge route — server-side frontmatter write path.

Tests + docs

• Unit test: new key added, existing key overwritten, unrelated keys + body preserved.
• Integration test in test-int/mcp/: write a note, update frontmatter, read it back, assert the field is set and the file's frontmatter is still valid YAML.
• Update the edit_note docstring/examples.

Conventions: sign commits (git commit -s); PR title feat(mcp): <summary>; run just fast-check and the new tests before opening the PR.

[claude]

Claude finished @phernandez's task in 25m 8s —— View job

---

Working on this

• Gather context and trace the server-side edit pipeline
• Design: metadata: Optional[dict] param on edit_note/EditEntityRequest, merged into frontmatter independent of operation
• Implement server-side: EditEntityRequest.metadata, threaded through the accepted-note-mutation pipeline (_run_accepted_note_edit → prepare_accepted_note_edit → EntityService.prepare_edit_entity_content), with a new _merge_metadata_into_markdown helper that reuses the existing frontmatter-parsing path so title/permalink resolution stays consistent
• Implement MCP tool: edit_note(..., metadata=...), docstring + example, auto-create path also accepts metadata
• Unit tests: new key added, key overwritten, unrelated keys/body preserved, identity-field guard (title/type/permalink ignored), no-frontmatter case
• Integration tests in test-int/mcp/ + a router-level test
• Run just fast-check and new tests (installing deps now — just/uv aren't on PATH in this sandbox, working around via python3 -m pip)
• Commit, push, open PR

[phernandez]

@claude your previous run completed the full implementation but timed out at 25m before committing, because it tried to install just/uv (which are not on the Actions runner) and burned the whole budget on python3 -m pip workarounds. Please redo it, but this time:

Do NOT install dependencies and do NOT run just/uv/pytest/ruff locally — they aren't available on the runner and will exhaust your time budget. Make the code + test edits, git commit -s, and git push. CI runs the full suite on the PR; that is where verification happens.

Re-apply the design your prior run already settled on (it was correct):

• Add metadata: Optional[dict] to EditEntityRequest and to the edit_note MCP tool, merged into frontmatter independent of operation.
• Thread it through the accepted-note-mutation pipeline: _run_accepted_note_edit → prepare_accepted_note_edit → EntityService.prepare_edit_entity_content, with a _merge_metadata_into_markdown helper that reuses the existing frontmatter-parsing path so title/permalink resolution stays consistent.
• The auto-create path (append/prepend on a missing note) should also accept metadata.
• Guard identity fields: ignore/reject attempts to set title/type/permalink via metadata (those have their own handling).
• Merge semantics: set/overwrite provided keys, preserve all other frontmatter and the note body. Key deletion is out of scope.
• Update the edit_note docstring + add an example.

Tests to include (write them, don't run them here): unit — new key added, key overwritten, unrelated keys/body preserved, identity-field guard, no-existing-frontmatter case; integration in test-int/mcp/ + a router-level test.

Conventions: git commit -s; commit subject feat(mcp): add metadata param to edit_note for frontmatter updates; include Closes #1011. Push the branch when done.

[claude]

Claude finished @phernandez's task in 10m 36s —— View job • claude/issue-1011-20260716-2019 • Create PR ➔

---

Implemented metadata param for edit_note

• Gather context (previous run's changes were not persisted — working tree was clean, redid from scratch)
• Design: metadata: Optional[dict] param on EditEntityRequest / edit_note, merged into frontmatter independent of operation
• Server-side: threaded metadata through _run_accepted_note_edit → prepare_accepted_note_edit → EntityService.prepare_edit_entity_content, via a new _merge_metadata_into_markdown helper that reuses the existing frontmatter-parsing path
• Auto-create path (append/prepend on a missing note) also accepts metadata
• Guard identity fields — title/type/permalink in metadata are silently ignored (they have their own resolution paths)
• MCP tool: edit_note(..., metadata=...) + docstring + example
• Unit tests (tests/services/test_entity_service_prepare.py): new key added, key overwritten, unrelated keys/body preserved, identity-field guard, no-existing-frontmatter case
• Runner-level tests (tests/indexing/): metadata threads through run_accepted_note_edit and prepare_accepted_note_edit
• Router-level test (tests/api/v2/test_knowledge_router.py) + integration tests (test-int/mcp/test_edit_note_integration.py)
• Commit (signed, Closes #1011) and push — no local just/uv/pytest/ruff runs, per your instructions CI verifies

Design notes

Went with Option A from the earlier triage: an optional metadata dict param, independent of operation, rather than a new set_frontmatter operation — this lets a single edit_note call combine a content edit with a frontmatter update, and mirrors write_note's existing metadata param.

edit_note(
  identifier="tickets/2026-06-18-printer-offline-at-downtown-location",
  operation="append",
  content="",
  metadata={"status": "resolved", "closed_at": "2026-06-18T10:42:00Z"},
)

Merge semantics: set/overwrite provided keys, everything else (other frontmatter keys, the body) untouched. Key deletion is out of scope for v1. title/type/permalink are dropped from the merge rather than erroring, since they already have dedicated resolution paths in the edit pipeline.

Not done here

Per your instructions, I did not run just fast-check, pytest, or ruff locally (not available on this runner and would exhaust the time budget) — CI will run the full suite on the PR.