write-note: add explicit --type arg; lock in content-frontmatter note_type with an integration test

[phernandez]

Background

The Claude Code memory-bridge plugin (#865) writes typed notes — type: session checkpoints, type: schema/decision seeds — through basic-memory tool write-note, relying on Basic Memory deriving note_type from the leading content frontmatter (services/entity_service.py:322-323 on create, 607-608 on update).

A Codex review on #865 (review 4397262976) flagged this as broken (P1) — believing the type is stripped and note_type defaults to note. It's a false positive (verified by reproduction + the code path; the cited markdown/utils.py:108-116 runs after the derivation). But settling it required a manual repro, and it exposed two real gaps worth fixing:

1. The behavior is implicit and fragile. The CLI write-note has no way to set note_type directly, so the plugin hooks depend on frontmatter derivation rather than stating intent.
2. It's untested. Nothing asserts the round-trip, which is exactly why the reviewer and the implementation disagreed.

Part 1 — write-note should accept an explicit --type (note_type)

The MCP write_note tool has a note_type param (src/basic_memory/mcp/tools/write_note.py:42), but the CLI basic-memory tool write-note exposes only --title/--folder/--content/--tags/--project/--project-id. Add the missing flag.

• Add --type (note_type) to the tool write-note CLI command, passed through to write_note(note_type=...).
• Define precedence when both an explicit --type and a content-frontmatter type are present (suggest: explicit --type wins; content frontmatter remains the fallback when --type is omitted, preserving today's behavior).
• Update the plugin's PreCompact hook to pass --type session explicitly instead of relying on embedded frontmatter (plugins/claude-code/hooks/pre-compact.sh).
• Update the setup skill's schema-seed step and /basic-memory:share to pass note_type explicitly via the MCP write_note(note_type=...) (they currently rely on content frontmatter). plugins/claude-code/skills/{setup,share}/.

Part 2 — Integration test: note_type round-trips

Lock in the behavior the review questioned so a future entity_service change can't silently break the memory bridge (and so reviewers/bots have ground truth).

• Write a note whose content frontmatter is type: session (no explicit note_type) → assert the persisted entity has note_type == "session" and search_notes(metadata_filters={"type": "session"}) returns it.
• Same for type: schema → assert it's found by the note_type == "schema" path and resolves via schema_validate.
• After Part 1: assert an explicit --type sets note_type, and cover the precedence rule above.
• (Optional) plugin smoke: a PreCompact-style checkpoint is found by the SessionStart --type session query.

Why both

Part 1 turns an implicit dependency into a first-class, explicit option for callers. Part 2 turns the behavior into a guaranteed contract. Together they would have pre-empted the entire #865 review back-and-forth.

Refs: #865, codex review 4397262976.

[claude]

Claude finished @phernandez's task in 18m 37s —— View job

---

Implementation Complete

Triage: Enhancement | Priority: Medium | Components: CLI, MCP tools, entity service, testing

All implementation work is complete. The branch claude/issue-875-20260531-1719 has commit 27a5f64 ready to push.

Checklist

Triage

• Classify issue and add enhancement label

Exploration

• Trace write_note CLI → MCP tool → entity_service note_type derivation
• Confirm pre-compact.sh and setup/share skills don't exist yet (out of scope)

Part 1 — Add --type to CLI write-note

• Entity.note_type_explicit: bool = False — sentinel flows MCP → API → entity_service without touching DB or frontmatter
• entity_service._apply_schema_frontmatter_overrides: skip frontmatter type= override when note_type_explicit=True
• MCP write_note: note_type: str | None = None; sets note_type_explicit when caller provides a value
• CLI write-note --type SESSION flag added, passes through to MCP
• JSON output now includes "note_type" for caller verification

Part 2 — Integration tests

• Frontmatter type: session → note_type == "session" + discoverable via search_notes(note_types=["session"])
• Frontmatter type: schema → note_type == "schema" + search verification
• Explicit note_type="decision" wins over conflicting frontmatter type: schema
• CLI: --type session sets note_type == "session" in JSON output
• CLI: --type decision wins over frontmatter type: schema

Verification

• Changes committed (27a5f6446f6d2e4d8bcda7e88dd861e8c1f2e114)
• Push to remote (blocked — git push requires approval in this workflow run)

---

Key Design Decisions

Precedence rule (explicit --type wins): When note_type is explicitly provided, Entity.note_type_explicit=True prevents entity_service from overriding it with the content-frontmatter type: field. When --type is omitted, content frontmatter is the fallback — preserving today's behavior exactly.

Only create/full-update paths are changed: _apply_schema_frontmatter_overrides is called for write_note (create + overwrite). The incremental edit_note path (prepare_edit_entity_content) is unchanged since it uses EntityModel, not the Pydantic schema, and edit_note has no note_type parameter.

pre-compact.sh / setup / share skills: These don't exist in the codebase. The issue references files from a proposed but not-yet-merged plugin PR (#865). Once those files exist, the write_note(note_type=...) MCP call will automatically get explicit-wins behavior via the new note_type_explicit flag.