osiris

OSIRIS

AI エージェント向けの、キャッシュを考慮したコンテキストエンジン兼状態ガバナーです。 標準の MCP サーバーで、ローカルファーストであり、どのモデルプロバイダーにも依存しません。

OSIRIS は AI エージェントのコストを抑え、処理を高速化し、信頼性を高めます。トークンとループを減らし、不要なツールの使用をなくし、コンテキストの喪失を防ぎます。

OSIRIS は他の MCP サーバー（ファイルシステム、Git、GitHub、シェル、ブラウザーなど）を置き換えるものではありません。それらと共存し、プロンプトコンテキストにかかるコストを大幅に削減します。

---

1. 中核となるアーキテクチャ上の制約

MCP サーバーが、クライアントホストによって組み立てられた最終的なプロンプトを見ることは決してありません。見ることができるのは、エージェントから送られてくる内容だけです。そのため、OSIRIS には次のことができません。

実現したいこと	標準の MCP サーバーで実際にできること
プロンプトに直接書き込む	正規の状態を生成し、エージェントにそれを持ち運ばせる
過去の会話ターンを消去する	今後のターンに向けて外部化する内容を決める
別の MCP サーバーのツールを隠す	Tool Compass を通じて推奨する
プロンプトのトークン数に厳密な上限を設ける	アクションをブロックする（不変条件、予算の適用）

OSIRIS が約束する内容は誠実です。クライアント側のプロンプトビルダーではなく、安定した状態と強制可能な安全性の契約を提供します。

---

2. シールドされたマニフェスト — 中核となる設計

osiris.plan は、エージェントがコンテキストウィンドウ内の固定位置に保持する、決定論的なブロック（約120トークン）を返します。

OSIRIS/1 task=7c3f obj="fix PowerShell profile bug" plan=3/7
inv=4 files=6 refs=9 dec=2 budget=ok
SEAL=sha256:3f9a1c…c21b

SEAL は安定したゾーンの SHA256 ダイジェストです。エージェントは各ターンでこれを osiris.observe に渡します。OSIRIS は再計算して、状態の変化をただちに検出します。

これが OSIRIS の受動的な伝達手段です。エージェントがツールの呼び出しを停止しても、重要な状態を保持して確実に持ち運べます。

プロンプトキャッシュはプレフィックスベースのため、ハッシュは3つ

head_hash   = sha256(system_head ‖ rules)                       immutable
zoneB_hash  = sha256(objective ‖ global_plan ‖ tool_contract)   quasi-stable
tail_hash   = sha256(constraints ‖ pinned_decisions)           append-only
prefix_hash = sha256(head_hash ‖ zoneB_hash)                   ← cached prefix
zoneA_hash  = sha256(head_hash ‖ tail_hash)                    ← full ZONE A

変更	判定	キャッシュコスト
head_hash	重大なドリフト	全体の再プリフィル
zoneB_hash	軽微なドリフト	差分のみ再プリフィル
tail_hash（追加）	通常の拡張	差分のみ再プリフィル
固定項目の書き換え	重大なドリフト（意味的）	キャッシュは維持、タスク状態が破損

制約や決定を追加すると tail_hash は変わりますが、prefix_hash は変わりません。プロンプトキャッシュは維持され、新しいトークンのみがプリフィルされます。

固定された決定の書き換えは明示的に検出されます。OSIRIS はコレクションの同一性をチェックし、意味的な破綻としてフラグを立てます（semantic_break: true、cause: pinned_rewrite）。

---

3. 6 つの MCP ツール

コンテキスト内のスキーマと説明のフットプリント：1,019 トークン（bench/run_bench.py で計測）。タスク開始時にコストが発生し、セッション全体で償却されます。800 トークン以上のペイロードがあれば、最初のターンで元が取れます。

ツール	役割	典型的な応答
osiris.plan	タスクの開始／更新／再開／ステータス確認。封印済みマニフェストを生成	約160トークン
osiris.precheck	アクションを許可または拒否（不変条件、予算、重複排除）	約70トークン
osiris.observe	アクションを記録し、ループを検出し、大きなデータをオフロードして、メモリを更新	約50トークン
osiris.recall	参照を再展開（サーバー側でフィルタリング：grep、範囲、アウトライン）	可変
osiris.checkpoint	スナップショット、再開、完了レポート、可逆的な圧縮	約80トークン
osiris.handoff	実行可能な委任コントラクトと構造化された結果	約200トークン

osiris.observe は、ロギング、ループ保護、ペイロードの外部化、メモリレジストリ、自動プルーニングを 1 回の呼び出しにまとめるため、エージェントは常にシームレスに応答できます。

拡張操作

