<!-- claude-memory:start -->

# Claude Memory System

This project provides **claudememory** — a dual-layer semantic index over Git commit history for Claude Code.

Two storage layers work together:
- **ChromaDB** — 1 document per commit, cosine similarity, metadata filters (fast, authoritative facts)
- **Mem0** — LLM-extracted context, cross-session learned interpretation (why things were built a certain way)

## Always Start Here

When beginning any task in a repository that has claude-memory configured:

1. Call `latest_commits(5)` to understand what changed recently
2. Call `search_git_history(<relevant topic>)` before touching any module with history
3. After fixing a bug, call `bug_fix_history(<component>)` to check for prior regressions

## Available Skills

| Task | Skill |
|------|-------|
| Search commit history for a topic | `/claude-memory-search` |
| Index a new repository | `/claude-memory-index` |
| Debug why a component behaves a certain way | `/claude-memory-debug` |
| Check what's currently indexed | `/claude-memory-status` |

## MCP Tools Reference

These tools are available when the `claudememory` MCP server is running.

| Tool | What it gives you | When to use |
|------|-------------------|-------------|
| `search_git_history(query, limit, category)` | Commits semantically related to a topic | Before editing any significant module |
| `latest_commits(limit)` | N most-recent indexed commits | Session start, before investigating regressions |
| `commits_touching_file(filename, limit)` | All commits that modified a file | Before editing a file — understand its history |
| `bug_fix_history(component, include_security)` | Bug/security fixes for a component | Before adding new code near known bug areas |
| `architecture_decisions(topic, limit)` | Refactors, migrations, design decisions | Understanding why code is structured a certain way |

## Proactive Usage Rules

**Always call before editing:**
```
commits_touching_file("PaymentService.php")  # know what's broken here before
bug_fix_history("auth")                       # avoid re-introducing fixed bugs
```

**Always call at session start:**
```
latest_commits(10)   # what changed while you were away?
```

**Always call when confused about design:**
```
architecture_decisions("state machine")  # why was this abstraction introduced?
search_git_history("why was X removed")
```

## Category Filter Values

Use `category=` in `search_git_history()` to narrow results:

| Category | 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 |

## Integration with GitNexus

If GitNexus is also configured, use both systems together:

| Question | Use |
|----------|-----|
| What does this function call? | GitNexus `context(symbol)` |
| Why was this function written this way? | claude-memory `search_git_history(symbol)` |
| What will break if I change this? | GitNexus `impact(symbol)` |
| Has this area had bugs before? | claude-memory `bug_fix_history(component)` |
| What changed recently? | claude-memory `latest_commits(10)` |

## Setup for a New Repository

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

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

# 3. Restart Claude Code
```


# currentDate
Today's date is 2026-03-13.

      IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.
<!-- claude-memory:end -->
