claudememory 0.1.0__tar.gz

claudememory-0.1.0/CLAUDE.md

@@ -0,0 +1,97 @@
+<!-- git-memory:start -->
+
+# Git Memory System
+
+This project provides **git-memory** — 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 git-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 | `/git-memory-search` |
+| Index a new repository | `/git-memory-index` |
+| Debug why a component behaves a certain way | `/git-memory-debug` |
+| Check what's currently indexed | `/git-memory-status` |
+
+## MCP Tools Reference
+
+These tools are available when the `git-memory` 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? | git-memory `search_git_history(symbol)` |
+| What will break if I change this? | GitNexus `impact(symbol)` |
+| Has this area had bugs before? | git-memory `bug_fix_history(component)` |
+| What changed recently? | git-memory `latest_commits(10)` |
+
+## Setup for a New Repository
+
+```bash
+# 1. Index the repo
+git-memory index --repo-path /path/to/repo --user-id my-repo
+
+# 2. Install Claude Code plugin (skills + MCP config)
+git-memory install --repo-path /path/to/repo --user-id my-repo
+
+# 3. Restart Claude Code
+```
+
+<!-- git-memory:end -->

claudememory-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include CLAUDE.md
+include LICENSE
+recursive-include skills *.md
+recursive-include config *.json
+include hooks/post-commit

claudememory-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: claudememory
+Version: 0.1.0
+Summary: Dual-layer ChromaDB + Mem0 Git commit index for Claude Code
+License: MIT
+Keywords: claude-code,mcp,git,memory,chromadb,mem0,ai,claudememory
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: gitpython>=3.1.40
+Requires-Dist: mem0ai>=0.1.0
+Requires-Dist: fastmcp>=0.4.0
+Requires-Dist: chromadb>=1.0.0
+Requires-Dist: ollama>=0.3.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=2.2.0; extra == "sentence-transformers"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+
+# git-memory
+
+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 git-memory
+```
+
+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 "git-memory[sentence-transformers]"` | Free, fully local, no Ollama |
+| **OpenAI** | `pip install "git-memory[openai]"` + `OPENAI_API_KEY` | ~$0.0001/commit |
+
+## Quick start
+
+```bash
+# 1. Index your repository
+git-memory index --repo-path /path/to/repo --user-id my-repo
+
+# 2. Install Claude Code skills + MCP config
+git-memory install --repo-path /path/to/repo --user-id my-repo
+
+# 3. Restart Claude Code — then use /git-memory-search, /git-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
+git-memory index    --repo-path . --user-id myapp   # bulk index
+git-memory serve                                     # start MCP server (stdio)
+git-memory status   --repo-path .                    # show coverage
+git-memory install  --repo-path . --user-id myapp   # install plugin
+git-memory store    HEAD                             # store single commit (hook)
+```
+
+## Configuration
+
+All settings via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_MEMORY_REPO_PATH` | `.` | Repository to index |
+| `GIT_MEMORY_USER_ID` | `git_memory_system` | Mem0 namespace (use per-repo names) |
+| `GIT_MEMORY_CHROMA_DIR` | `~/.cache/git_memory/chroma_commits` | ChromaDB storage path |
+| `GIT_MEMORY_EMBED_PROVIDER` | `ollama` | Embedding backend: `ollama`, `openai`, `sentence-transformers` |
+| `GIT_MEMORY_EMBED_MODEL` | *(provider default)* | Override embedding model name |
+| `GIT_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/your-org/gitnexus)
+
+- GitNexus answers **what calls what** (structural, live code)
+- git-memory answers **why it was written that way** (historical, commit-level)

claudememory-0.1.0/README.md

@@ -0,0 +1,75 @@
+# git-memory
+
+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 git-memory
+```
+
+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 "git-memory[sentence-transformers]"` | Free, fully local, no Ollama |
+| **OpenAI** | `pip install "git-memory[openai]"` + `OPENAI_API_KEY` | ~$0.0001/commit |
+
+## Quick start
+
+```bash
+# 1. Index your repository
+git-memory index --repo-path /path/to/repo --user-id my-repo
+
+# 2. Install Claude Code skills + MCP config
+git-memory install --repo-path /path/to/repo --user-id my-repo
+
+# 3. Restart Claude Code — then use /git-memory-search, /git-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
+git-memory index    --repo-path . --user-id myapp   # bulk index
+git-memory serve                                     # start MCP server (stdio)
+git-memory status   --repo-path .                    # show coverage
+git-memory install  --repo-path . --user-id myapp   # install plugin
+git-memory store    HEAD                             # store single commit (hook)
+```
+
+## Configuration
+
+All settings via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_MEMORY_REPO_PATH` | `.` | Repository to index |
+| `GIT_MEMORY_USER_ID` | `git_memory_system` | Mem0 namespace (use per-repo names) |
+| `GIT_MEMORY_CHROMA_DIR` | `~/.cache/git_memory/chroma_commits` | ChromaDB storage path |
+| `GIT_MEMORY_EMBED_PROVIDER` | `ollama` | Embedding backend: `ollama`, `openai`, `sentence-transformers` |
+| `GIT_MEMORY_EMBED_MODEL` | *(provider default)* | Override embedding model name |
+| `GIT_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/your-org/gitnexus)
+
+- GitNexus answers **what calls what** (structural, live code)
+- git-memory answers **why it was written that way** (historical, commit-level)

