Metadata-Version: 2.5
Name: locusfiles
Version: 0.1.0
Summary: Local-first personal AI brain: index your own folders and search them from local MCP clients such as Claude Desktop, Claude Code and Cursor.
License-Expression: FSL-1.1-ALv2
License-File: src/locus/LICENSE
License-File: src/locus/NOTICE
License-File: src/locus/THIRD_PARTY_LICENSES.md
Requires-Python: >=3.11
Requires-Dist: chromadb<1.6,>=1.5
Requires-Dist: mcp<2.3,>=2.2
Requires-Dist: pydantic>=2.5
Requires-Dist: pypdfium2>=4.30
Requires-Dist: python-docx>=1.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: hatchling<2,>=1.27; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: lancedb
Requires-Dist: lancedb>=0.15; extra == 'lancedb'
Provides-Extra: local
Requires-Dist: sentence-transformers>=3.0; extra == 'local'
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == 'openai'
Provides-Extra: relay
Requires-Dist: cryptography>=42; extra == 'relay'
Requires-Dist: httpx>=0.27; extra == 'relay'
Requires-Dist: realtime<2.32,>=2.31; extra == 'relay'
Provides-Extra: voyage
Requires-Dist: voyageai>=0.3; extra == 'voyage'
Description-Content-Type: text/markdown

# Locus

Your files, your machine, the MCP clients you already use.

Locus indexes folders you choose on your own computer and gives MCP clients that can start a local
server (tested: Claude Desktop, Claude Code and Cursor) a semantic search tool over them. Every
result carries the file path, so the assistant can cite its sources.

The package is `locusfiles`; the command it installs is `locus`.

## Install

You need Python 3.11 or newer. Install with [pipx](https://pipx.pypa.io) or
[uv](https://docs.astral.sh/uv/), which put `locus` in its own environment. These commands work
once `locusfiles` is published on PyPI (first upload planned for 2026-10-01):

```bash
# On-device embeddings, no account (downloads PyTorch, about 1-2 GB):
pipx install "locusfiles[local]"
# or
uv tool install --python 3.12 "locusfiles[local]"

# A Locus plan (managed embeddings, remote connection), no PyTorch:
pipx install "locusfiles[relay]"
```

Other extras: `voyage` or `openai` to embed with your own provider key.

macOS and Linux are tested. Windows is not yet verified.

## First search

```bash
export LOCUS_EMBEDDER=local            # or managed (with LOCUS_API_KEY), voyage, openai
locus doctor                           # checks Python, packages, settings and the embedder
locus index ~/Documents/notes --prune  # parse, chunk, embed and index a folder
locus query "what did I decide about pricing" -k 5
```

Then connect your AI assistant: it runs `locus serve` (MCP over stdio). Setup steps for each
client are on the Locus website's Connect page (`/docs/connect`).

## What leaves your computer

- Local: Indexing and embeddings run on your computer. When your AI assistant searches, the
  matching excerpts go to that assistant, as they would if you pasted them in.
- Your own key: Chunk text goes straight from your computer to the embedding provider you chose,
  under your own account.
- Managed: On managed plans, chunk text passes through Locus's relay to Voyage AI to be embedded.
  We don't store it; we keep only usage counts.
- Remote: When you reach your computer from another device or a web AI app, your question and
  the matching excerpts travel through Locus's relay (Vercel and Supabase) to and from your
  computer. They are encrypted in transit and we don't store them.
- In every mode: Your raw files are never uploaded to Locus.

Indexes live in `~/.locus` (set `LOCUS_DATA_DIR` to move them). Settings are environment
variables, or a `.env` file in the directory you run `locus` from or one of its parents.
