locus

Locus

自律型 AI エージェント向けの、階層構造を持つ Markdown ベースのメモリーシステムです。各ディレクトリは宮殿の一室（locus）であり、必要に応じて参照する特定の知識が含まれています。 Method of Loci の基本単位にちなんで名付けられました。

基本的な考え方： コンテキストウィンドウを小さく保ちます。宮殿全体ではなく、必要な部屋だけを読み込みます。

---

仕組み

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

エージェントは INDEX.md を読み、関連する部屋へ移動して、その部屋だけを読みます。 セッションログは、統合によって正規ファイルにまとめられるまで蓄積されます。

詳しいドキュメントはWikiをご覧ください。

---

クイックスタート

# 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

---

インストール

MCP サーバー（MCP 対応クライアント向けの推奨方法）

pip install locus-mcp

uvx を使えば、インストールせずに実行できます：

uvx locus-mcp --palace ~/.locus

エージェントスキル

スキルファイルは、特定のランタイム向けに書かれた Locus の唯一の要素です。 宮殿の規約、MCP サーバー、recall／lint／index CLI はランタイムに依存せず、ファイルを読み取れる、または MCP で通信できるものであれば何からでも利用できます。 skills/claude/ のスキルは Claude Code 向けに作成・保守されており、ここで提供されているのはこのセットのみです。 これらは YAML フロントマター付きのプレーンな Markdown なので、別のランタイム向けに自由に調整できます。 以前はランタイムごとのコピーを skills/codex/ と skills/gemini/ に置いていましたが、3 種類のバリエーションを適切に保守するコストが、得られるものを上回ったため削除しました。

クローンからインストールします：

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 でインストール先を上書きできます。

スキル	コマンド	説明
locus	/locus	記憶を呼び出し、宮殿内を移動し、部屋やセッションログを書き込み、インデックスを再生成します
locus-consolidate	/locus-consolidate	セッションログを正規ファイルに統合します
locus-audit	/locus-audit	宮殿の健全性を監査します
locus-feedback	/locus-feedback	宮殿から呼び出した記憶について明示的なフィードバックを記録します
locus-release	/locus-release	リリース後の検証ワークフロー（コントリビューター向け）
locus-security	/locus-security	信頼タグ、nonce の管理、locus-security CLI
locus-palace-init	/locus-palace-init	既存のメモリーファイルから宮殿を初期化します

エージェント SDK（Python）

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

---

MCP サーバー

locus-mcp コマンドは、Model Context Protocol 経由で 5 つのツールを公開します。

すべてのローカル連携には stdio を使用してください（Claude Desktop、Claude Code、Codex、Gemini のデフォルトで、追加のフラグは不要です）。 SSE トランスポートはネットワーク環境へのデプロイで利用できます（--transport sse）。明示的に FASTMCP_HOST=0.0.0.0 を設定する必要があります。デフォルトでは、サーバーはループバックにバインドします。

ツール	説明
memory_list	INDEX.md（引数なし）を返すか、部屋のファイル一覧を返します
memory_read	宮殿内の任意のファイルを読み取ります
memory_write	ファイルをアトミックに書き込みます（保護機能により、_metrics/、sessions/、.sig/、.security/ には書き込めません）
memory_search	共有 FTS5 インデックスを使って、順位付けされた全文検索を行います（記憶の呼び出しを参照）。FTS5 がない場合は ripgrep のみを使用します
memory_batch	1 回の呼び出しで宮殿内の最大 20 ファイルを読み取ります。複数の部屋を読み込む場合に使用します

--security を追加すると、読み取り時の Ed25519 署名検証と、書き込み時の自動署名が有効になります。 詳しくは、以下のセキュリティをご覧ください。

Claude Desktop（claude_desktop_config.json）

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

uvx を使う方法（インストール不要）：

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

Cursor / Zed

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

環境変数

すべてのクライアントは、--palace の代わりに LOCUS_PALACE をサポートしています。

export LOCUS_PALACE=~/.locus
locus-mcp

クライアントの完全なセットアップガイドについては MCP サーバーの設定 を、 アーキテクチャの詳細については spec/mcp-server.md を参照してください。

---

リコール

locus recall は、「これについてすでに何を知っているか」という問いに1回の呼び出しで回答します。フックからすべてのプロンプトで実行できるほど高速です。任意の数の Markdown ルート（palace、OKF バンドル、Claude Code のメモリディレクトリ、またはそれらすべて）を対象に、SQLite FTS5 インデックス（標準ライブラリのみ、PyYAML 不要）を維持します。

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