claudememory-0.1.0/claudememory.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: claudememory
+Version: 0.1.0
+Summary: Dual-layer ChromaDB + Mem0 Git commit index for Claude Code
+License: MIT
+Keywords: claude-code,mcp,git,memory,chromadb,mem0,ai,claudememory
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: gitpython>=3.1.40
+Requires-Dist: mem0ai>=0.1.0
+Requires-Dist: fastmcp>=0.4.0
+Requires-Dist: chromadb>=1.0.0
+Requires-Dist: ollama>=0.3.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=2.2.0; extra == "sentence-transformers"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+
+# git-memory
+
+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 git-memory
+```
+
+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 "git-memory[sentence-transformers]"` | Free, fully local, no Ollama |
+| **OpenAI** | `pip install "git-memory[openai]"` + `OPENAI_API_KEY` | ~$0.0001/commit |
+
+## Quick start
+
+```bash
+# 1. Index your repository
+git-memory index --repo-path /path/to/repo --user-id my-repo
+
+# 2. Install Claude Code skills + MCP config
+git-memory install --repo-path /path/to/repo --user-id my-repo
+
+# 3. Restart Claude Code — then use /git-memory-search, /git-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
+git-memory index    --repo-path . --user-id myapp   # bulk index
+git-memory serve                                     # start MCP server (stdio)
+git-memory status   --repo-path .                    # show coverage
+git-memory install  --repo-path . --user-id myapp   # install plugin
+git-memory store    HEAD                             # store single commit (hook)
+```
+
+## Configuration
+
+All settings via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_MEMORY_REPO_PATH` | `.` | Repository to index |
+| `GIT_MEMORY_USER_ID` | `git_memory_system` | Mem0 namespace (use per-repo names) |
+| `GIT_MEMORY_CHROMA_DIR` | `~/.cache/git_memory/chroma_commits` | ChromaDB storage path |
+| `GIT_MEMORY_EMBED_PROVIDER` | `ollama` | Embedding backend: `ollama`, `openai`, `sentence-transformers` |
+| `GIT_MEMORY_EMBED_MODEL` | *(provider default)* | Override embedding model name |
+| `GIT_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/your-org/gitnexus)
+
+- GitNexus answers **what calls what** (structural, live code)
+- git-memory answers **why it was written that way** (historical, commit-level)

claudememory-0.1.0/claudememory.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+CLAUDE.md
+MANIFEST.in
+README.md
+pyproject.toml
+claudememory.egg-info/PKG-INFO
+claudememory.egg-info/SOURCES.txt
+claudememory.egg-info/dependency_links.txt
+claudememory.egg-info/entry_points.txt
+claudememory.egg-info/requires.txt
+claudememory.egg-info/top_level.txt
+config/mcp_config_example.json
+git_memory/__init__.py
+git_memory/chroma_index.py
+git_memory/cli.py
+git_memory/filters.py
+git_memory/indexer.py
+skills/git-memory-debug/SKILL.md
+skills/git-memory-index/SKILL.md
+skills/git-memory-search/SKILL.md
+skills/git-memory-status/SKILL.md

claudememory-0.1.0/claudememory.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

claudememory-0.1.0/claudememory.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+git-memory = git_memory.cli:main
+git-memory-index = git_memory.cli:index_cmd
+git-memory-serve = git_memory.cli:serve_cmd
+git-memory-store = git_memory.cli:store_cmd

claudememory-0.1.0/claudememory.egg-info/requires.txt

@@ -0,0 +1,16 @@
+gitpython>=3.1.40
+mem0ai>=0.1.0
+fastmcp>=0.4.0
+chromadb>=1.0.0
+ollama>=0.3.0
+
+[dev]
+pytest
+ruff
+mypy
+
+[openai]
+openai>=1.0.0
+
+[sentence-transformers]
+sentence-transformers>=2.2.0

claudememory-0.1.0/claudememory.egg-info/top_level.txt

@@ -0,0 +1 @@
+git_memory

claudememory-0.1.0/config/mcp_config_example.json

