Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ivenkoolab--loci/badge.svg)](/listings/ivenkoolab--loci)

HTML

<a href="/listings/ivenkoolab--loci"><img src="/api/listings/ivenkoolab--loci/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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

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

  1. <p align="center">
  2. <img src="docs/assets/loci-banner.svg" alt="loci — shared memory for your AI tools" width="100%">
  3. </p>
  4. <p align="center">
  5. <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>
  6. </p>
  7. <p align="center">
  8. <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&amp;label=CI" alt="CI"></a>
  9. <a href="https://pypi.org/project/loci-rag/"><img src="https://img.shields.io/pypi/v/loci-rag?color=367d65" alt="PyPI"></a>
  10. <img src="https://img.shields.io/badge/MCP-server-367d65" alt="MCP server">
  11. <img src="https://img.shields.io/badge/Python-3.11%2B-367d65" alt="Python 3.11+">
  12. <a href="native/"><img src="https://img.shields.io/badge/Rust-native%20build-367d65" alt="Rust native build"></a>
  13. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-367d65" alt="MIT license"></a>
  14. </p>
  15. <!-- mcp-name: io.github.IvenKooLab/loci -->
  16. **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.**
  17. 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.
  18. **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.
  19. [Quick start](#quick-start) · [MCP setup](#connect-your-ai-tools) · [Web console](#web-console) · [Usage guide](docs/guide.en.md) · [中文说明](README.zh-CN.md)
  20. ![loci console — synthetic-data demo](docs/assets/console-demo-light.png)
  21. *Actual console UI with fictional demo data. No personal knowledge base, account or API key is connected; counts are illustrative.*
  22. <details>
  23. <summary>Dark theme preview</summary>
  24. ![loci console — dark theme, fictional demo data](docs/assets/console-demo-dark.png)
  25. </details>
  26. ## What you can do
  27. | Need | How loci helps |
  28. |---|---|
  29. | Find a decision buried in your notes | Hybrid search across directories, with tag, path and date filters |
  30. | Search for an exact identifier | Literal matching for `user_id`, `api/v2`, `SHT45` — a symbol does not have to win a semantic ranking |
  31. | Know whether a decision still applies | `loci history` walks the supersession chain: what replaced it, and when |
  32. | Ask a question and check the evidence | Answers cite source sections; optional claim-by-claim verification |
  33. | Carry context between AI tools | MCP tools share one instance; durable memories are Markdown files |
  34. | See what each coding agent remembers | Harness discovery, file browsing, per-tool stats and digest notes |
  35. | Manage the knowledge base visually | Built-in Web console for search, Q&A, memories, indexing and audit |
  36. | Resume a task exactly where it left off | Structured state by exact key (`brain_state_save` / `brain_state_get`) — no ranking in the way |
  37. | Prune memory with evidence instead of vibes | Memory health: citations, corrections and age per note (`loci memory-health`) |
  38. 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.
  39. ## What belongs where
  40. Three kinds of "memory" fail differently, and mixing them is the classic
  41. misuse:
  42. | Kind | Lives in | Retrieved by | Right for | Wrong for |
  43. |---|---|---|---|---|
  44. | Free-text knowledge | memory notes (`brain_remember`) | hybrid retrieval | "what do we know about X" | exact resume of a task |
  45. | 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 |
  46. | Live dialogue slots | the host agent's session | the host's own context | this turn's variables | anything you expect to survive the session |
  47. Rules of thumb:
  48. - If retrieval returning a *similar but wrong* record would be a bug, it is
  49. state — key it and fetch exactly (`brain_state_get type=task key=8f3c`).
  50. - Real-time slot values change every turn; do not put them in the vector
  51. store. Persist the ones worth keeping across sessions as state records.
  52. - Prose that a future question might phrase differently is knowledge —
  53. `brain_remember` it, and let ranking do the work.
  54. State records are plain JSON, hand-editable, and deliberately **not indexed**
  55. into vectors: that is the boundary, not an omission.
  56. ## Decision history
  57. A decision note edited in place loses the fact that something replaced it. Two
  58. frontmatter keys keep that visible, and `loci history` walks the chain:
  59. ```markdown
  60. ---
  61. supersedes: use-staging # the note this one replaces
  62. effective: 2026-03-01 # when this one took effect
  63. ---
  64. ```
  65. ```bash
  66. loci history use-staging
  67. # decision history, oldest first:
  68. # 1. use-staging (effective 2026-01-05) → superseded by
  69. # 2. staging-exception (effective 2026-03-01)
  70. # current decision: staging-exception (effective 2026-03-01)
  71. ```
  72. `loci ask` marks excerpts from superseded notes in the context it sends to the
  73. model, so an answer does not quote last quarter's decision as current policy —
  74. and it tells you how many excerpts were affected.
  75. ## Memory health
  76. Every search or answer that uses a memory note is ledgered (`citations.jsonl`
  77. in the instance directory). `loci memory-health` joins that with feedback
  78. (`loci feedback bad` — which also sinks the rated chunks in later retrieval)
  79. and age, and flags notes worth looking at:
  80. ```
  81. $ loci memory-health
  82. 12 memory note(s), most-cited first
  83. cited corr age(d) last-cited flags file
  84. 17 0 41.2 0.3 - 20260920-103000-deploy-policy.md
  85. 0 2 63.8 - corrected 20260830-090000-old-strategy.md
  86. 0 0 51.4 - never-cited 20260901-120000-random-idea.md
  87. ```
  88. `corrected` = rated bad after being used; `never-cited` = old and unused.
  89. Both are candidates for `brain_forget` — with evidence, not vibes. loci sees
  90. tool calls, not your conversation, so corrections reach it only through
  91. explicit feedback; the report never silently rewrites retrieval.
  92. ## Quick start
  93. ### Try it first, with nothing configured
  94. ```bash
  95. pip install loci-rag
  96. loci demo
  97. ```
  98. `loci demo` copies six fictional notes into `./loci-demo-notes`, chunks them and
  99. answers three example questions — cited down to `file > section` — with no
  100. `config.toml`, no API key and no network. It is keyword-only (BM25, the same
  101. ranking hybrid search fuses with vector hits), which is exactly the point:
  102. something runs before you commit a key. Add `[embed]` later and the same index
  103. goes hybrid.
  104. ![loci demo — real output, bundled fictional notes](docs/assets/demo-offline.png)
  105. *Actual `loci demo` output on the bundled sample notes; paths shortened, timings vary.*
  106. ### Index your own notes
  107. Requires **Python 3.11+**. Start from source so the example configuration is available:
  108. ```bash
  109. git clone https://github.com/IvenKooLab/loci.git
  110. cd loci
  111. python -m pip install -e .
  112. cp config.example.toml config.toml
  113. ```
  114. 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.
  115. ```bash
  116. loci ingest
  117. loci search "deployment decisions"
  118. loci ask "What did we decide about deployment, and why?"
  119. ```
  120. 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]'`.
  121. > 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`.
  122. Using Obsidian? See the [vault setup, privacy and compatibility guide](docs/obsidian.en.md).
  123. ## Web console
  124. ```bash
  125. loci serve-http
  126. ```
  127. 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.
  128. 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).
  129. 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.
  130. ## Connect your AI tools
  131. Point each MCP client at the **same `LOCI_HOME`** so they share the same config, index and memory files:
  132. ```json
  133. {
  134. "mcpServers": {
  135. "loci": {
  136. "command": "loci-mcp",
  137. "env": { "LOCI_HOME": "/absolute/path/to/your/loci-instance" }
  138. }
  139. }
  140. }
  141. ```
  142. Use an absolute executable path if your client cannot find `loci-mcp`. The instance directory must contain your `config.toml`.
  143. | MCP tools | Purpose |
  144. |---|---|
  145. | `brain_search` · `brain_ask` | Retrieve excerpts or get cited answers |
  146. | `brain_remember` · `brain_forget` | Store or retract durable memories |
  147. | `brain_state_save` · `brain_state_get` · `brain_state_list` · `brain_state_delete` | Exact-key structured state (task snapshots, entity records) |
  148. | `brain_memory_health` | Which memory notes are cited, corrected, or dead weight |
  149. | `brain_links` · `brain_graph` | Explore note links and extracted relations |
  150. | `brain_wiki` · `brain_harness` | Consolidate knowledge and inspect agent memories |
  151. | `brain_governance` · `brain_quality` | Lifecycle scan (superseded / duplicate / stale notes) and retrieval-quality drift |
  152. | `brain_stats` · `brain_ingest` | Inspect and refresh the index |
  153. 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.
  154. ![loci-mcp — real JSON-RPC session](docs/assets/mcp-tools.png)
  155. *Actual `loci-mcp` output: `initialize`, `tools/list` and `prompts/list` on the real binary.*
  156. ### Native build (Rust)
  157. The same retrieval pipeline and MCP surface, with no Python runtime to install —
  158. one binary, and the index is a single SQLite file instead of a database
  159. directory:
  160. ```bash
  161. cargo build --release -p loci-cli # in native/
  162. ./target/release/loci-mcp --config ~/.loci/config.toml
  163. ./target/release/loci gui # the same console, served natively
  164. ```
  165. Status: retrieval, a subset of MCP tools, harness discovery, migration and the
  166. console are ported. Harness file browsing and digest generation remain
  167. Python-only. See
  168. [`native/`](native/) for what is ported and the fidelity tests that pin it
  169. (chunking, the frozen `default` tokenizer, the CJK bigram decoy case, RRF, and
  170. incremental ingest).
  171. **The two builds keep separate store formats** (SQLite vs ChromaDB directory),
  172. but they exchange data: export from Python with `loci export`, import in the
  173. native build with `loci import`, which refuses to mix embedding spaces unless
  174. you pass `--force`.
  175. ## A small daily workflow
  176. ```bash
  177. loci watch # keep changed documents indexed
  178. loci remember "Use staging for demos" --title "Demo environment"
  179. loci search "demo environment" --tag memory
  180. loci ask "How should I prepare a demo?" --verify
  181. loci harness # inspect detected agent memories
  182. ```
  183. 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.
  184. <details>
  185. <summary><strong>See a retrieval session</strong></summary>
  186. ![loci terminal demo](docs/assets/loci-demo.gif)
  187. 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.
  188. </details>
  189. ## Documentation
  190. | Guide | Covers |
  191. |---|---|
  192. | [Usage guide](docs/guide.en.md) / [中文指南](docs/guide.zh-CN.md) | Commands, filters, harness setup, access control and local models |
  193. | [Configuration example](config.example.toml) | Provider settings, source directories and runtime options |
  194. | [Architecture](docs/ARCHITECTURE.md) | Modules and the retrieval pipeline |
  195. | [Changelog](CHANGELOG.md) · [Roadmap](docs/roadmap.md) | Released changes and planned work |
  196. | [Contributing](CONTRIBUTING.md) | Development conventions and offline testing |
  197. 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.
  198. ```bash
  199. python -m pip install -e '.[dev,pdf]'
  200. pytest # offline tests; no API keys required
  201. ```
  202. 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 in

Free to use. If it’s helped, pass it on.