loci

English · 简体中文 · 繁體中文 · 日本語 · 한국어

Turn scattered notes, project docs and agent memories into a knowledge base you can search and ask questions about — from your terminal, browser or MCP client.

loci combines vector search with BM25 and returns answers with file > section citations. Your files and index stay on your machine. Embedding and chat requests go to the providers you configure; local endpoints can keep the entire workflow offline.

Quick start · Web console · MCP setup · Usage guide · 中文说明

Actual console UI with fictional demo data. No personal knowledge base, account or API key is connected; counts are illustrative.

Dark theme preview

What you can do

Markdown, text, HTML, org-mode and chat exports work out of the box. Optional extras add PDF, Word and OCR support. Keep using your existing note editor or Obsidian vault.

Quick start

Try it first, with nothing configured

pip install loci-rag
loci demo

loci demo copies six fictional notes into ./loci-demo-notes, chunks them and answers three example questions — cited down to file > section — with no config.toml, no API key and no network. It is keyword-only (BM25, the same ranking hybrid search fuses with vector hits), which is exactly the point: something runs before you commit a key. Add [embed] later and the same index goes hybrid.

Actual loci demo output on the bundled sample notes; paths shortened, timings vary.

Index your own notes

Requires Python 3.11+. Start from source so the example configuration is available:

git clone https://github.com/IvenKooLab/loci.git
cd loci
python -m pip install -e .
cp config.example.toml config.toml

Edit config.toml: fill in [llm] and [embed], and change [[sources]].path to your notes directory. The embedding endpoint must support /embeddings; chat and embeddings may use different providers.

loci ingest
loci search "deployment decisions"
loci ask "What did we decide about deployment, and why?"

Already have a configuration? Install the package with python -m pip install loci-rag and set LOCI_HOME to your instance directory. For optional document support, use python -m pip install 'loci-rag[pdf,docx]'.

API keys can be supplied through BRAIN_LLM_API_KEY and BRAIN_EMBED_API_KEY. After changing the embedding model, rebuild with loci ingest --force.

Web console

loci serve-http

Open 127.0.0.1:8765/ui to browse harness memories, search, ask questions, edit shared notes and inspect indexing activity. Clicking a search result opens an evidence pane with the passage it was cut from — the file > section citation, checkable without leaving the console. The console includes Chinese/English and light/dark switches; no frontend build is required.

By default, anonymous loopback clients have admin access. Behind a reverse proxy or SSH tunnel, set [http] local_admin = false and configure role-based tokens. See access control.

For DeepSeek Harness, loci-dsh brings search, Q&A and memory capture into the Harness workbench through the same HTTP backend.

Connect your AI tools

Point each MCP client at the same LOCI_HOME so they share the same config, index and memory files:

{
  "mcpServers": {
    "loci": {
      "command": "loci-mcp",
      "env": { "LOCI_HOME": "/absolute/path/to/your/loci-instance" }
    }
  }
}

Use an absolute executable path if your client cannot find loci-mcp. The instance directory must contain your config.toml.

The server also exposes note resources and briefing, study-plan and contradiction-check prompts. See the MCP guide for details.

A small daily workflow

loci watch                            # keep changed documents indexed
loci remember "Use staging for demos" --title "Demo environment"
loci search "demo environment" --tag memory
loci ask "How should I prepare a demo?" --verify
loci harness                          # inspect detected agent memories

Indexing is incremental. Notes stay readable as Markdown. For multiple machines, sync source files and memory notes, then rebuild each local index; keep credentials out of the repository.

See a retrieval session

The usage guide includes the original bilingual retrieval example and a small evaluation you can rerun against your own corpus.

Documentation

loci uses the OpenAI-compatible SDK and ChromaDB, with no LangChain or LlamaIndex dependency. BM25, loaders and the MCP transport are implemented in the project.

python -m pip install -e '.[dev,pdf]'
pytest  # offline tests; no API keys required

Find loci on Glama, ModelScope and awesome-mcp-servers. Source: GitHub · Gitee. Licensed under MIT.