loci-vault 0.7.0

Loci /ˈloʊsaɪ/ (LOH-sy, or LOH-kee the way a Roman would have said it) is Latin for "places," the plural of locus. The name comes from the method of loci, the classical memory technique where you store what you want to remember by putting it somewhere — a room, a road, a building you already know by heart — and retrieve it by walking back through. The word keeps that spatial sense wherever it turns up: in mathematics a locus is the set of points satisfying a condition, in genetics the fixed position of a gene on a chromosome, and a locus classicus is the one authoritative passage on a subject. The root always points at a specific, defined place.

Loci builds that space for your digital life. It is a personal knowledge system on plain Markdown files with YAML frontmatter, organised as a graph: every note, article, task, book, person, and conversation you save becomes a node with a stable UID, a declared type, and typed relationships to other nodes. The files can also point outward — to a PDF on a drive, a book on a shelf, a message in an inbox — recording where a thing lives instead of making you move it. You and your agents navigate it the way a memory palace is navigated: by association, by position, by path.

It has three faces over one vault. An MCP server with skills that teach Claude to read the ontology before it writes, so it uses your vocabulary rather than inventing one. A local web app for browsing, filtering, reading, and walking the graph. And the files themselves, which open, grep, and commit in any editor with nothing else running. The goal is one place where your thinking accumulates, in a form no platform owns.

Quick start

Requires Python 3.13+ and uv.

1. Install from PyPI

uv tool install loci-vault

The package is loci-vault; the commands it installs are loci and loci-mcp.

2. Wire it into Claude Code

loci skills
claude mcp add --scope user loci loci-mcp

The first installs the skills into ~/.claude/skills/; the second registers the MCP server.

3. Point it at a vault

Restart Claude Code and tell it where the vault should live: "point Loci at ~/vault". Then:

Save this article to my loci vault: https://example.com/post
What does my loci vault know about stoicism?

4. Run it

The package installs two console scripts, and they are separate processes:

loci needs a vault and exits with an error if none is configured yet (step 3 sets one). To use a specific vault for one run: LOCI_VAULT_ROOT=~/vault loci.

Upgrading, running from a checkout, and sync are all in docs/setup.md.

Documentation

Work in progress, and a personal one: the core is used every day, the edges are uneven. Status says which is which.

Licence

PolyForm Noncommercial 1.0.0.

Noncommercial use is free. Personal use, research, teaching, and charities are all permitted purposes, including modifying and redistributing.

Commercial use needs a separate licence from the owner. If you want to use Loci in or for a business, open an issue and ask.

This makes Loci source-available rather than open source: the OSI definition forbids restricting commercial use, so it will not carry an OSI badge and GitHub reports its licence as "Other". The choice is deliberate, and it is the restrictive end on purpose, since a licence can be loosened later but never tightened.

Your vault is yours. The licence covers this software, not the notes you write with it.

Contributing

See CONTRIBUTING.md.

Pull requests are gated on a signed Contributor Licence Agreement. A bot posts the sentence to reply with; you sign once. You keep your copyright, and the grant is what keeps commercial licensing and a future move to AGPL or MIT possible.