git-memento

git-memento is a Git extension that records the AI coding session used to produce a commit. It attaches AI conversation transcripts as git notes, creating an audit trail for AI-assisted development.

Table of Contents

• What is git-memento?
• Getting Started
  • Prerequisites
  • Installation
  • First-time setup
  • Your first memento commit
  • Verify the note
  • Share with your team
• Core Commands
• Advanced Features
• CI/CD Integration
• Build and Install
• Testing
• Contributing
• License

What is git-memento?

git-memento solves a critical problem in AI-assisted development: when an AI assistant produces a commit, the conversation that led to that change is typically lost. Team members see what changed but not why the AI was asked to change it, what alternatives were considered, or what constraints were given.

git-memento:

• Creates commits with normal Git flow (-m or editor)
• Attaches the AI session transcript to the commit using git notes
• Produces human-readable markdown notes
• Keeps provider support extensible (Codex and Claude Code supported)
• Works seamlessly with your existing Git workflow

Who is this for? Development teams using AI coding assistants (Codex, Claude Code) who want to maintain transparency, support code review, meet compliance requirements, or preserve context for debugging and onboarding.

Getting Started

Prerequisites

Before using git-memento, you need:

• Git installed and configured (git config user.name and user.email set)
• An AI provider CLI installed:
  • Codex: Install via npm install -g @codexcli/cli or your provider's instructions
  • Claude Code: Install from claude.ai/code

Installation

Install git-memento from the latest GitHub release:

curl -fsSL https://raw.githubusercontent.com/mandel-macaque/memento/main/install.sh | sh

The installer will:

1. Detect your OS and architecture
2. Download the appropriate release binary
3. Install to ~/.local/bin (or your configured install directory)
4. Prompt you to add the directory to your PATH if needed

Alternative: You can also build from source if you prefer.

After installation, verify git-memento is available:

git memento --version
git memento help

First-time setup

Initialize git-memento for your repository. This stores provider configuration in local git metadata (.git/config):

# For Codex
git memento init codex

# For Claude Code
git memento init claude

You only need to run init once per repository. The configuration is stored locally and won't affect other repositories.

Your first memento commit

1. Make your changes as you normally would

2. Stage your files:

   git add .
   

3. Create a commit with an attached AI session note:

   git memento commit <session-id> -m "Your commit message"
   

   • Replace <session-id> with your AI session ID
   • For Codex: Find session IDs with codex sessions list --json
   • For Claude Code: Use the session ID from your Claude session

   Example:

   git memento commit abc123 -m "Add user authentication feature"
   

Verify the note

Check that the AI session transcript was attached to your commit:

# Show the commit
git log -1 --pretty=fuller

# Show the attached note
git notes show HEAD

You should see a markdown-formatted conversation with your AI provider showing the messages exchanged during the session.

Share with your team

Push your commit and sync the notes to your remote repository:

git memento push

This command:

