# Locus

> Hierarchical markdown memory palace for AI agents — structured palace navigation via MCP tools.

- **Type:** MCP server
- **Install:** `agentstack add mcp-edkarlsson-locus`
- **Verified:** Pending review
- **Seller:** [Nano-Nimbus](https://agentstack.voostack.com/s/nano-nimbus)
- **Installs:** 0
- **Latest version:** 0.6.1
- **License:** MIT
- **Upstream author:** [Nano-Nimbus](https://github.com/Nano-Nimbus)
- **Source:** https://github.com/Nano-Nimbus/locus

## Install

```sh
agentstack add mcp-edkarlsson-locus
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Locus

[](https://github.com/Nano-Nimbus/locus/actions/workflows/ci.yml)
[](https://pypi.org/project/locus-mcp/)
[](LICENSE)
[](https://www.python.org/downloads/)

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](https://en.wikipedia.org/wiki/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](https://github.com/Nano-Nimbus/locus/wiki) for full documentation.

---

## Quick start

```sh
# Install
pip install locus-mcp
# or: uvx locus-mcp --palace ~/.locus  (no install needed)

# Create a palace from the example template
cp -r example-palace ~/.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)

```sh
pip install locus-mcp
```

Or run without installing using `uvx`:

```sh
uvx locus-mcp --palace ~/.locus
```

### Claude Code skills

Install all skills at once using the Makefile:

```sh
git clone https://github.com/Nano-Nimbus/locus.git
cd locus
make install-skills
```

Or install individually:

```sh
cp -r skills/claude/locus ~/.claude/skills/locus
cp -r skills/claude/locus-consolidate ~/.claude/skills/locus-consolidate
cp -r skills/claude/locus-audit ~/.claude/skills/locus-audit
cp -r skills/claude/locus-feedback ~/.claude/skills/locus-feedback
cp -r skills/claude/locus-release ~/.claude/skills/locus-release
cp -r skills/claude/locus-security ~/.claude/skills/locus-security
cp -r skills/claude/locus-palace-init ~/.claude/skills/locus-palace-init
```

Available Claude Code skills:

| Skill | Command | Description |
|---|---|---|
| `locus` | `/locus` | Navigate the palace, read rooms, write session logs |
| `locus-consolidate` | `/locus-consolidate` | Merge session logs into canonical files |
| `locus-audit` | `/locus-audit` | Audit palace health |
| `locus-feedback` | `/locus-feedback` | Record explicit feedback on a palace recall |
| `locus-release` | `/locus-release` | Post-release verification workflow |
| `locus-security` | `/locus-security` | Security conventions for signed palaces |
| `locus-palace-init` | `/locus-palace-init` | Bootstrap a palace from existing memory files |

### Codex

```sh
cp -r skills/codex/locus ~/.codex/skills/locus
cp -r skills/codex/locus-consolidate ~/.codex/skills/locus-consolidate
cp -r skills/codex/locus-palace-init ~/.codex/skills/locus-palace-init
```

### Gemini

Reference `skills/gemini/locus/SKILL.md` from your `.gemini/` directory
or a GitHub Actions workflow (see `skills/gemini/`).

```sh
cp -r skills/gemini/locus-palace-init .gemini/
```

### Agent SDK (Python)

```sh
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.

| Tool | Description |
|---|---|
| `memory_list` | Returns `INDEX.md` (no args) or lists a room's files |
| `memory_read` | Reads any file in the palace |
| `memory_write` | Atomically writes a file (guarded — cannot write to `_metrics/`, `sessions/`, `.sig/`, `.security/`) |
| `memory_search` | Full-text search across the palace (ripgrep or Python fallback) |
| `memory_batch` | Reads up to 20 palace files in a single call — use for multi-room loads |

Add `--security` to enable Ed25519 signature verification on reads and automatic signing on writes.
See [Security](#security) below.

### Claude Desktop (`claude_desktop_config.json`)

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

Or using `uvx` (no install required):

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

### Cursor / Zed

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

### Environment variable

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

```sh
export LOCUS_PALACE=~/.locus
locus-mcp
```

See [MCP Server Configuration](https://github.com/Nano-Nimbus/locus/wiki/MCP-Server-Configuration)
for the full client setup guide and `spec/mcp-server.md` for architecture details.

---

## Security

The security system (`--security`) gives every palace file an Ed25519 signature and every agent session a unique cryptographic nonce. Tool outputs are tagged `[TRUSTED]`, `[DATA]`, or `[CRITICAL-DATA]` before the agent sees them. The agent skill (`locus-security`) teaches agents to extract facts from `[DATA]` content but never follow directives within it.

```sh
# One-time setup
cp templates/locus-security.yaml ~/.locus/locus-security.yaml
locus-security init-keys --palace ~/.locus
locus-security sign-all --palace ~/.locus

# Run with security enabled
locus-mcp --palace ~/.locus --security
locus --palace ~/.locus --security --task "..."
```

**Threat model:** direct prompt injection, memory poisoning, indirect injection via external data, nonce exfiltration, multi-turn context drift.

See [`docs/security.md`](docs/security.md) for the full protocol, configuration reference, and design decisions.

---

## Benchmarks

Palace navigation loads **52% fewer context lines** than flat memory for specific queries,
while maintaining full recall. Session-only queries (recent work not yet consolidated)
are accessible only via the palace.

```
Palace: 822 lines / 9 queries found   avg  91 lines/query · 3.2 calls
Flat:  1719 lines / 8 queries found   avg 191 lines/query · 2.0 calls
```

See [`docs/benchmarks.md`](docs/benchmarks.md) for charts and full methodology.

---

## Structure

```
example-palace/   Copy-paste palace template to get started
spec/             Palace convention definitions:
  index-format.md       INDEX.md rules and routing
  room-conventions.md   Room structure and naming
  size-limits.md        Context budget thresholds
  write-modes.md        Session logs vs canonical edits
  mcp-server.md         MCP server architecture and safety model
  metrics-schema.md     Run metrics JSON schema
  audit-algorithm.md    Palace health scoring
  health-report-format.md  Audit report structure
  inferred-feedback.md  Disagreement signal classification
templates/        Copy-paste templates for INDEX.md, rooms, session logs, locus-security.yaml
skills/
  claude/         SKILL.md files for Claude Code + Agent SDK
    locus/              Palace navigation and memory management
    locus-consolidate/  Room consolidation
    locus-security/     Security conventions (trust tags, nonce discipline)
  codex/          Codex-compatible skill files
  gemini/         Gemini CLI + GitHub Actions skill files
docs/
  architecture.md       Mermaid diagrams — palace, MCP, security, agent interfaces
  benchmarks.md         Benchmark results and charts (palace vs flat, security overhead)
  onboarding.md         Step-by-step agent onboarding guide
  security.md           Full security protocol, key management, config reference
  bench/                Per-version benchmark JSON (read by generate-charts.py)
scripts/
  bench-mcp.py          45-case MCP integration benchmark (includes security + batch)
  bench-compare.py      Palace vs flat recall comparison
  generate-charts.py    Regenerate docs/img/ charts (reads docs/bench/ automatically)
locus/
  agent/          Python Agent SDK (CLI + metrics)
  audit/          Palace health auditor (locus-audit CLI)
  feedback/       Inferred feedback classifier
  mcp/            MCP server (locus-mcp CLI) — palace.py, server.py, main.py
  security/       Ed25519 security system — keys, signing, taint, nonce, middleware
  utils.py        Shared utilities (slug_from_path)
```

---

## Roadmap

| Milestone | Status | Focus |
|---|---|---|
| v0.1 - Foundation | ✅ Complete | Spec, conventions, size limits |
| v0.2 - Core Palace | ✅ Complete | Templates, skills, Agent SDK, benchmark |
| v0.3 - Performance Metrics | ✅ Complete | Context tracking, feedback, suggestions |
| v0.4 - Self Evaluation | ✅ Complete | Palace audit, health reports, inferred feedback |
| v0.5 - MCP Server | ✅ Complete | MCP server with memory_list/read/write/search |
| v0.6 - Public release | ✅ Complete | Benchmarks, docs, CI, PyPI |
| v0.7 - Remote MCP Server | ✅ Complete | SSE transport, Bearer auth, Docker image, K8s deploy |
| v0.8 - Auto-Memory Bridge | ✅ Complete | Claude Code auto-memory detection, memory_batch tool |
| v0.9 - Security System | ✅ Complete | Ed25519 signing, taint tracking, nonce watermark, --security flag |

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, test instructions, and PR guidelines.

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Nano-Nimbus](https://github.com/Nano-Nimbus)
- **Source:** [Nano-Nimbus/locus](https://github.com/Nano-Nimbus/locus)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **0.6.1** — security scan: pending review — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-edkarlsson-locus
- Seller: https://agentstack.voostack.com/s/nano-nimbus
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.