loci

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.

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.

Related MCP server: loci-mcp

Quick start

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. 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.

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.