git-memory

A semantic index over your Git commit history for Claude Code. Gives Claude an MCP server with 5 tools to query what changed, why, and where — before it edits your code.

Node.js port of claude-memory (Python).

How it works

git-memory walks your Git log, filters signal-rich commits, embeds them with a local or cloud embedding model, and stores them in ChromaDB. An MCP server exposes 5 query tools to Claude Code so it can answer "what's the history of this module?" before touching it.

git history → filter → embed → ChromaDB → MCP tools → Claude Code

Requirements

• Node.js 18+
• Git repository to index
• One of the following embedding providers:
  • Ollama (default) — run ollama pull nomic-embed-text and ollama serve
  • OpenAI — set OPENAI_API_KEY
  • fastembed — fully local, no server needed

Installation

npm install -g git-memory

Or use directly without installing:

npx git-memory index --repo-path /path/to/repo --user-id my-repo

Quick Start

1. Index your repository

# Dry run first — see what will be indexed
git-memory index --repo-path /path/to/repo --user-id my-repo --dry-run

# Full index
git-memory index --repo-path /path/to/repo --user-id my-repo

From within the repo directory:

cd /path/to/repo
git-memory index --user-id my-repo

For large repos (>1000 commits), limit to recent history:

git-memory index --user-id my-repo --limit 500

2. Install the MCP server into Claude Code

git-memory install --repo-path /path/to/repo --user-id my-repo

This writes the MCP server config to .claude.json in your repo.

3. Restart Claude Code

The MCP tools are now available in Claude Code sessions for that repo.

MCP Tools

Once installed, Claude Code has access to these 5 tools:

| Tool | Description | |------|-------------| | search_git_history(query, limit, category) | Semantic search over commit messages and metadata | | latest_commits(limit) | Most recent indexed commits | | commits_touching_file(filename, limit) | All commits that modified a file | | bug_fix_history(component, include_security) | Bug and security fixes for a component | | architecture_decisions(topic, limit) | Refactors, migrations, design decisions |

Category filter

Pass category= to search_git_history to narrow results:

| Value | Matches | |-------|---------| | fix | Bug fixes, hotfixes, patches | | feat | New features | | security | Security-related changes | | refactor | Code refactors | | migration | Database/schema migrations | | arch | Architecture decisions | | perf | Performance improvements |

Check status

git-memory status --repo-path /path/to/repo

Expected output:

── git-memory status ──────────────────────────
  Repo          : my-repo
  Chroma docs   : 39 (this repo) / 39 (all repos)
  Total commits : 42
  Coverage      : 93%
  Embed provider: ollama

Configuration

All options can be set via environment variables or CLI flags.

| Environment Variable | CLI Flag | Default | Description | |---------------------|----------|---------|-------------| | GIT_MEMORY_REPO_PATH | --repo-path | cwd | Path to the Git repo | | GIT_MEMORY_USER_ID | --user-id | git_memory_system | Unique ID per repo (used to namespace the index) | | GIT_MEMORY_EMBED_PROVIDER | — | ollama | Embedding provider: ollama, openai, fastembed | | GIT_MEMORY_EMBED_MODEL | — | nomic-embed-text | Embedding model name | | GIT_MEMORY_LLM_MODEL | — | qwen2.5 | LLM for context enrichment (Layer 2) | | OLLAMA_URL | — | http://localhost:11434 | Ollama server URL | | OPENAI_API_KEY | — | — | Required when using OpenAI provider | | GIT_MEMORY_CHROMA_DIR | — | ~/.cache/git_memory/chroma_commits | ChromaDB storage path | | GIT_MEMORY_CONTEXT_DIR | — | ~/.cache/git_memory/chroma_context | Context store path |

Embedding providers

Ollama (default)

ollama pull nomic-embed-text
ollama serve
git-memory index --user-id my-repo

OpenAI

export OPENAI_API_KEY=sk-...
export GIT_MEMORY_EMBED_PROVIDER=openai
export GIT_MEMORY_EMBED_MODEL=text-embedding-3-small
git-memory index --user-id my-repo

fastembed (fully local, no server)

export GIT_MEMORY_EMBED_PROVIDER=fastembed
# Uses BAAI/bge-small-en-v1.5 by default
git-memory index --user-id my-repo

MCP config reference

The install command writes this to .claude.json automatically. You can also configure it manually:

{
  "mcpServers": {
    "git-memory": {
      "command": "git-memory",
      "args": ["serve"],
      "env": {
        "GIT_MEMORY_REPO_PATH": "/path/to/repo",
        "GIT_MEMORY_USER_ID": "my-repo-name",
        "GIT_MEMORY_EMBED_PROVIDER": "ollama",
        "GIT_MEMORY_EMBED_MODEL": "nomic-embed-text",
        "GIT_MEMORY_LLM_MODEL": "qwen2.5",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

Claude Code skills

git-memory ships four Claude Code skills in the skills/ directory. These guide Claude on when and how to use the MCP tools:

| Skill | Trigger phrase | |-------|---------------| | git-memory-index | "index this repo", "set up git memory" | | git-memory-search | "why was this written this way?", "find commits touching auth" | | git-memory-debug | "why did this break?", "trace all changes to OrderService" | | git-memory-status | "is git memory set up?", "how many commits are indexed?" |

Add this to your CLAUDE.md to activate them:

When beginning any task:
1. Call `latest_commits(5)` to understand recent changes
2. Call `search_git_history(<topic>)` before editing any module
3. After fixing a bug, call `bug_fix_history(<component>)` to check for prior regressions

Development

git clone https://github.com/YOUR_ORG/git-memory
cd git-memory
npm install

# Run CLI without building
npm run dev -- index --user-id test

# Start MCP server in dev mode
npm run serve:dev

# Build TypeScript
npm run build

Troubleshooting

| Symptom | Fix | |---------|-----| | 0 commits indexed | Run git-memory index --repo-path . | | MCP tools return errors | Check Ollama is running: ollama serve | | Wrong user-id | Must match GIT_MEMORY_USER_ID in MCP config | | Search returns nothing | Confirm index has data: git-memory status | | Layer 2 context missing | Normal if LLM is unavailable — Layer 1 (ChromaDB) still works |

License

AGPL-3.0-or-later