• Pushes your commits to the remote
• Syncs refs/notes/* to the remote
• Configures fetch mappings so teammates can retrieve notes

Your team members can fetch the notes with:

git memento notes-sync

You're now up and running! Continue reading for more advanced features and commands.

Core Commands

Initialize per-repository

git memento init
git memento init codex
git memento init claude

init stores configuration in local git metadata (.git/config) under memento.*.

Create commits with notes

git memento commit <session-id> -m "Normal commit message"
git memento commit <session-id> -m "Subject line" -m "Body paragraph"
git memento commit <session-id> --summary-skill default -m "Subject line"

You can pass -m multiple times, and each value is forwarded to git commit in order. When -m is omitted, git commit opens your default editor.

Amend commits

git memento amend -m "Amended subject"
git memento amend <new-session-id> -m "Amended subject" -m "Amended body"
git memento amend <new-session-id> --summary-skill session-summary-default -m "Amended subject"

amend runs git commit --amend:

• Without a session id, it copies the note(s) from the previous HEAD onto the amended commit
• With a session id, it copies previous note(s) and appends the new fetched session as an additional session entry
• A single commit note can contain sessions from different AI providers

Summary mode

--summary-skill <skill|default> (for commit and amend <session-id>) changes note behavior:

• The default notes ref (refs/notes/commits) stores a summary record instead of the full transcript
• The full session is stored in refs/notes/memento-full-audit
• The CLI prints the generated summary and asks for confirmation
• If rejected, you must provide a prompt to regenerate
• default maps to the repository skill at skills/session-summary-default/SKILL.md
• The default summary skill is always applied as a baseline; if a user-provided summary skill conflicts with it, user-provided instructions take precedence

Verify both notes after a summary run:

git notes show <commit-hash>
git notes --ref refs/notes/memento-full-audit show <commit-hash>

Share notes with remote

git memento share-notes
git memento share-notes upstream

This pushes refs/notes/* and configures local remote.<name>.fetch so notes can be fetched by teammates.

Push branch and sync notes

git memento push
git memento push upstream

This runs git push <remote> and then performs the same notes sync as share-notes. Default remote is origin.

Sync notes from remote

If a session id is not found, git-memento asks the configured provider for available sessions and prints them.

This command:

• Ensures notes fetch mapping is configured
• Creates backup refs under refs/notes/memento-backups/<timestamp>/...
• Fetches remote notes into refs/notes/remote/<remote>/*
• Merges remote notes into local notes and pushes synced notes back to the remote
• Syncs both refs/notes/commits and refs/notes/memento-full-audit

git memento notes-sync
git memento notes-sync upstream
git memento notes-sync upstream --strategy union

Default remote is origin, default strategy is cat_sort_uniq.

Audit note coverage

git memento audit --range main..HEAD
git memento audit --range origin/main..HEAD --strict --format json

Audit note coverage and note metadata in a commit range:

• Reports commits with missing notes (missing-note <sha>)
• Validates note metadata markers (- Provider: and - Session ID:)
• In --strict mode, invalid note structure fails the command

Repository diagnostics

git memento doctor
git memento doctor upstream --format json

Run repository diagnostics for provider config, notes refs, and remote sync posture.

Show help and version

git memento help
git memento --version

Advanced Features

Configure automatic note carry-over

For rewritten commits (rebase / commit --amend):

git memento notes-rewrite-setup

This sets local git config:

• notes.rewriteRef=refs/notes/*
• notes.rewriteMode=concatenate
• notes.rewrite.rebase=true
• notes.rewrite.amend=true

Carry notes from rewritten range

For squash/rewrite flows onto a new target commit:

git memento notes-carry --onto <new-commit> --from-range <base>..<head>

This reads notes from commits in <base>..<head> and appends provenance blocks to <new-commit>. It carries both refs/notes/commits and refs/notes/memento-full-audit.

Provider configuration

Provider defaults can come from env vars, and init persists the selected provider + values in local git config:

• MEMENTO_AI_PROVIDER (default: codex)
• MEMENTO_CODEX_BIN (default: codex)
• MEMENTO_CODEX_GET_ARGS (default: sessions get {id} --json)
• MEMENTO_CODEX_LIST_ARGS (default: sessions list --json)
• MEMENTO_CODEX_SUMMARY_BIN (default: codex)
• MEMENTO_CODEX_SUMMARY_ARGS (default: exec -c skill.effective_path={effectiveSkillPath} -c skill.default_path={defaultSkillPath} -c skill.user_path={userSkillPath} "{prompt}")
• MEMENTO_CLAUDE_BIN (default: claude)
• MEMENTO_CLAUDE_GET_ARGS (default: sessions get {id} --json)
• MEMENTO_CLAUDE_LIST_ARGS (default: sessions list --json)
• MEMENTO_CLAUDE_SUMMARY_BIN (default: claude)
• MEMENTO_CLAUDE_SUMMARY_ARGS (default: -p --append-system-prompt "Skill paths: effective={effectiveSkillPath}; default={defaultSkillPath}; user={userSkillPath}. Prefer user skill when provided." "{prompt}")

Summary args template placeholders:

• {prompt}: generated summary prompt
• {sessionId}: session id
• {skill}: user skill name or session-summary-default
• {defaultSkillPath}: default skill file path (skills/session-summary-default/SKILL.md)
• {userSkillPath}: user skill file path (empty when `--summary-skill de