Metadata-Version: 2.5
Name: locusfiles
Version: 0.1.3
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

We recommend [uv](https://docs.astral.sh/uv/): you do not need Python installed first, because it
installs its own. [pipx](https://pipx.pypa.io) works too if you already have Python 3.11 or newer.
Either one puts `locus` in its own environment. `locusfiles` has been on PyPI since 0.1.0
(2026-09-29):

```bash
# Recommended: uv (install it first; skip if `uv --version` already works)
curl -LsSf https://astral.sh/uv/install.sh | sh   # then open a new terminal, so `uv` is found
# On-device embeddings, no account (downloads PyTorch, about 1-2 GB):
uv tool install --python 3.12 "locusfiles[local]"
# or a Locus plan (managed embeddings, remote connection), no PyTorch:
uv tool install --python 3.12 "locusfiles[relay]"
uv tool update-shell               # adds ~/.local/bin to PATH; open a new terminal afterwards

# Alternative: pipx (needs Python 3.11+)
pipx install "locusfiles[local]"   # or "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 and your search queries pass through Locus's relay to Voyage AI to be embedded.
  We don't store them; 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.

## Licence

The `locusfiles` package is licensed under the **Functional Source License, Version 1.1, ALv2
Future License** (`FSL-1.1-ALv2`). The full text ships inside the package as its `LICENSE` file,
and that text is the binding version. In short, the engine is **source-available**: you may use,
copy, modify and redistribute it for any purpose except a Competing Use (making it available to
others in a commercial product or service that substitutes for it or offers substantially similar
functionality). Two years after a version is made available, that version is also available under
the Apache License, Version 2.0. The hosted services (the relay, the website and billing) are not
part of the package and are not licensed by it.
