Bm Checkpoint

Checkpoint Codex Work

Create a durable, immutable handoff note for current Codex work. Use this when the user asks to checkpoint, wrap up, hand off, remember the work state, or when the post-compaction SessionStart context requests the deliberate handoff.

Gather

Read ~/.codex/basic-memory.json, then the nearest project .codex/basic-memory.json; project keys override user keys:

• primaryProject, default omitted
• captureFolder, default codex/<git top-level directory name>
• placementConventions, optional
• sessionProfile, default general
• repository, required when sessionProfile is coding

Apply the bm-writing skill before drafting the note.

Gather repo evidence:

• the original objective that started the thread and why it mattered
• the latest user intent, including corrections or scope changes that supersede the original objective
• 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
• 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 thread
• unresolved blockers
• next action
• current username, hostname, and timestamp
• host-provided session_id, agent, codex_turn_id, trigger, and model values from the checkpoint request, when present

Use direct, read-only evidence for repository and pull-request state. Do not claim a test passed unless you ran it or the user supplied the result. Treat host-provided session metadata as opaque identity data. Preserve exact non-empty values; never infer or rewrite them. For older requests supplying only codex_session_id, use that exact value as session_id with agent: codex. Do not emit the legacy field on new checkpoints.

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. Treat it as a snapshot plus pointers to authoritative artifacts, not a replacement for tasks, decisions, plans, issues, pull requests, commits, diffs, checked-in docs, or source files.

Every invocation creates a new checkpoint. Never edit, replace, or append to an earlier checkpoint, even when the topic is unchanged.

Use the title:

Codex checkpoint - <UTC YYYY-MM-DDTHH-MM-SSZ> - <short topic>

The UTC timestamp is part of the immutable checkpoint identity and avoids filename-unsafe colons. If write_note reports a title collision, retry with the smallest available numeric suffix such as - 2. Never resolve a collision by modifying the existing note.

Call write_note with project=<configured primaryProject>, overwrite=False, and output_format="json" on every attempt. When primaryProject is omitted, leave the project argument unset so Basic Memory uses its default project. The frontmatter project field is descriptive metadata and does not replace the tool's project argument. The explicit non-overwrite flag must win even when the user's write_note_overwrite_default setting is true. Only accept a successful result with action: created; treat action: conflict or NOTE_ALREADY_EXISTS as the title collision above, and stop on any other action or error.

Write a note to Basic Memory. For the general profile:

• title: the timestamped checkpoint title above
• directory: configured captureFolder
• tags: ["codex", "checkpoint"]
• frontmatter:
  • type: codex_session
  • status: open
  • project: <primaryProject if known>
  • cwd: <current cwd>
  • started: <current timestamp>
  • username: <current username>
  • hostname: <current hostname>
  • capture: deliberate
  • agent: codex
  • session_id: <host-provided Codex session id>, when supplied
  • codex_turn_id: <host-provided Codex turn id>, when supplied
  • trigger: <host-provided checkpoint trigger>, when supplied
  • model: <host-provided model slug>, when supplied

For the coding profile, write 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, pull_request_state, pull_request_base, and pull_request_head. Resolve the pull request with a read-only GitHub query; 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.