/bm-checkpoint

name: bm-checkpoint
description: Save a deliberate work checkpoint to Basic Memory with the story, changed files, verification, decisions, blockers, and the next action. Use when the user asks to checkpoint, wrap up, hand off, or remember the state of the work.
argument-hint: (optional short topic for the checkpoint title)

Checkpoint Claude Work

Create a durable handoff note for the current work. Use this when the user asks to checkpoint, wrap up, hand off, remember the state of the work, or before a long context transition. This is the deliberate, high-signal counterpart to the automatic PreCompact checkpoint.

Gather

Resolve config: read the `basicMemory` block with the same precedence the hooks use. For the user-level base, append `settings.json` to the literal value of `CLAUDE_CONFIG_DIR` when that environment variable is present; do not trim it, expand `~`, or treat an empty value as unset. Use `~/.claude/settings.json` only when the variable is absent. Then the project's `.claude/settings.json` and `.claude/settings.local.json` override it per key:

• `primaryProject`, default omitted (Basic Memory's default project)
• `captureFolder`, default `sessions`
• `placementConventions`, optional
• `sessionProfile`, default `general`
• `repository`, required when `sessionProfile` is `coding`

Apply the `bm-writing` skill before drafting the note.

Gather evidence:

• the original problem or goal and why it mattered
• the approach taken and why it solves the problem
• the current system state and practical impact
• tradeoffs, sharp edges, useful simplifications, and intentionally parked work
• the durable lesson, if one exists — what future work should know or avoid
• `git status --short`
• current branch
• repository root and current working directory
• current Git SHA
• current pull request number, title, URL, state, base, and head when one exists
• changed files you touched
• tests or checks actually run
• failures or skipped checks
• decisions made in this session
• unresolved blockers
• next action
• current username, hostname, and timestamp
• exact host-provided session identifier, when available; never infer one

Do not claim a test passed unless you ran it or the user supplied the result.

Write

A checkpoint is a durable handoff, not a status dump or commit-by-commit changelog. Tell the story for a human or agent returning later.

Write the note with `write_note`, routed to `primaryProject` (pass it as `project`, or as `project_id` if it's an `external_id` UUID). For the `general` profile:

• `title`: `Claude checkpoint - <short topic>`
• `directory`: configured `captureFolder`
• `tags`: `["claude", "checkpoint"]`
• `note_type`: `session`
• `metadata` (frontmatter):
• `status: open`
• `project: <primaryProject if known>`
• `cwd: <current cwd>`
• `started: <current timestamp>`
• `username: <current username>`
• `hostname: <current hostname>`
• `capture: deliberate`
• `agent: claude-code`
• `session_id: <exact host-provided session id>`, when available

New notes use `agent` and `session_id`, not `claude_session_id`. Existing notes with the legacy field remain valid; do not rewrite them. Session identity is the pair of agent and session ID, never a bare ID shared across hosts.

For the `coding` profile, write `note_type: coding_session` (frontmatter `type: coding_session`) and use the same common frontmatter plus these schema-required fields:

• `repository: <confirmed stable repository identifier>`
• `repo_root: <git rev-parse --show-toplevel>`
• `cwd: <current cwd>`
• `branch: <git rev-parse --abbrev-ref HEAD>`
• `git_sha: <git rev-parse HEAD>`

When the current branch has a pull request, also add the typed optional fields `pull_request_number`, `pull_request_title`, `pull_request_url`, lowercase `pull_request_state`, `pull_request_base`, and `pull_request_head`. Resolve the pull request with a read-only GitHub query (e.g. `gh pr view --json ...`); omit those fields when no PR exists. Write the number as a quoted string, for example `pull_request_number: "123"`, so exact metadata queries behave consistently across storage backends. Never infer or copy repository/PR identity only from conversation text. Stop if the required coding fields cannot be proven.

Begin the body with `# <exact note title>`.

Use these sections, omitting optional ones that add no value:

• `## Summary`: one concrete sentence that does not merely repeat the title
• `## Story`: problem -> approach -> current state and impact in substantive prose
• `## Project Memory`, when the work surfaced a durable lesson future readers

need — the constraint discovered, the boundary made explicit, the shortcut to avoid

• `## Changed Files`, when paths are useful for resuming
• `## Verification`, for checks actually run and their outcomes
• `## Observations`
• `## Relations`, when the session has an obvious graph target

Use observations to distill durable facts for structured recall rather than duplicating every narrative sentence:

• `[result]` for concrete outcomes
• `[decision]` for each decision made or preserved
• `[blocker]` for each unresolved blocker
• `[next_step]` for the next concrete action; include at least one
• `[verification]` or `[changed_file]` only when the item is itself important

project memory, not merely supporting detail

Do not create separate Decisions, Blockers, or Next Action sections with plain bullets. Omit empty categories instead of writing placeholder text such as "None."

Relations are not observations. Put them under `## Relations` using Basic Memory relation syntax, for example `- relates_to [[Exact existing note title]]`. Never write `[relates_to]` or a bare `memory://` URL as an observation. Only add a relation when its target is an existing task, decision, spec, issue, or PR note.

Confirm

Reply with the permalink and the one next action the checkpoint preserves.