Installation¶

Supported platforms¶

Platform	Architecture	Python
Linux	x86_64, aarch64	3.10 – 3.14
macOS	x86_64, arm64	3.10 – 3.14
Windows	x86_64	3.10 – 3.14

A single wheel per platform covers all supported Python versions via the stable ABI (abi3-py310).

Basic install¶

# Core SemvecState, memory tiers, phase detector, token reduction
pip install semvec

With extras¶

# Multi-agent coordination primitives
pip install "semvec[cortex]"

# Coding-agent compaction + MCP server + Claude Code hooks
pip install "semvec[coding]"

# REST API — starts the FastAPI server via `semvec serve`
pip install "semvec[api]"

# Benchmark harness dependencies (SentenceTransformers, datasets, psutil)
pip install "semvec[benchmarks]"

# Optional Mem0 head-to-head baseline for benchmarks
pip install "semvec[mem0]"

# Developer tooling (ruff, mypy, pre-commit, pytest, httpx)
pip install "semvec[dev]"

# mkdocs-material for the documentation site
pip install "semvec[docs]"

# Everything the developers use
pip install "semvec[cortex,coding,api,benchmarks,dev,docs]"

Extra	Pulls in	When you need it
`[cortex]`	— (marker only)	multi-agent coordination is always available; the extra marks intent for future pip resolvers
`[coding]`	`fastmcp>=2.0`	MCP server + Claude Code hooks
`[api]`	`fastapi`, `uvicorn[standard]`, `slowapi`, `sqlalchemy`, `prometheus-client`, `pydantic`	REST API server — see REST API
`[benchmarks]`	`sentence-transformers>=3.0`, `datasets>=2.14`, `psutil>=5.9`	running any harness under `benchmarks/` or `semvec.benchmarks.longmemeval`
`[mem0]`	`mem0ai>=0.1`, `faiss-cpu>=1.7`	head-to-head Mem0 comparison
`[dev]`	`ruff`, `mypy`, `pre-commit`, `pytest`, `httpx`	contributing — includes the FastAPI TestClient transport
`[docs]`	`mkdocs>=1.6`, `mkdocs-material>=9.5`, `pymdown-extensions`	building this site (`mkdocs serve`)

Embedder¶

Semvec does not ship an embedder and refuses to fall back to hash-based pseudo-embeddings. You need one of:

pip install sentence-transformers        # most common
pip install sentence-transformers torch  # with a torch backend of your choice

Any object exposing get_embedding(text) -> np.ndarray and get_dimension() -> int works — see the quickstart.

Licensing¶

Community tier works without a key but is rate-limited to 5 QPS sustained / 50 burst and in-memory backends only. Pro and Enterprise tiers require a signed JWT:

export SEMVEC_LICENSE_KEY="eyJhbGciOiJFZERTQSI..."

See Licensing for tier details and error handling.

Developing locally¶

Clone, build from source, and run the full test suite:

git clone https://github.com/MichaelNeuberger/semvec.git
cd semvec
python -m venv .venv
.venv/bin/pip install --upgrade pip maturin pytest numpy sentence-transformers
.venv/bin/pip install -v .
.venv/bin/python -m pytest tests/

See CONTRIBUTING.md for the full build/test/release loop including Rust unit tests and wheel verification.