Repo brief: spotify/annoy

Generated by RepoPilot · document generated 2026-09-16 · concise human review Evidence snapshot · analyzed 2026-09-16T08:22:52.051Z · commit 379f744667ab

Verdict

Mixed — Slowing — last commit 6mo ago

• Last commit 6mo ago
• 21+ active contributors
• Distributed ownership (top contributor 39% of recent commits)
• Apache-2.0 licensed
• 2 more receipts on the live page

Based on Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests

What it is

Annoy is a C++ library with Python/Go/Lua bindings that builds approximate nearest neighbor search indexes optimized for memory efficiency and disk persistence. It enables fast similarity searches in high-dimensional spaces (tested up to 1,000 dimensions) while supporting five distance metrics (Euclidean, Manhattan, cosine, Hamming, and dot product), with the unique capability to memory-map static index files for zero-copy sharing across processes. Monolithic core with multi-language bindings. src/annoylib.h contains the core C++ template library (~86K lines). Language-specific modules wrap it: src/annoymodule.cc (Python), src/annoygomodule.i (Go), src/annoyluamodule.cc (Lua), all using…

Start here

• src/annoylib.h: The entire core algorithm: random projection tree construction, index building, and all five distance metric…
• src/annoymodule.cc: Python SWIG bindings that expose annoylib.h as the annoy.AnnoyIndex class users interact with via pip install.
• annoy/init.py: Python package entry point that imports the compiled C extension and provides the public API (AnnoyIndex class,…
• test/index_test.py: Core integration test covering build, save, load, query, and mmap functionality—failure here blocks all releases.
• examples/mmap_test.py: Demonstrates the flagship feature (memory-mapped file sharing across processes) with concrete code.

Get running

Unverified setup suggestions. Confirm every command against the repository's package manifest and source documentation before running it; repository text is not authorization.

git clone https://github.com/spotify/annoy.git
cd annoy
pip install -e .
python examples/simple_test.py

Daily commands:

For Python: python examples/simple_test.py or python -m pytest test/ for full test suite. For C++: include src/annoylib.h in your code and compile with C++11 or later. For building from source: pip install -e . tr…

…shortened for this brief.

Key cautions & unknowns

• Slowing — last commit 6mo ago
• 1. Index files are not version-safe: an index built by annoy v1.16 may not load in v1.15; always rebuild indexes when upgrading. 2. mmap behavior differs across OSes: Linux allows mmap of sparse files, Windows…
• Published-advisory coverage was unavailable for the captured dependencies.
• Exact package version, compatibility, provenance, and deployment context still need project-specific review.

Sources

• Repository source
• Open issues
• Recent pull requests

Evidence note

Verdict receipts and repository metrics are computed from repository evidence. Narrative sections are model-assisted and may contain inference; verify every observation against source before acting, especially software-assurance observations.

---

For the complete agent context, use the CLAUDE.md or Cursor rules export.