loci
A queryable second brain over your scattered notes and docs - hybrid retrieval (vector + BM25), section-level citations, and an MCP server so AI agents can use it. ~300 lines, no LangChain.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/IvenKooLab/loci with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/IvenKooLab/loci'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/ivenkoolab--loci)HTML
<a href="/listings/ivenkoolab--loci"><img src="/api/listings/ivenkoolab--loci/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requires Python 3.11+ (uses the stdlib `tomllib`).
# option A: install from PyPI (adds `loci` and `loci-mcp` commands) pip install "loci-rag[pdf,docx]" # optional extras: PDF w/ tables, Word documents # option B: zero-install quickstart pip install -r requirements.txt # 1. Configure: copy the example and fill in your values cp config.example.toml config.toml # 2. Ingest (incremental — deduplicated by content hash, safe to re-run) loci ingest # or: python main.py ingest # 3. Ask loci ask "what did I write about X?"
The workflow
%%{init: {'theme':'base','themeVariables':{'background':'#000000','primaryColor':'#000000','primaryTextColor':'#00FF41','primaryBorderColor':'#00FF41','lineColor':'#00FF41','secondaryColor':'#001a00','tertiaryColor':'#000000','clusterBkg':'#000000','clusterBorder':'#00FF41','edgeLabelBackground':'#000000','fontSize':'14px','fontFamily':'trebuchet ms, verdana, arial, sans-serif'},'themeCSS':'.nodeLabel { color: #00FF41 !important; } .edgeLabel { background: #000 !important; color: #00FF41 !important; } .cluster-label { color: #00FF41 !important; }'}}%%
flowchart TD
A["pip install loci-rag"] --> B["cp config.example.toml config.toml<br>fill API keys + source dirs"]
B --> C["loci ingest — hybrid index built"]
C --> D["loci watch — index stays fresh (optional)"]
C --> E{"What do you need?"}
E -->|"a synthesized answer"| F["loci ask --verify<br>claim-by-claim audit"]
E -->|"raw excerpts to quote"| G["loci search --tag memory"]
E -->|"back-and-forth"| H["loci chat"]
E -->|"scattered notes on a topic"| I["loci wiki topic<br>consolidate into a wiki page"]
F --> J["loci remember —<br>keep what you learned"]
I --> JWhat was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 276 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <img src="docs/assets/loci-banner.svg" alt="loci — shared memory for your AI tools" width="100%">
- </p>
- <p align="center">
- <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.zh-TW.md">繁體中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a>
- </p>
- <p align="center">
- <a href="https://github.com/IvenKooLab/loci/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/IvenKooLab/loci/ci.yml?branch=main&label=CI" alt="CI"></a>
- <a href="https://pypi.org/project/loci-rag/"><img src="https://img.shields.io/pypi/v/loci-rag?color=367d65" alt="PyPI"></a>
- <img src="https://img.shields.io/badge/MCP-server-367d65" alt="MCP server">
- <img src="https://img.shields.io/badge/Python-3.11%2B-367d65" alt="Python 3.11+">
- <a href="native/"><img src="https://img.shields.io/badge/Rust-native%20build-367d65" alt="Rust native build"></a>
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-367d65" alt="MIT license"></a>
- </p>
- <!-- mcp-name: io.github.IvenKooLab/loci -->
- **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](#quick-start) · [MCP setup](#connect-your-ai-tools) · [Web console](#web-console) · [Usage guide](docs/guide.en.md) · [中文说明](README.zh-CN.md)
- 
- *Actual console UI with fictional demo data. No personal knowledge base, account or API key is connected; counts are illustrative.*
- <details>
- <summary>Dark theme preview</summary>
- 
- </details>
- ## What you can do
- | Need | How loci helps |
- |---|---|
- | Find a decision buried in your notes | Hybrid search across directories, with tag, path and date filters |
- | Search for an exact identifier | Literal matching for `user_id`, `api/v2`, `SHT45` — a symbol does not have to win a semantic ranking |
- | Know whether a decision still applies | `loci history` walks the supersession chain: what replaced it, and when |
- | Ask a question and check the evidence | Answers cite source sections; optional claim-by-claim verification |
- | Carry context between AI tools | MCP tools share one instance; durable memories are Markdown files |
- | See what each coding agent remembers | Harness discovery, file browsing, per-tool stats and digest notes |
- | Manage the knowledge base visually | Built-in Web console for search, Q&A, memories, indexing and audit |
- | Resume a task exactly where it left off | Structured state by exact key (`brain_state_save` / `brain_state_get`) — no ranking in the way |
- | Prune memory with evidence instead of vibes | Memory health: citations, corrections and age per note (`loci memory-health`) |
- 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.
- ## What belongs where
- Three kinds of "memory" fail differently, and mixing them is the classic
- misuse:
- | Kind | Lives in | Retrieved by | Right for | Wrong for |
- |---|---|---|---|---|
- | Free-text knowledge | memory notes (`brain_remember`) | hybrid retrieval | "what do we know about X" | exact resume of a task |
- | Structured state | `state/<type>/<key>.json` (`brain_state_save`) | exact key, no ranking | task snapshots, entity records, slot state worth persisting | prose you might want to fuzzy-find |
- | Live dialogue slots | the host agent's session | the host's own context | this turn's variables | anything you expect to survive the session |
- Rules of thumb:
- - If retrieval returning a *similar but wrong* record would be a bug, it is
- state — key it and fetch exactly (`brain_state_get type=task key=8f3c`).
- - Real-time slot values change every turn; do not put them in the vector
- store. Persist the ones worth keeping across sessions as state records.
- - Prose that a future question might phrase differently is knowledge —
- `brain_remember` it, and let ranking do the work.
- State records are plain JSON, hand-editable, and deliberately **not indexed**
- into vectors: that is the boundary, not an omission.
- ## Decision history
- A decision note edited in place loses the fact that something replaced it. Two
- frontmatter keys keep that visible, and `loci history` walks the chain:
- ```markdown
- ---
- supersedes: use-staging # the note this one replaces
- effective: 2026-03-01 # when this one took effect
- ---
- ```
- ```bash
- loci history use-staging
- # decision history, oldest first:
- # 1. use-staging (effective 2026-01-05) → superseded by
- # 2. staging-exception (effective 2026-03-01)
- # current decision: staging-exception (effective 2026-03-01)
- ```
- `loci ask` marks excerpts from superseded notes in the context it sends to the
- model, so an answer does not quote last quarter's decision as current policy —
- and it tells you how many excerpts were affected.
- ## Memory health
- Every search or answer that uses a memory note is ledgered (`citations.jsonl`
- in the instance directory). `loci memory-health` joins that with feedback
- (`loci feedback bad` — which also sinks the rated chunks in later retrieval)
- and age, and flags notes worth looking at:
- ```
- $ loci memory-health
- 12 memory note(s), most-cited first
- cited corr age(d) last-cited flags file
- 17 0 41.2 0.3 - 20260920-103000-deploy-policy.md
- 0 2 63.8 - corrected 20260830-090000-old-strategy.md
- 0 0 51.4 - never-cited 20260901-120000-random-idea.md
- ```
- `corrected` = rated bad after being used; `never-cited` = old and unused.
- Both are candidates for `brain_forget` — with evidence, not vibes. loci sees
- tool calls, not your conversation, so corrections reach it only through
- explicit feedback; the report never silently rewrites retrieval.
- ## Quick start
- ### Try it first, with nothing configured
- ```bash
- 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:
- ```bash
- 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.
- ```bash
- 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`.
- Using Obsidian? See the [vault setup, privacy and compatibility guide](docs/obsidian.en.md).
- ## Web console
- ```bash
- loci serve-http
- ```
- Open **[127.0.0.1:8765/ui](http://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](docs/guide.en.md#web-console).
- For DeepSeek Harness, [loci-dsh](https://github.com/IvenKooLab/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:
- ```json
- {
- "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`.
- | MCP tools | Purpose |
- |---|---|
- | `brain_search` · `brain_ask` | Retrieve excerpts or get cited answers |
- | `brain_remember` · `brain_forget` | Store or retract durable memories |
- | `brain_state_save` · `brain_state_get` · `brain_state_list` · `brain_state_delete` | Exact-key structured state (task snapshots, entity records) |
- | `brain_memory_health` | Which memory notes are cited, corrected, or dead weight |
- | `brain_links` · `brain_graph` | Explore note links and extracted relations |
- | `brain_wiki` · `brain_harness` | Consolidate knowledge and inspect agent memories |
- | `brain_governance` · `brain_quality` | Lifecycle scan (superseded / duplicate / stale notes) and retrieval-quality drift |
- | `brain_stats` · `brain_ingest` | Inspect and refresh the index |
- The server also exposes note resources and briefing, study-plan and contradiction-check prompts. See the [MCP guide](docs/guide.en.md#mount-it-in-any-mcp-host) for details.
- 
- *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:
- ```bash
- 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/`](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
- ```bash
- 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.
- <details>
- <summary><strong>See a retrieval session</strong></summary>
- 
- The [usage guide](docs/guide.en.md#demo) includes the original bilingual retrieval example and a small evaluation you can rerun against your own corpus.
- </details>
- ## Documentation
- | Guide | Covers |
- |---|---|
- | [Usage guide](docs/guide.en.md) / [中文指南](docs/guide.zh-CN.md) | Commands, filters, harness setup, access control and local models |
- | [Configuration example](config.example.toml) | Provider settings, source directories and runtime options |
- | [Architecture](docs/ARCHITECTURE.md) | Modules and the retrieval pipeline |
- | [Changelog](CHANGELOG.md) · [Roadmap](docs/roadmap.md) | Released changes and planned work |
- | [Contributing](CONTRIBUTING.md) | Development conventions and offline testing |
- 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.
- ```bash
- python -m pip install -e '.[dev,pdf]'
- pytest # offline tests; no API keys required
- ```
- Find loci on [Glama](https://glama.ai/mcp/servers/IvenKooLab/loci), [ModelScope](https://modelscope.cn/mcp/servers/IvenKooLab/loci) and [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers). Source: [GitHub](https://github.com/IvenKooLab/loci). Licensed under [MIT](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.