Locus

Locus

Hierarchical markdown-based memory system for autonomous AI agents. Each directory is a room (locus) in the palace, containing specific knowledge navigated on demand. Named for the atomic unit of the Method of Loci.

Core idea: Keep context windows small. Load only the room you need, not the whole palace.

---

How it works

palace/

INDEX.md ← always read first (~50 lines max) global/ toolchain/ toolchain.md ← canonical facts about tools projects/ my-project/ my-project.md ← room overview + key files technical-gotchas.md ← specialty: issues & resolutions sessions/ 2026-03-02.md ← append-only session log

An agent reads INDEX.md, navigates to the relevant room, and reads only that room. Session logs accumulate until consolidation merges them into canonical files.

See the wiki for full documentation.

---

Quick start

# Install

pip install locus-mcp

or: uvx locus-mcp --palace ~/.locus (no install needed)

Create a palace from the packaged example

locus init ~/.locus

Edit ~/.locus/INDEX.md to describe your palace

Run the MCP server

locus-mcp --palace ~/.locus

or: LOCUS_PALACE=~/.locus locus-mcp

---

Installation

MCP server (recommended for MCP-capable clients)

pip install locus-mcp

Or run without installing using uvx:

uvx locus-mcp --palace ~/.locus

Agent skills

The skill files are the one part of Locus written for a specific runtime. The palace convention, the MCP server, and the recall / lint / index CLIs are runtime-neutral and work from anything that can read a file or speak MCP. The skills in skills/claude/ are written and maintained for Claude Code, and that is the only set shipped here. They are plain markdown with YAML frontmatter, so another runtime is welcome to adapt them. Per-runtime copies used to live in skills/codex/ and skills/gemini/; they were removed because keeping three variants honest cost more than it returned.

Install them from a clone:

git clone https://github.com/Nano-Nimbus/locus.git

cd locus make install-skills # copies skills/claude/* to ~/.claude/skills/ make install-skills-dry # print what would be copied, write nothing

CLAUDE_SKILLS_DIR overrides the destination.

Agent SDK (Python)

pip install locus-mcp

locus --palace ~/.locus --task "What toolchain conventions are set?"

---

MCP Server

The locus-mcp command exposes five tools over the Model Context Protocol.

Use stdio for all local integrations (Claude Desktop, Claude Code, Codex, Gemini — default, no extra flags needed). SSE transport is available for network deployments (--transport sse) and requires FASTMCP_HOST=0.0.0.0 to be set explicitly — the server binds to loopback by default.

Add --security to enable Ed25519 signature verification on reads and automatic signing on writes. See Security below.

Claude Desktop (claude_desktop_config.json)

{

"mcpServers": { "locus": { "command": "locus-mcp", "args": ["--palace", "/path/to/palace"] } } }

Or using uvx (no install required):

{

"mcpServers": { "locus": { "command": "uvx", "args": ["locus-mcp", "--palace", "/path/to/palace"] } } }

Cursor / Zed

{

"mcp": { "servers": { "locus": { "command": "locus-mcp", "args": ["--palace", "/path/to/palace"] } } } }

Environment variable

All clients support LOCUS_PALACE as an alternative to --palace:

export LOCUS_PALACE=~/.locus

locus-mcp

See MCP Server Configuration for the full client setup guide and spec/mcp-server.md for architecture details.

---

Recall

locus recall answers "what do I already know about this?" in one call, fast enough to run on every prompt from a hook. It keeps a SQLite FTS5 index (standard library only, no PyYAML) over any number of markdown roots: a palace, an OKF bundle, a Claude Code memory directory, or all of them at once.

locus recall --root ~/memory --root ./docs "why does the flux kustomization stall"

Recalled memory:

1. Flux healthcheck stall (human-reviewed, 2026-08-22) /home/me/memory/project_flux-healthcheck-stall.md Flux Kustomization with wait:true stalls on health checks for a bad revision ...
2. [STALE] Old Flux bootstrap procedure (unverified, 2025-11-02) /home/me/docs/runbooks/flux-bootstrap.md Bootstrap Flux with a personal access token ...

Frontmatter drives the result: title (or name, or the first heading), description, tags, type (or metadata.type), modified (else generated.at, else file mtime), status, stale_after, and verified. Ranking is bm25 with title and description weighted above the body; exact ties go to human-reviewed files, then to the newest modified. A hit is flagged STALE when its stale_after has passed or its status is deprecated. Trust tiers follow OKF: unverified, machine-confirmed (only non-human verified entries), human-reviewed (any verified entry whose by starts with human:).

Roots can live in a .locus.toml in the project or any parent directory:

[recall]

roots = ["docs", "~/memory/shared"]

The index is stored at ${XDG_CACHE_HOME:-~/.cache}/locus/ .sqlite, never inside a root, and is refreshed incrementally (mtime, then content hash) on every call. With no hits the text output is empty and the exit status is still 0, so a prompt hook can call it unconditionally:

#!/bin/sh

Claude Code UserPromptSubmit hook: whatever this prints is injected as context.

prompt=$(jq -r .prompt) exec locus recall -k 3 --budget 4096 "$prompt"

The MCP server's memory_search uses the same index, so MCP results are ranked the same way. Full rules in spec/recall.md.

---

Lint and index

locus lint checks markdown roots for Open Knowledge Format v0.2 conformance and the Locus palace conventions. locus index generates the index files those conventions define. Both read the same frontmatter recall indexes, and neither imports the Agent SDK, so a CI job that only checks conformance does not install it.

locus lint  --root docs --check          # CI gate: exit 1 on any error

locus lint --root docs --fix # add inferable fields, rewrite nothing locus index --root docs --check # exit 1 when a generated index drifted

docs/runbooks/valve-chatter.md: error [okf.type-missing] frontmatter has no non-empty type (fix: add type: Runbook) docs/log.md: error [okf.log-order] entries run oldest first: 2026-05-09 follows 2026-05-01 docs/reference/platform.md: warning [locus.size-limit] 214 lines exceeds the 200-line soft limit for a specialty file 2 error(s), 1 warning(s), 1 fixable

lint

Rules split in two. okf.* checks what the specification requires: a parseable frontmatter block with a non-empty type on every non-reserved document, an index.md with no frontmatter beyond a bundle-root okf_version, a log.md that is date-headed and newest first, and ISO 8601 timestamps. Unknown keys and unknown type values are never reported: the spec requires consumers to tolerate both. locus.* checks the palace conventions: the size limits from spec/size-limits.md and the room main-file rule from spec/room-conventions.md.

Errors fail --check; warnings are advisory. A palace legitimately carries no frontmatter at all, so on a palace root the missing type rules are warnings rather than a CI failure on a layout the palace spec itself describes.

--fix adds three fields and only three: type from --type-map or [lint.types], generated.at from the file's first git commit, and status: deprecated for archive paths. It never rewrites or deletes a key, it never invents a generated block (nothing in a file says who produced it), and running it twice produces identical bytes.

index

What gets generated depends on the root: an OKF bundle gets an index.md per directory in section 8 form (* [Title](path) - description, with okf_version: "0.2" frontmatter at the bundle root only), a palace gets the 50-line routing table INDEX.md, and a Claude Code memory directory gets a MEMORY.md of one - [Title](file.md) - description line per topic file. Output is deterministic, so --check is a byte comparison, and only index files are ever written.

Configure both from one .locus.toml:

[lint]

roots = ["docs"] archive_globs = ["archive/*"]

[lint.types] "." = "Reference" runbooks = "Runbook"

Full rules in [`spec/lint-and-index