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