フラグ	デフォルト	説明
--root DIR	.locus.toml、次に LOCUS_PALACE	インデックス化するディレクトリ。複数指定可能
-k N	3	ヒット数
--budget BYTES	4096	テキスト出力の上限
--include journal	off	type: Journal のファイルを含めます
--type TYPE	all	このフロントマター型のみを対象にします。複数指定可能
--json	off	テキストではなく JSON リストを出力します
--refresh	off	インデックスを最初から再構築します

結果はフロントマターに基づきます。title（または name、あるいは最初の見出し）、description、tags、type（または metadata.type）、modified（なければ generated.at、それもなければファイルの mtime）、status、stale_after、verified が使われます。ランキングには bm25 を使い、タイトルと説明の重みを本文より高くします。完全に同点の場合は、人間がレビューしたファイルを優先し、次に modified が新しいものを優先します。stale_after を過ぎているか、status が deprecated の場合、ヒットには STALE のフラグが付きます。信頼度の階層は OKF に従います。unverified、machine-confirmed（人間以外による verified エントリのみ）、human-reviewed（by が human: で始まる verified エントリ）。

ルートは、プロジェクト内または任意の親ディレクトリにある .locus.toml に記述できます。

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

インデックスは ${XDG_CACHE_HOME:-~/.cache}/locus/<hash-of-roots>.sqlite に保存され、ルート内には保存されません。また、呼び出しごとに（mtime、次にコンテンツハッシュを使って）差分更新されます。ヒットがない場合、テキスト出力は空になり、終了ステータスは 0 のままです。そのため、プロンプトフックから無条件に呼び出せます。

#!/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"

MCP サーバーの memory_search は同じインデックスを使うため、MCP の結果も同じ方法でランキングされます。詳細なルールは spec/recall.md を参照してください。

---

リントとインデックス

locus lint は、Markdown ルートが Open Knowledge Format v0.2 への準拠と、Locus palace の規約を満たしているかをチェックします。locus index は、これらの規約で定義されているインデックスファイルを生成します。どちらも同じフロントマターの recall インデックスを読み込み、Agent SDK をインポートしません。そのため、準拠状況のチェックのみを行う CI ジョブでは、Agent SDK をインストールする必要はありません。

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

フラグ	デフォルト	意味
--root DIR	.locus.toml、次に LOCUS_PALACE	チェックするディレクトリ。複数指定可能
--check	オフ	エラーがある場合にゼロ以外で終了します。CI 向け
--strict	オフ	--check で警告をエラーとして扱います
--fix	オフ	推定可能なフィールドを追加します。既存のキーは書き換えません
--type-map DIR=TYPE	なし	DIR 以下の OKF タイプを推定します。複数指定可能
--archive-glob GLOB	なし	status: deprecated を付与するパス。複数指定可能
--json	オフ	テキストではなく JSON レポートを出力します

ルールは 2 種類に分かれています。okf.* は仕様で必須とされる項目をチェックします。すべての予約対象外ドキュメントに解析可能なフロントマターと空でない type があること、index.md にバンドルルートの okf_version 以外のフロントマターがないこと、log.md の見出しが日付形式で新しい順に並んでいること、タイムスタンプが ISO 8601 形式であることを確認します。不明なキーと不明なタイプ値は報告されません。仕様では、コンシューマーがその両方を許容することが求められているためです。locus.* は spec/size-limits.md のサイズ制限と spec/room-conventions.md のルームのメインファイル規則という、パレスの規約をチェックします。

エラーがあると --check は失敗し、警告は参考情報として扱われます。パレスにはフロントマターがまったくない場合も正当にあります。そのため、パレスルートでは、欠落しているタイプに関するルールは警告となり、パレス仕様自体が説明する構成で CI が失敗することはありません。

--fix が追加するのは次の 3 つのフィールドのみです。--type-map または [lint.types] の type、ファイルの最初の git コミットから取得する generated.at、アーカイブパスの status: deprecated です。キーの書き換えや削除は行わず、generated ブロックも新たに作成しません（ファイルのどこにも、誰が生成したかは記されていないためです）。2 回実行しても出力バイト列は同一です。

index

フラグ	デフォルト	意味
--root DIR	.locus.toml、次に LOCUS_PALACE	インデックスを作成するディレクトリ。複数指定可能
--check	オフ	何も書き込まず、差異があればゼロ以外で終了します。CI 向け
--kind	auto	okf、palace、memory の分類を強制します
--json	オフ	テキストではなく JSON レポートを出力します

生成される内容はルートによって異なります。OKF バンドルでは、セクション 8 の形式（* [Title](path) - description。フロントマターの okf_version: "0.2" はバンドルルートのみに記載）で各ディレクトリに index.md を作成します。パレスでは、50 行のルーティングテーブル INDEX.md を作成します。Claude Code のメモリディレクトリでは、各トピックファイルにつき - [Title](file.md) - description の 1 行を記載した MEMORY.md を作成します。 出力は決定的であるため、--check はバイト単位で比較し、書き込まれるのはインデックスファイルのみです。

