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/<hash-of-roots>.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