呼び出し	動作
osiris.observe(kind="dropped", result=<ref>)	ドロップレシート：エージェントがペイロードをプロンプトから退避したことを確認 → トークン削減が証明され、クレジットされます
osiris.observe(kind="head"|"contract", result=…)	システムプロンプトの先頭部分／クライアントコントラクトを記録し、キャッシュを無効化する揮発性トークン（タイムスタンプ、UUID）を検出
osiris.recall(op="grep"|"range"|"head"|"tail"|"outline"|"aggregate"|"jsonl")	サーバー側でフィルタリング：要求した一致項目のみがコンテキストウィンドウに入ります
osiris.plan(mode="status")	コンテキストの負荷の内訳（計測値、申告値、不明値）
osiris.checkpoint(mode="compact"|"trim"|"clear")	可逆的なセッション圧縮の準備
osiris.precheck → suggest_alternative	重複操作の競合をアクティブに解決

リソースとプロンプト

• osiris://task/{task_id}/manifest — アクティブなゾーン、ドリフト状態、目標
• osiris://task/{task_id}/status — リアルタイムのコンテキスト負荷
• osiris://ref/{ref} — 参照されているペイロードの生バイトコンテンツ
• プロンプト osiris/task-resume — クラッシュ後のエージェント復旧用クリーンテンプレート

---

4. アーキテクチャ

┌──────────────────────────────────────────────────────────────┐
│  Agent (Claude Code, Cursor, MiniMax Code, Codex, Cline…)   │
│  Context: system │ tools │ OSIRIS MANIFEST │ history         │
└───────────────────────────┬──────────────────────────────────┘
                            │  MCP stdio — 6 tools, ~1,019 tok schema
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  osiris-mcp  (server.py)                                     │
│  plan · precheck · observe · recall · checkpoint · handoff   │
└───────────────────────────┬──────────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────────┐
│  core/                                                        │
│   task_state  Typed TaskState (objective, plan, decisions)    │
│   memory     Typed memory registry by kind and scope         │
│   refs       Content-addressed store (verified on read)      │
│   prefix     Zones, 3-hash system, drift, PrefillPlan        │
│   prune      Reversible externalization, 4 modes             │
│   query      Server-side payload filtering (grep, range...)  │
│   compaction trim / compact / clear (lossless)               │
│   pressure   Context pressure metrics & tracking             │
│   loopguard  Fingerprinting, 5 loop patterns detection       │
│   invariants TOML rule engine (guard rails)                  │
│   compass    Tool Compass (dynamic relevance scoring)        │
│   handoff    Executable agent delegation contracts           │
│   events     Append-only event journal + checkpoints         │
│   ledger     Tokens / cost / savings / OSIRIS overhead       │
│   fileops    Sandboxed file inspection (roots, size limits)  │
│   redact     Secret scrubbing before any hashing             │
│   policy     Budget policies & token enforcement             │
└───────────────────────────┬──────────────────────────────────┘
                            ▼
        ~/.osiris/osiris.db  +  ~/.osiris/reports/

---

5. メモリモデル

決定論的で型付き、コンテンツアドレス可能なメモリです。不透明なベクトルデータベースではありません。

TaskState
├── objective      immutable
├── constraints[]  append-only
├── decisions[]    append-only, pinned verbatim
├── plan           completed / active / remaining steps
├── files{}        path, SHA-256 hash, mtime, last access, ref
├── tool_results{} cache_key, ref, size, token cost, TTL
├── failures{}     error signature, tool, args hash, attempts, lesson
├── lessons[]      general behavioral rules learned
├── handoffs{}     cross-agent delegation contracts
└── budget         estimated vs consumed tokens and cost

スコープ：task → project → agent → global。

---

6. キャッシュ対応プルーニング

セキュリティ不変条件：プルーニングはペイロードデータをコンテンツアドレス可能な参照（mem://sha256:…）へ移動します。削除は一切行いません。

ZONE_A_pruning_cost = pruned_tokens
ZONE_C_or_D_pruning_cost = 0                      ← always zero cost
net_savings = pruned_tokens − (prefix_tokens × P(cache_dead) × prefix_pruned)

モード	トリガー	退避対象	キャッシュへの影響	ユースケース
cache_ttl（デフォルト）	Δt > TTL	C/D、およびキャッシュの期限切れ時のみ A/B	なし	推奨デフォルト
conservative	非常に高いしきい値	作業ゾーン（C/D）のみ	なし	コストの高い API モデル
balanced	中程度のしきい値	C/D と古い履歴ターン	なし	標準的なエージェントワークフロー
aggressive	低いしきい値	再展開可能なすべて	プレフィルのリスクは軽微	高速なローカル LLM

---

7. LoopGuard による保護

fingerprint = sha256(tool ‖ canonical_args ‖ result_signature)