@@ -0,0 +1,15 @@
+{
+  "_comment": "Add the 'mcpServers' block to your existing ~/.claude/claude_desktop_config.json",
+  "mcpServers": {
+    "git-memory": {
+      "command": "python",
+      "args": ["/ABSOLUTE/PATH/TO/YOUR/REPO/ai/git_memory_mcp_server.py"],
+      "env": {
+        "GIT_MEMORY_REPO_PATH": "/ABSOLUTE/PATH/TO/YOUR/REPO",
+        "GIT_MEMORY_USER_ID": "git_memory_system",
+        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_OR_LEAVE_EMPTY_FOR_LOCAL_CHROMA",
+        "GIT_MEMORY_CHROMA_DIR": "/Users/YOU/.cache/git_memory/chroma"
+      }
+    }
+  }
+}

claudememory-0.1.0/git_memory/__init__.py

@@ -0,0 +1,27 @@
+"""
+git-memory — Dual-layer ChromaDB + Mem0 commit index for Claude Code.
+
+Layers:
+  ChromaDB  — 1 document per commit, cosine similarity, metadata filters
+  Mem0      — LLM-extracted context, cross-session learned interpretation
+
+Usage:
+    git-memory index --repo-path /path/to/repo
+    git-memory serve
+    git-memory install   # installs Claude Code plugin
+"""
+
+__version__ = "0.1.0"
+__author__  = "Güneş Bizim"
+
+from git_memory.chroma_index import ChromaCommitIndex
+from git_memory.indexer      import GitMemoryIndexer
+from git_memory.filters      import is_relevant, summarize_commit, build_metadata
+
+__all__ = [
+    "ChromaCommitIndex",
+    "GitMemoryIndexer",
+    "is_relevant",
+    "summarize_commit",
+    "build_metadata",
+]

claudememory-0.1.0/git_memory/chroma_index.py

