Contributing to memsearch

Contributing to memsearch

Thanks for your interest in contributing! This guide will help you get set up and submit your first PR.

Questions or ideas? Join the [Discord](https://discord.com/invite/FG6hMJStWu).

Getting Started

git clone https://github.com/zilliztech/memsearch.git
cd memsearch
uv sync --all-extras
uv run pre-commit install

**Dependency management:** Use `uv` and `pyproject.toml` — never `pip install` directly.

**Pre-commit hooks:** The `pre-commit install` step registers Git hooks that run `ruff check --fix` and `ruff format` on staged files before each commit.

Running Tests

# Full suite
uv run python -m pytest

# Single file
uv run python -m pytest tests/test_chunker.py

# Single test with verbose output
uv run python -m pytest tests/test_store.py::test_upsert_and_search -v

# With coverage report
uv run python -m pytest --cov=memsearch --cov-report=term-missing

**Note:** Always use `uv run python -m pytest` instead of `uv run pytest` to avoid picking up a system-level pytest.

Code Style

The project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting. CI will fail if either check doesn't pass.

uv run ruff check src/ tests/      # lint
uv run ruff format src/ tests/     # format

undefined

Commits and Pull Requests

Use [Conventional Commits](https://www.conventionalcommits.org/) prefixes for **PR titles**:

Prefix	Example
feat:	feat: add date filtering to search
fix:	fix: handle empty markdown files in scanner
docs:	docs: add troubleshooting guide
ci:	ci: update GitHub Actions versions
chore:	chore: bump dependencies
refactor:	refactor: simplify config merging logic
test:	test: add transcript parser edge cases

Workflow

undefined

Project Structure

src/memsearch/              # Core Python library
├── core.py                 # MemSearch public API (index, search, watch, compact)
├── cli.py                  # Click CLI
├── store.py                # Milvus vector store (hybrid search, upsert, dedup)
├── chunker.py              # Markdown heading-based chunking + SHA-256 hash
├── embeddings/             # Pluggable embedding providers (onnx, openai, google, etc.)
├── scanner.py