loci

loci is a queryable "second brain" tool for scattered notes and documents, and it also provides an MCP server so that AI agents can use the same memory.

Purpose

loci is used to solve the retrieval problem of project documents, notes, and chat logs scattered across a dozen directories. Its core idea is: rather than building another chat application, build a memory layer that every chat application can mount. Claude Desktop, Cursor, Cline, or any MCP host can become its interface. It does not compete with note-taking applications such as Obsidian, but instead works in layers with them as a cross-vault search engine: Obsidian handles recording, and loci handles cross-directory retrieval.

Main capabilities

• Hybrid retrieval: vector retrieval and a built-in BM25 of about 60 lines (with a CJK tokenizer) are fused via Reciprocal Rank Fusion (RRF). Chinese queries can find English documents (and vice versa), and keyword evidence can catch what embeddings miss.
• Paragraph-level citations: each citation points to a specific paragraph (in the form path > section), not just the file level.
• Optional reranking: rerank the fused candidate results via --rerank to improve precision, with support for two providers; the local model is downloaded on first use (about 1.1 GB).
• Multi-format support: PDF (via the [pdf] add-on, PyMuPDF4LLM extracts pages as markdown, tables are presented as pipe rows, with plain pypdf text as a fallback), Word (via the [docx] add-on, indexing .docx paragraphs and table rows), HTML (.html/.htm converted to text that preserves headings, using the standard library html.parser, zero dependencies), org-mode (.org notes converted faithfully, #+TITLE becomes h1, #+FILETAGS becomes searchable tags), chat exports (put ChatGPT or Claude conversations.json into any source directory, and each conversation becomes a searchable document, tagged as chatlog).
• Obsidian-native details: understands frontmatter tags: (can be filtered with search --tag), [[wikilinks]] (can be traversed with links), code blocks are not truncated in the middle, single-line notes are stillsearchable.
• Incremental indexing: the write path is loaders → chunker (heading-aware splitting) → embedder → store (ChromaDB persistence), with deduplication by content hash.

Usage

Requires Python 3.11+ (uses the standard library tomllib). [llm] and [embed] can point to different providers (for example, DeepSeek for chat and OpenAI for embeddings); the only rule is that the [embed] endpoint must provide an OpenAI-style /embeddings API. API keys can also come from the environment variables BRAIN_LLM_API_KEY / BRAIN_EMBED_API_KEY (taking precedence over the config file).

Search and ask support freely combinable filter operators.

The MCP server exposes three tools and supports the full protocol: Resources (resources/list exposes brain://stats as well as a brain://note/… resource for each indexed file, with the raw markdown retrieved via resources/read), Prompts (three ready-made templates: brain-briefing, study-plan, contradiction-check).

Memories are stored as plain markdown in the memories directory (easy to manage with git, no lock-in), tagged as memory, and can be restricted in retrieval with loci search --tag memory. Cross-IDE tip: by default, the store / memories paths are relative to the directory from which loci is started; if each IDE starts from a different project folder, you can point to the same absolute location in config.toml (such as store.path = "~/.loci/store", memories.path = "~/.loci/memories"), so that all IDEs share the same memory store.

loci-dsh is a visualization plugin for DeepSeek Harness: it performs search, asking questions, quickly capturing memories, and viewing index statistics in the dsh Web UI sidebar, communicating with loci serve-http via a local REST interface.

Fully offline solution: the index is stored locally, and embedding/chat callsIt can also be localized. Any OpenAI-compatible server will do, and Ollama has been verified end to end. With this configuration, ingest / search / ask make zero cloud calls.

Use cases

• Search project documents, notes, and chat logs across multiple directories.
• Let MCP hosts such as Claude Desktop, Cursor, and Cline share the same memory store, so memories written in one tool can be recalled from another.
• Search over mixed Chinese and English corpora.
• Q&A that requires paragraph-level verifiable citations.
• Scenarios that require fully local/offline operation (with Ollama).

Limitations and design decisions

• The core is about 300 lines and does not use LangChain, making it easy to read and modify.
• MCP first, with no web app to maintain.
• Hybrid search is enabled by default.
• Citations always include path and paragraph for quick verification.
• The defensive loader skips content that cannot be parsed and will not hang.
• Single-line notes are not filtered out by minimum chunking and can still be indexed.
• Secrets are not written into code, only placed in config.toml (already gitignored) or environment variables.

To contribute, see CONTRIBUTING.md (rules: no frameworks, keep tests offline, citations are non-negotiable). For the roadmap, see docs/roadmap.md, which includes reranking, GraphRAG experiments, and more loaders.

Regarding specific pricing, fees, and installation command details, complete information is not currently available in the materials.