git-memento-workflow

Git Memento Workflow

Run this workflow whenever work must be committed with an AI session note.

1. Preflight

• Confirm repository status with git status --short and branch with git branch --show-current.
• Confirm git memento is available: git memento help.
• If unavailable, install git-memento into a directory on PATH and re-check.

2. Initialize Once Per Repository

• Check configuration: git config --local --get memento.provider.
• If missing, run git memento init codex or git memento init claude.
• If provider CLI shape differs from expected sessions get/list --json, configure adapter command in local git config:
  • git config --local memento.<provider>.bin <adapter-or-cli-path>
  • git config --local memento.<provider>.getArgs '<args with {id} placeholder>'
  • git config --local memento.<provider>.listArgs '<list args>'
• For summary mode, configure provider summary execution if defaults do not match your environment:
  • git config --local memento.<provider>.summary.bin <adapter-or-cli-path>
  • git config --local memento.<provider>.summary.args '<args with {prompt}, optionally {skill} and {sessionId}>'

3. Resolve Session ID

• Prefer explicit session id from the user.
• For Codex in this environment, default to CODEX_THREAD_ID when present.
• Validate retrieval before commit by running provider command manually if needed.

4. Create Memento Commit or Amend

• Stage files as needed (git add ...).
• Run commit through memento so note attachment happens in the same flow:
  • git memento commit <session-id> -m "<subject>"
  • Optional summary mode: git memento commit <session-id> --summary-skill <skill|default> -m "<subject>"
• For amend flows:
  • git memento amend -m "<amended-subject>" to carry forward existing note(s) onto the amended commit.
  • git memento amend <session-id> -m "<amended-subject>" to carry forward existing note(s) and append a new session.
  • Optional summary mode: git memento amend <session-id> --summary-skill <skill|default> -m "<amended-subject>"
• Summary mode behavior:
  • The CLI generates a markdown summary using the configured provider command.
  • It prints the generated summary and requires explicit confirmation.
  • If rejected, it asks for a user prompt and regenerates.
  • It writes the summary into refs/notes/commits and stores the full session in refs/notes/memento-full-audit.
• Backward compatibility:
  • Legacy single-session notes are preserved.
  • When append is needed, legacy notes are upgraded into the versioned multi-session envelope so no prior session content is lost.
• For longer body, use embedded newlines in -m or omit -m to use editor.