Locus
<!-- mcp-name: io.github.Nano-Nimbus/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 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)
pip install locus-mcp
Or run without installing using uvx:
uvx locus-mcp --palace ~/.locus
Claude Code skills
Install all skills at once using the Makefile:
git clone https://github.com/Nano-Nimbus/locus.git
cd locus
make install-skills
Or install individually:
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
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/).
cp -r skills/gemini/locus-palace-init .gemini/
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.
| 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 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.
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.
# 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 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 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 for dev setup, test instructions, and PR guidelines.