git-agent-memory 0.1.0
Git history for the AI helping you code.
Requires Python: >=3.8
Keywords: git, ai, cli, commit-history, developer-tools

# 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.

[![Build Status](https://img.shields.io/badge/build-passing-lightgrey)](#)
[![Version](https://img.shields.io/badge/version-0.1.0-lightgrey)](#)
[![License](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)

## 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):

```bash
pipx install git-agent-memory
```

With `pip`:

```bash
pip install git-agent-memory
```

### 2. Enable Globally

```bash
git-agent-memory setup
```

This installs a global `post-commit` hook (`core.hooksPath`) for your user account.

### 3. Make a Commit

```bash
git commit -m "feat: add search endpoint"
```

Then inspect:

```bash
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:

```bash
git-agent-memory exclude
```

Re-enable for current repo:

```bash
git-agent-memory include
```

Remove global hook:

```bash
git-agent-memory uninstall
```

Check current state:

```bash
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 <module> based on past failure patterns."

## Commands

```bash
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:

```yaml
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

```bash
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](LICENSE).