Metadata-Version: 2.4
Name: claude-repo-mem
Version: 0.1.3
Summary: Durable, hierarchical, repo-scoped memory for Claude Code. Local-first MCP server with hybrid lexical + vector retrieval over your codebase, docs, and accumulated decisions.
Project-URL: Homepage, https://github.com/amritmalla/claude-repo-mem
Project-URL: Repository, https://github.com/amritmalla/claude-repo-mem
Project-URL: Issues, https://github.com/amritmalla/claude-repo-mem/issues
Project-URL: Changelog, https://github.com/amritmalla/claude-repo-mem/blob/main/CHANGELOG.md
Author-email: Yam Malla <amritmalla2021@gmail.com>
License: MIT
License-File: LICENSE
Keywords: anthropic,claude,claude-code,code-search,embeddings,llm,mcp,memory,rag,retrieval
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: sentence-transformers>=2.7
Requires-Dist: sqlite-vec>=0.1.3
Requires-Dist: tiktoken>=0.7
Requires-Dist: tree-sitter-go>=0.21
Requires-Dist: tree-sitter-java>=0.21
Requires-Dist: tree-sitter-javascript>=0.21
Requires-Dist: tree-sitter-python>=0.21
Requires-Dist: tree-sitter-rust>=0.21
Requires-Dist: tree-sitter-typescript>=0.21
Requires-Dist: tree-sitter>=0.21
Requires-Dist: watchdog>=4
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.34; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: voyage
Requires-Dist: voyageai>=0.2; extra == 'voyage'
Description-Content-Type: text/markdown

# claude-repo-mem

> Durable, hierarchical, repo-scoped memory for Claude Code. Local-first MCP server.

`claude-repo-mem` indexes your repository — code, docs, and your own accumulated decisions — into a SQLite database with hybrid lexical + vector retrieval, then exposes it to Claude Code as 11 MCP tools.

---

## Why claude-repo-mem

Working with an AI agent in a real codebase runs into the same friction every session:

- **Context burns fast.** Native `Read`/`Grep` pull whole files into the window to answer narrow questions. `recall` returns ranked, summarized, scoped results inside a token budget — full source for the top hits, summaries for the rest — so you spend context on what matters.
- **Following code flow is expensive.** Chasing a caller → handler → route by hand means repeated reads. `trace` walks the relation graph from a seed and returns the connected source in one round-trip.
- **Nothing carries across sessions.** Decisions, conventions, and the "why" behind the code evaporate when the conversation ends. `remember`, `handoff`, and `resume` persist durable memory and task state as git-trackable markdown.
- **It stays on your machine.** Everything lives in a single `.claude-repo-mem/` directory with a local embedding model by default — no code leaves the repo, no API key required.

The result: the agent treats your repo as the authoritative source for its own structure and history, instead of rediscovering it file-by-file each time.

---

## Install

```bash
pip install claude-repo-mem
```

Requires Python 3.11+.

---

## Quick start

```bash
cd your-repo
claude-repo-mem index               # build the index (downloads bge-small on first run, ~90MB)
claude-repo-mem doctor              # verify: units, by_layer, T2 coverage, counters
```

To expose it to Claude Code, drop a `.mcp.json` in your repo root:

```json
{
  "mcpServers": {
    "claude-repo-mem": {
      "command": "claude-repo-mem",
      "args": ["serve", "--watch"]
    }
  }
}
```

Claude Code will auto-launch the server on workspace load. The `--watch` flag runs an incremental file watcher (debounced 750ms) so the index stays current as you edit.

> No path needed under Claude Code: it injects `CLAUDE_PROJECT_DIR` into the server's environment, which the server uses to locate the index even though MCP servers are launched from a system working directory rather than your repo. Under a different MCP host that doesn't set `CLAUDE_PROJECT_DIR`, pin the repo with `"--root", "/abs/path"` or the `CLAUDE_REPO_MEM_ROOT` env var. See [docs/usage.md](docs/usage.md#wire-into-claude-code).

Prefer not to run the watcher? Install a git hook instead:

```bash
claude-repo-mem install-hooks       # writes .git/hooks/post-commit
```

---

## CLI

```text
claude-repo-mem index [--embedder NAME] [--no-embed] [--reset]
claude-repo-mem serve [--watch | --no-watch]
claude-repo-mem doctor                              # layer counts, T2 coverage, counters
claude-repo-mem install-hooks [--force]             # git post-commit reindex
claude-repo-mem distill [--yes] [--transcript PATH] # extract durable memories from a transcript
claude-repo-mem bench   --fixture queries.yaml [--k 5] [--no-embed]
```

---

## Languages and synthesizers

| Language | Parser | Notes |
|---|---|---|
| Python | tree-sitter | classes, methods, functions, docstrings |
| JavaScript / TypeScript | tree-sitter | functions, classes, methods, JSX |
| Java | tree-sitter | classes, interfaces, methods, constructors |
| Go | tree-sitter | funcs, methods, structs, interfaces |
| Rust | tree-sitter | fn, impl methods, structs, traits |
| Markdown | markdown-it | sections by heading hierarchy |

Synthesizers add cross-file edges on top of parser output:

- **Flask** `@app.route(...)` → handler.
- **Django** `path(...)` / `re_path(...)` → handler (resolves dotted refs against `views.py`).
- **Express** `app.METHOD(url, handler)` → same-file handler.
- **Python imports** → cross-module edges.
- **React hooks** — `useState` setter calls emit `mutates_state_of` edges on the containing component.

---

## Documentation

Full documentation lives in [`docs/`](docs/):

- [Usage guide](docs/usage.md) — indexing, Claude Code setup, configuration, workflows, troubleshooting.
- [Tool reference](docs/tools.md) — the 11 MCP tools, their parameters and returns.
- [Architecture](docs/architecture.md) — how indexing, storage, and retrieval work.
- [Contributing](CONTRIBUTING.md) — dev setup, tests, and release flow.

---

## License

MIT. See [`LICENSE`](LICENSE).

Release notes for each version live in [`CHANGELOG.md`](CHANGELOG.md).