検出項目	トリガー信号	判定
完全な重複	同一のフィンガープリント	suggest_alternative
失敗の繰り返し	同じエラーシグネチャ（3 回以上）	block + required_action
ループパターン	引数を変えても同じエラー	warn
振動	A/B/A/B の交互パターン	warn
暴走	状態の進展がないまま N 回呼び出し	warn / block

---

8. 不変条件（ガードレール）

.osiris/invariants.toml でプロジェクトの安全ルールを定義します。

[[invariant]]
id = "tests-before-commit"
when = { tool = "git.commit" }
require = { state = "tests_passed" }
message = "Cannot commit while tests are failing"

[[invariant]]
id = "no-test-edit"
when = { path_glob = "tests/**" }
verdict = "block"
message = "Modifying test suites requires explicit approval"

---

9. ロスレス検証と非損失の証明

OSIRIS は、オフロードされたデータの完全な監査可能性を保証します。

1. 自己検証可能な参照：mem://sha256:<hash>。読み取り時には、データを返す前にハッシュと照合して整合性を再検証します。
2. 削除経路なし：データはローカルストアに移動され、完全に削除されることはありません。
3. 再現可能な監査：

   python -m osiris audit --task <task_id>
   

   非損失の暗号学的証明を出力します：

   {"lossless": true, "items_externalized": 14, "items_verified": 14, "items_missing": 0, "integrity_violations": []}
   

---

10. 検証済みベンチマーク

自動コーディングワークフローで python bench\run_bench.py を実行した際の実測値：

ペイロードサイズ	ベースラインコンテキスト	固定 OSIRIS	適応型 OSIRIS	純改善率	OSIRIS モード	オーバーヘッド
200 tok	1,583	2,687	1,651	−4.30%	傍観者	34 tok
800 tok	3,851	3,755	3,261	+15.32%	ライト	1,810 tok
2,000 tok	9,015	5,229	5,233	+41.95%	標準	2,492 tok
5,000 tok	20,979	8,171	8,168	+61.07%	標準	2,439 tok
20,000 tok	82,135	23,427	23,440	+71.46%	フル	2,422 tok

• アクセスコスト：スキーマに 1,019 トークンを使用。セッション内のタスク全体で償却されます。
• セッション純損益ゲート：合格（全スイートでの最悪ケースの純増：+951 トークン）。
• 20,000 トークン時：コンテキスト使用量を純増で 71.46% 削減します。

---

11. クイックスタート

cd D:\MCP-Osiris
uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe -e ".[dev]"

CLI 検証

.venv\Scripts\python.exe -m pytest tests -q        # Run test suite (77 passed)
.venv\Scripts\python.exe -m ruff check src tests    # Code linting
.venv\Scripts\python.exe -m osiris health           # Server health check
.venv\Scripts\python.exe -m osiris audit --task t_1 # Cryptographic non-loss proof
.venv\Scripts\python.exe bench\run_bench.py         # Reproduce benchmarks

MCP サーバーとしての登録

クライアント設定（mcp.json）に追加します：

{
  "mcpServers": {
    "osiris": {
      "command": "D:\\mcp-osiris\\.venv\\Scripts\\python.exe",
      "args": ["-m", "osiris"],
      "env": {
        "OSIRIS_HOME": "C:\\Users\\Tech\\.osiris",
        "OSIRIS_ROOTS": "D:\\mcp-osiris"
      }
    }
  }
}

---

12. インストール

PyPI から（推奨）

pip install mcp-osiris          # or: uv pip install mcp-osiris
mcp-osiris                      # runs the MCP server on stdio
osiris health                   # CLI verification
osiris-dashboard --port 8770    # Control Plane (dashboard)

npm から（Python のセットアップ不要）

npx -y osiris-mcp

npm パッケージは stdio ランチャーです。次の順序で Python ランタイムを解決し、 PyPI パッケージ mcp-osiris を実行します。OSIRIS_PYTHON → uvx → python3 → python。

ソースから

git clone https://github.com/MlkBlk-IT/osiris.git
cd osiris
uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe -e ".[dev]"

MCP クライアントの設定

{
  "mcpServers": {
    "osiris": {
      "command": "npx",
      "args": ["-y", "osiris-mcp"],
      "env": {
        "OSIRIS_HOME": "~/.osiris",
        "OSIRIS_ROOTS": "/path/to/project"
      }
    }
  }
}

変数	デフォルト	役割
OSIRIS_HOME	~/.osiris	SQLite データベース、レポート、キャッシュ
OSIRIS_ROOTS	(空)	ファイルの読み取りが許可されるルート（; 区切り）
OSIRIS_CACHE_TTL_S	300	キャッシュ TTL（秒）
OSIRIS_PRUNE_THRESHOLD_TOKENS	40000	削減しきい値
OSIRIS_DISPATCH_ONLY	0	1 → osiris.call のみを公開

---

ライセンス

MIT © 2026 Malik Belkacemi (MLKBLK-IT)