@@ -0,0 +1,190 @@
+"""
+ChromaDB layer for git commits.
+1 document = 1 commit — no fragmentation, no LLM extraction overhead.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+import chromadb
+
+log = logging.getLogger(__name__)
+
+CHROMA_DIR     = os.getenv("GIT_MEMORY_CHROMA_DIR",
+                            str(Path.home() / ".cache" / "git_memory" / "chroma_commits"))
+OLLAMA_URL     = os.getenv("OLLAMA_URL", "http://localhost:11434")
+EMBED_MODEL    = os.getenv("GIT_MEMORY_EMBED_MODEL", "nomic-embed-text")
+EMBED_PROVIDER = os.getenv("GIT_MEMORY_EMBED_PROVIDER", "ollama")  # ollama | openai | sentence-transformers
+COLLECTION     = "git_commits"
+
+
+def _build_embedding_function():
+    """Return a ChromaDB embedding function based on GIT_MEMORY_EMBED_PROVIDER."""
+    if EMBED_PROVIDER == "openai":
+        from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction
+        model = os.getenv("GIT_MEMORY_EMBED_MODEL", "text-embedding-3-small")
+        return OpenAIEmbeddingFunction(
+            api_key=os.environ["OPENAI_API_KEY"],
+            model_name=model,
+        )
+    if EMBED_PROVIDER == "sentence-transformers":
+        from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction
+        model = os.getenv("GIT_MEMORY_EMBED_MODEL", "all-MiniLM-L6-v2")
+        return SentenceTransformerEmbeddingFunction(model_name=model)
+    # default: ollama
+    from chromadb.utils.embedding_functions import OllamaEmbeddingFunction
+    return OllamaEmbeddingFunction(
+        url=f"{OLLAMA_URL}/api/embeddings",
+        model_name=EMBED_MODEL,
+    )
+
+
+def _build_document(commit_hash, author, date, message, stats, files):
+    files_str = ", ".join(files) if files else "none"
+    return (
+        f"{message.strip()}\n"
+        f"Author: {author}\n"
+        f"Date: {date}\n"
+        f"Stats: {stats}\n"
+        f"Files: {files_str}"
+    )
+
+
+class ChromaCommitIndex:
+    """1 ChromaDB document per Git commit — fast, accurate, no LLM overhead."""
+
+    def __init__(self, chroma_dir=CHROMA_DIR):
+        Path(chroma_dir).mkdir(parents=True, exist_ok=True)
+        self._client = chromadb.PersistentClient(path=chroma_dir)
+        self._ef = _build_embedding_function()
+        self._col = self._client.get_or_create_collection(
+            name=COLLECTION,
+            embedding_function=self._ef,
+            metadata={"hnsw:space": "cosine"},
+        )
+
+    def upsert_commit(self, commit_hash, author_name, author_email, committed_date,
+                      message, category, files, stats_str, repo) -> bool:
+        if self._col.get(ids=[commit_hash])["ids"]:
+            return False
+        self._col.add(
+            ids=[commit_hash],
+            documents=[_build_document(
+                commit_hash, f"{author_name} <{author_email}>",
+                committed_date[:10], message, stats_str, files,
+            )],
+            metadatas=[{
+                "short_hash":     commit_hash[:8],
+                "author_name":    author_name,
+                "author_email":   author_email,
+                "committed_date": committed_date,
+                "category":       category,
+                "repo":           repo,
+                "files_str":      "|".join(files),
+                "date_str":       committed_date[:10],
+            }],
+        )
+        return True
+
+    def search(self, query, n_results=10, category=None, repo=None) -> list[dict]:
+        where = self._build_where(category=category, repo=repo)
+        kwargs = dict(
+            query_texts=[query],
+            n_results=min(n_results, max(1, self._col.count())),
+            include=["documents", "metadatas", "distances"],
+        )
+        if where:
+            kwargs["where"] = where
+        try:
+            return self._format_results(self._col.query(**kwargs))
+        except Exception as exc:
+            log.error("Chroma search error: %s", exc)
+            return []
+
+    def get_latest(self, n=10, repo=None) -> list[dict]:
+        where = self._build_where(repo=repo)
+        count = self._col.count()
+        if count == 0:
+            return []
+        kwargs = dict(limit=min(count, max(n * 3, 50)), include=["documents", "metadatas"])
+        if where:
+            kwargs["where"] = where
+        try:
+            raw = self._col.get(**kwargs)
+        except Exception as exc:
+            log.error("Chroma get_latest error: %s", exc)
+            return []
+        records = [
+            {
+                "commit_hash":   raw["ids"][i],
+                "short_hash":    raw["metadatas"][i].get("short_hash", ""),
+                "author":        raw["metadatas"][i].get("author_name", ""),
+                "date":          raw["metadatas"][i].get("committed_date", ""),
+                "category":      raw["metadatas"][i].get("category", "general"),
+                "files_changed": [f for f in raw["metadatas"][i].get("files_str","").split("|") if f],
+                "summary":       (raw.get("documents") or [""])[i],
+                "source":        "chroma",
+            }
+            for i in range(len(raw["ids"]))
+        ]
+        records.sort(key=lambda r: r.get("date", ""), reverse=True)
+        return records[:n]
+
+    def search_by_file(self, filename, n_results=20) -> list[dict]:
+        try:
+            all_docs = self._col.get(include=["metadatas", "documents"])
+            matched = [
+                {
+                    "commit_hash":   all_docs["ids"][i],
+                    "short_hash":    m.get("short_hash", ""),
+                    "author":        m.get("author_name", ""),
+                    "date":          m.get("committed_date", ""),
+                    "category":      m.get("category", "general"),
+                    "files_changed": [f for f in m.get("files_str","").split("|") if f],
+                    "summary":       (all_docs.get("documents") or [""])[i],
+                    "source":        "chroma",
+                }
+                for i, m in enumerate(all_docs["metadatas"])
+                if filename.lower() in m.get("files_str", "").lower()
+            ]
+            if matched:
+                matched.sort(key=lambda r: r.get("date",""), reverse=True)
+                return matched[:n_results]
+        except Exception:
+            pass
+        return self.search(f"changes to {filename}", n_results=n_results)
+
+    def count(self) -> int:
+        return self._col.count()
+
+    @staticmethod
+    def _build_where(category=None, repo=None) -> Optional[dict]:
+        conds = []
+        if category: conds.append({"category": {"$eq": category}})
+        if repo:     conds.append({"repo":     {"$eq": repo}})
+        if not conds:        return None
+        if len(conds) == 1:  return conds[0]
+        return {"$and": conds}
+
+    @staticmethod
+    def _format_results(raw) -> list[dict]:
+        ids, docs, metas, dists = (
+            raw.get("ids",[[]])[0], raw.get("documents",[[]])[0],
+            raw.get("metadatas",[[]])[0], raw.get("distances",[[]])[0],
+        )
+        return [
+            {
+                "commit_hash":     h,
+                "short_hash":      metas[i].get("short_hash", h[:8]),
+                "author":          metas[i].get("author_name", "unknown"),
+                "date":            metas[i].get("committed_date", ""),
+                "category":        metas[i].get("category", "general"),
+                "files_changed":   [f for f in metas[i].get("files_str","").split("|") if f],
+                "summary":         docs[i] if docs else "",
+                "relevance_score": round(1.0 - float(dists[i] if dists else 1.0), 4),
+                "source":          "chroma",
+            }
+            for i, h in enumerate(ids)
+        ]