loci

[loci — shared memory for your AI tools]

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

[CI] [PyPI] [MCP server] [Python 3.11+] [Rust native build] [MIT license]

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

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.

MCP is the point. Mount loci-mcp in Claude Desktop, Cursor, Cline or any other MCP host and your assistant gets the whole knowledge base as tools. The console and a desktop shell are alternate front-ends to the same index — you never need them.

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

[loci console — synthetic-data demo]

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.

Quick start

Try it first, with nothing configured

pip install loci-ragloci 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.

[loci demo — real output, bundled fictional notes]

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.gitcd locipython -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 ingestloci 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.

Using Obsidian? See the vault setup, privacy and compatibility guide.

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.

[loci-mcp — real JSON-RPC session]

Actual loci-mcp output: initialize, tools/list and prompts/list on the real binary.

Native build (Rust)

The same retrieval pipeline and MCP surface, with no Python runtime to install — one binary, and the index is a single SQLite file instead of a database directory:

cargo build --release -p loci-cli     # in native/./target/release/loci-mcp --config ~/.loci/config.toml./target/release/loci gui             # the same console, served natively

Status: retrieval, a subset of MCP tools, harness discovery, migration and the console are ported. Harness file browsing and digest generation remain Python-only. See native/ for what is ported and the fidelity tests that pin it (chunking, the frozen default tokenizer, the CJK bigram decoy case, RRF, and incremental ingest).

The two builds keep separate store formats (SQLite vs ChromaDB directory), but they exchange data: export from Python with loci export, import in the native build with loci import, which refuses to mix embedding spaces unless you pass --force.

A small daily workflow

loci watch                            # keep changed documents indexedloci remember "Use staging for demos" --title "Demo environment"loci search "demo environment" --tag memoryloci ask "How should I prepare a demo?" --verifyloci 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.

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.