# claudememory

Dual-layer semantic index over Git commit history for Claude Code.

| Layer | Purpose |
|-------|---------|
| **ChromaDB** | 1 document/commit, cosine similarity, metadata filters — fast, authoritative facts |
| **Mem0** | LLM-extracted context, cross-session learned interpretation — the *why* layer |

## Install

```bash
pip install claudememory
```

No external services required — works out of the box with three embedding options:

| Mode | Setup | Cost |
|------|-------|------|
| **Ollama** (default) | `ollama pull nomic-embed-text` | Free, fully local |
| **sentence-transformers** | `pip install "claudememory[sentence-transformers]"` | Free, fully local, no Ollama |
| **OpenAI** | `pip install "claudememory[openai]"` + `OPENAI_API_KEY` | ~$0.0001/commit |

## Quick start

```bash
# 1. Index your repository
claude-memory index --repo-path /path/to/repo --user-id my-repo

# 2. Install Claude Code skills + MCP config
claude-memory install --repo-path /path/to/repo --user-id my-repo

# 3. Restart Claude Code — then use /claude-memory-search, /claude-memory-debug etc.
```

## MCP tools

| Tool | Description |
|------|-------------|
| `search_git_history(query)` | Semantic search over commit history |
| `latest_commits(limit)` | N most-recent indexed commits |
| `commits_touching_file(filename)` | All commits that modified a file |
| `bug_fix_history(component)` | Bug/security fixes for a component |
| `architecture_decisions(topic)` | Refactors, migrations, design decisions |

## CLI

```bash
claude-memory index    --repo-path . --user-id myapp   # bulk index
claude-memory serve                                     # start MCP server (stdio)
claude-memory status   --repo-path .                    # show coverage
claude-memory install  --repo-path . --user-id myapp   # install plugin
claude-memory store    HEAD                             # store single commit (hook)
```

## Configuration

All settings via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_MEMORY_REPO_PATH` | `.` | Repository to index |
| `CLAUDE_MEMORY_USER_ID` | `claude_memory_system` | Mem0 namespace (use per-repo names) |
| `CLAUDE_MEMORY_CHROMA_DIR` | `~/.cache/claude_memory/chroma_commits` | ChromaDB storage path |
| `CLAUDE_MEMORY_EMBED_PROVIDER` | `ollama` | Embedding backend: `ollama`, `openai`, `sentence-transformers` |
| `CLAUDE_MEMORY_EMBED_MODEL` | *(provider default)* | Override embedding model name |
| `CLAUDE_MEMORY_LLM_MODEL` | *(provider default)* | Override LLM model name (Mem0 layer) |
| `OPENAI_API_KEY` | *(empty)* | Enables OpenAI embeddings + LLM automatically |
| `MEM0_API_KEY` | *(empty)* | Use Mem0 cloud instead of local inference |
| `OLLAMA_URL` | `http://localhost:11434` | Ollama endpoint |

## Works great alongside [GitNexus](https://github.com/abhigyanpatwari/GitNexus)

- GitNexus answers **what calls what** (structural, live code)
- claudememory answers **why it was written that way** (historical, commit-level)