1 つの .locus.toml で両方を設定します。

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

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

ルールの全容は spec/lint-and-index.md をご覧ください。

---

セキュリティ

セキュリティシステム（--security）は、すべてのパレスファイルに Ed25519 署名を付与し、すべてのエージェントセッションに固有の暗号学的ノンスを割り当てます。ツールの出力には、エージェントに表示される前に [TRUSTED]、[DATA]、または [CRITICAL-DATA] のタグが付けられます。エージェントスキル（locus-security）は、エージェントに対し、[DATA] の内容から事実を抽出しつつ、その中の指示には決して従わないよう教えます。

# One-time setup
locus-security init-config --palace ~/.locus   # writes 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 "..."

locus-security CLI には 5 つのサブコマンドがあります。init-config（パッケージ内に同梱されたコピーから注釈付きの locus-security.yaml を書き込みます）、init-keys、sign-all、verify-all（ファイルの検証に失敗した場合、またはパレス内に署名可能なファイルがまったくない場合に終了コード 1 を返します）、および rotate-keys です。sign-all は UTF-8 として読み取れないファイルがあっても処理を中断せず、そのファイル名を表示してスキップし、スキップしたファイルがあれば終了コード 1 を返します。どちらのコマンドも、リンク先がパレスの外に解決されるシンボリックリンクをたどりません。これらのリンクは sign-all ではファイル名を表示してスキップされ、verify-all では失敗として報告されます。

脅威モデル： 直接的なプロンプトインジェクション、メモリポイズニング、外部データを介した間接的なインジェクション、ノンスの流出、複数ターンにわたるコンテキストのドリフト。

プロトコル、設定リファレンス、設計上の決定について詳しくは、docs/security.md をご覧ください。

---

ベンチマーク

宮殿ナビゲーションでは、特定のクエリに対して、完全な再現率を維持しながら、フラットメモリと比べてコンテキスト行数を52％削減できます。セッションのみのクエリ（まだ統合されていない直近の作業）にアクセスできるのは、宮殿だけです。

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

グラフと手法の詳細については、docs/benchmarks.md を参照してください。

---

構造

example-palace/   Palace template; `locus init` writes it into a new palace
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
  recall.md             locus recall: roots, index, ranking, trust tier, STALE
  lint-and-index.md     locus lint and locus index: OKF conformance, generated indexes
  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/        Templates for INDEX.md, rooms, session logs, locus-security.yaml
                  (`locus init --show list`; both trees ship inside the wheel)
skills/
  claude/         SKILL.md files for Claude Code + Agent SDK (the only maintained set)
    locus/              Recall, palace navigation, writes, index and lint
    locus-consolidate/  Room consolidation
    locus-audit/        Palace health audit
    locus-feedback/     Recall quality feedback
    locus-palace-init/  Bootstrap a palace from existing memory files
    locus-release/      Post-release verification (contributors)
    locus-security/     Security conventions (trust tags, nonce discipline)
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
  conform/        locus lint and locus index: OKF conformance, index generation
  recall/         locus recall: FTS5 index shared with memory_search
  security/       Ed25519 security system — keys, signing, taint, nonce, middleware
  scaffold.py     locus init: packaged templates and palace scaffolding
  utils.py        Shared utilities (slug_from_path)

---

ロードマップ

マイルストーン	ステータス	主な内容
v0.1 - 基盤	✅ 完了	仕様、規約、サイズ制限
v0.2 - コア宮殿	✅ 完了	テンプレート、スキル、Agent SDK、ベンチマーク
v0.3 - パフォーマンス指標	✅ 完了	コンテキスト追跡、フィードバック、提案
v0.4 - 自己評価	✅ 完了	宮殿の監査、ヘルスレポート、推定フィードバック
v0.5 - MCP サーバー	✅ 完了	memory_list/read/write/search を備えた MCP サーバー
v0.6 - 一般公開	✅ 完了	ベンチマーク、ドキュメント、CI、PyPI
v0.7 - リモート MCP サーバー	✅ 完了	SSE トランスポート、Bearer 認証、Docker イメージ、K8s デプロイ
v0.8 - 自動メモリブリッジ	✅ 完了	Claude Code の自動メモリ検出、memory_batch ツール
v0.9 - セキュリティシステム	✅ 完了	Ed25519 署名、汚染追跡、nonce ウォーターマーク、--security フラグ

---

貢献

開発環境のセットアップ、テスト手順、PR ガイドラインについては、CONTRIBUTING.md を参照してください。

ライセンス

MIT