git-agent-memory

Git history for the AI helping you code.

git-agent-memory is a lightweight developer tool for AI-assisted software development.
It closes the context gap between your current code and your project history by converting Git commits into structured, local context (commits.md) that coding agents can actually use.

Purpose

Most AI coding tools read your current files well, but miss historical intent.
This project makes commit history usable for:

• better code reviews
• safer refactors
• faster debugging and regression analysis
• fewer regressions (avoid re-introducing already fixed bugs)
• stronger onboarding context for new contributors

It helps agents answer:

• Why code changed
• What changed together
• Which files are usually involved in fixes
• What was already tried before
• What must not break again

What It Does

After setup, every new commit triggers a capture flow:

1. Parse latest commit metadata and file stats
2. Update <repo>/commits.md with a structured entry
3. Keep entries deduplicated by commit hash
4. Keep commits.md local-only by default

By default, commits.md and commits.lock are added to .git/info/exclude (not .gitignore), so they are ignored locally without touching tracked repo files.

Quick Start

1. Install

With pipx (recommended):

pipx install git-agent-memory

With pip:

pip install git-agent-memory

2. Enable Globally

git-agent-memory setup

This installs a global post-commit hook (core.hooksPath) for your user account.

3. Make a Commit

git commit -m "feat: add search endpoint"

Then inspect:

cat commits.md

If commits.md does not exist, it is created automatically on first successful capture/write.

Enable and Disable

Default mode after setup: enabled for all repositories for your user account.

Disable for current repo:

git-agent-memory exclude

Re-enable for current repo:

git-agent-memory include

Remove global hook:

git-agent-memory uninstall

Check current state:

git-agent-memory status
git-agent-memory doctor

Example Prompts Using commits.md

Use these with ChatGPT, Codex, Cursor, or any coding agent that can read your repo files.

1. Prevent breaking an old fix

• "Read commits.md and the current diff. Identify previous bug-fix commits touching the same files and list regression checks so we do not reintroduce those issues."

2. Safer refactor planning

• "Before refactoring src/git_agent_memory/hooks.py, use commits.md to summarize prior hook-related changes and list behavior that must stay unchanged."

3. Focused test plan

• "Using recent entries in commits.md, propose a minimal regression test plan for based on past failure patterns."

Commands

git-agent-memory setup [--dry-run] [--force-absolute]
git-agent-memory uninstall
git-agent-memory status
git-agent-memory doctor
git-agent-memory capture
git-agent-memory exclude
git-agent-memory include
git-agent-memory rebuild [--max-entries 100]

Command summary:

• setup: install/verify global hook setup
• uninstall: remove managed global hook and restore backup when present
• status: quick installation and repo capture status
• doctor: detailed diagnostics
• capture: manually capture latest commit
• exclude: skip current repo (adds repo path to global excluded_repos)
• include: remove current repo from global exclusions
• rebuild: rebuild commits.md from git history

Configuration

Global config path:

• ~/.git-agent-memory/config.yaml

Optional repo-local override:

• .git-agent-memory.yaml

Example:

enabled: true
max_entries: 100
file_name: "commits.md"
track_commits_file: false
excluded_repos:
  - "/absolute/path/to/repo"

Fields:

• enabled: global on/off default
• max_entries: max number of commit entries to keep
• file_name: output filename (safe basename only)
• track_commits_file: set true if you want to track commits.md in Git
• excluded_repos: explicit repo opt-out list

Troubleshooting

1. No commits.md appears after commit

• Run git-agent-memory status
• Run git-agent-memory doctor
• Check ~/.git-agent-memory/errors.log
• Run git-agent-memory capture manually to verify capture path

2. Repo is skipped unexpectedly

• Run git-agent-memory status and check skip reason
• If excluded, run git-agent-memory include

3. Want past history immediately

• Run git-agent-memory rebuild --max-entries 200

Development

git clone <repo>
cd git-agent-memory
python -m venv .venv
. .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e .
pytest

License

MIT. See LICENSE.