llm-kosh

---

開発の背景

AI エージェントはますます長いワークフローにまたがって推論できるようになっていますが、そのメモリは一時的なものか、不透明なホスト型サービスに委ねられていることが多くあります。

**LLM-Kosh はメモリをローカルインフラとして扱います：**確認可能で、持ち運び可能、監査可能、権限管理され、MCP 互換クライアント間で利用できます。

一般的なローカルファイルに、構造化インデックスとガバナンス制御を組み合わせて、エージェントに永続メモリレイヤーを提供します：

• ローカルファースト — デフォルトでは、カートリッジはお使いのマシンに保存されます。
• 確認可能 — メモリは読み取り可能で、バックアップ、差分確認、レビューが可能です。
• 監査可能 — 変更は改ざんを検知できる台帳に記録されます。
• 権限管理 — MCP は読み取り専用で開始します。書き込み、変更、非公開エクスポートには明示的なオプトインが必要です。
• ポータブル — 1 つのカートリッジを複数の互換性のある AI クライアントやワークフローで利用できます。
• 証拠を考慮 — Kosh Verify は、裏付け、矛盾、推論、証拠の不足、証拠の不在を区別できます。

インストール： python -m pip install --upgrade llm-kosh

Kosh Verify：根拠を示せるメモリー

長期にわたって保持されるメモリーでは、一度限りの誤った回答とは異なる障害が発生します。弱かったり、誤解されたりしたメモリーが、後のセッションで再び呼び出される可能性があります。

Kosh Verify は、LLM-Kosh の根拠を考慮した検証機能です。カートリッジにすでに存在する根拠に基づき、時間的な背景、裏付けとなる事実、因果関係の経路、矛盾、発見されたのではなく推論された関係、根拠の不足、安定性に関する情報、そして根拠が不十分な場合に明示的に回答を差し控える状態を含む、構造化されたレポートを生成できます。

あらゆる真実を判定する万能のオラクルではなく、インポートしたソースを保存しただけで信頼できるものにするわけでもありません。カートリッジが観測したこと、推論したこと、矛盾すること、裏付けられないことの違いを保つのが目的です。

決定論的な合成インシデントのデモをお試しください。

llm-kosh --root ./kosh-demo kosh-verify \
  "Why did checkout fail and what evidence contradicts the explanation?" \
  --when "2026-05-01T13:30:00+00:00" \
  --depth 5 \
  --demo-seed \
  --json

--demo-seed は選択したルートに合成インシデントの根拠を書き込むため、使い捨てのディレクトリを使用してください。同じ動作は、自動テストとネットワーク不要の受け入れテストハーネスでもカバーされています。

python scripts/kosh_verify_acceptance.py

契約、境界、API の例、MCP 機能、再現可能なチェックについては、Kosh Verify をご覧ください。

LLM-Kosh の特長

機能	LLM-Kosh
ローカル優先の永続メモリー	✅
MCP ネイティブのアクセス	✅
人が確認できるストレージ	✅
改ざんの痕跡が残る変更台帳	✅
デフォルトで読み取り専用のエージェントアクセス	✅
根拠に裏付けられたコンテキストパック	✅
時間的／因果的な検証	✅
矛盾と根拠の不足に関するレポート	✅
根拠がない場合に明示的に回答を差し控え	✅
ホスト型メモリーサービスが必要	❌
クラウドへの自動同期が必要	❌

アーキテクチャ

flowchart TB
    A[AI client / agent] -->|MCP| R[Access layer]
    M[CLI] --> R
    N[Background service] --> R
    O[Local HTTP MCP - optional] --> R

    subgraph KOSH[LLM-Kosh]
      R
      C[Memory]
      D[Evidence]
      E[Search]
      F[Policy]
      G[Ledger]
      H[Context packs]
      V[Kosh Verify]

      R --> C
      R --> D
      R --> F
      C --> E
      C --> G
      C --> H
      C --> V
      D --> V
    end

    C --> I[(Local cartridge)]
    D --> I
    E --> I
    G --> I
    I --> J[Plain files]
    I --> K[SQLite / FTS]
    I --> L[Audit ledger]

リポジトリのルートにはコードが含まれます。カートリッジのルートには、実際に使用するメモリーストアが含まれます。監視対象の取り込みフォルダーから新しいデータをカートリッジに取り込めるため、実行時データがソースのチェックアウトに混在しません。

60 秒で始める

Python 3.10 以降が必要です。

python -m pip install --upgrade llm-kosh
llm-kosh install --yes
llm-kosh status

これにより、パッケージをインストールし、デフォルトのカートリッジを ~/.llmkosh/cartridge に作成して、ローカルのデフォルト設定を行い、可能な場合は対応するデスクトップ連携を登録します。

カスタムカートリッジを作成してクエリを実行します。

llm-kosh --root ./my-cartridge init --owner "Local User"
llm-kosh --root ./my-cartridge add --kind note --title "First memory" --body "Hello"
llm-kosh --root ./my-cartridge query "Hello"

バックグラウンドサービスを管理します。

llm-kosh service start
llm-kosh service status
llm-kosh service stop

現在利用できる機能

コアプロジェクトは現在利用できます。

• PyPI で公開されている Python パッケージ llm-kosh
• カートリッジの作成、検索、インポート、パッキング、検証を行うローカル CLI
• Trusted Memory の提案、呼び出し、確認、競合検出、明示的なレビューを行う、管理機能付きの llm-kosh-memory CLI
• 根拠を考慮した時間的／因果的な検証を行う Kosh Verify CLI と Python API
• 決定論的な Kosh Verify インシデントデモと受け入れテスト
• 書き込み、変更、非公開エクスポートの機能ゲートを明示的に備えたローカル MCP サーバー
• これらのゲートを変更せず、読み取り専用の kosh_verify と管理機能付きの Trusted Memory ツールを追加する、ソースレベルの MCP 合成機能
• 取り込みおよびメンテナンスタスク用のバックグラウンドサービス
• ローカルインデックスを備えた、プレーンファイル形式の確認可能なストレージ
• 改ざんの痕跡が残る変更台帳
• GitHub Actions によるテスト、品質管理、セキュリティスキャン、公開ワークフロー
• 根拠に裏付けられたメモリーと引用付きコンテキストのための、実験段階の企業ナレッジベース基盤

残るリリース作業は主に、Windows、macOS、Linux 向けデスクトップパッケージの仕上げと署名です。ここで説明している llm-kosh-mcp と llm-kosh-memory のエントリーポイントは、現在の master ソースに含まれており、次回のパッケージリリースを予定しています。現在 PyPI で公開されている 2.1.3 パッケージには、これらのエントリーポイントは含まれていません。

MCP クライアントでの使用

現在公開されているパッケージでは、既存の CLI を通じて標準の MCP サーバーを利用できます。

llm-kosh --root ./my-cartridge mcp-server

現在のソースでは、組み合わせた MCP エントリーポイントから、標準サーバー、読み取り専用の kosh_verify、およびガバナンスが適用された Trusted Memory ツールを利用できます。

python -m pip install -e .
llm-kosh-mcp --root ./my-cartridge

同等のモジュール呼び出し：

python -m llm_kosh.mcp_trusted_memory_server --root ./my-cartridge

Trusted Memory の MCP インターフェースには、意図的に権限が設定されています。

• trusted_memory_recall、trusted_memory_inbox、trusted_memory_conflicts、trusted_memory_explain は読み取り専用です。
• trusted_memory_propose には --allow-write が必要です。
• trusted_memory_review には --allow-mutate が必要です。
• エージェントが作成した提案の根拠は agent_observation として記録され、user_direct に自己昇格することはありません。
• 明示的なレビューでは、元の情報源の権限を書き換えずにライフサイクルを変更できます。厳格なリコールでは、引き続き権威ある、または信頼された根拠が必要です。

Kosh Verify では、追加の権限は必要ありません。書き込み、変更、プライベートエクスポートの機能は引き続きオプトイン方式であり、標準サーバーのフラグを使用します。

llm-kosh-mcp --root ./my-cartridge --allow-write
llm-kosh-mcp --root ./my-cartridge --allow-write --allow-mutate
llm-kosh-mcp --root ./my-cartridge --allow-private

組み合わせたサーバーでは、ローカルのストリーミング可能な HTTP もサポートされます。

llm-kosh-mcp --root ./my-cartridge --http --port 8000
# endpoint: http://127.0.0.1:8000/mcp

ループバックを越えて公開する場合、HTTP トランスポートは実際のネットワーク境界として扱ってください。ガバナンスが適用されたメモリの仕様についてはTrusted Memory over MCP、kosh_verify の仕様についてはKosh Verify、一般的な MCP のセットアップについてはMCP guideを参照してください。

企業ナレッジ基盤

実験的な企業ナレッジレイヤーは、単純なメモのリコールにとどまらず、カートリッジを拡張します。参照を優先するエビデンス、セッションとエピソードの理解、エビデンスに裏付けられたメモリ、レビューのライフサイクル、権限を優先する検索、引用付きの構造化コンテキストパックを導入します。

既存のカートリッジを移行します。

llm-kosh --root ./my-cartridge brain migrate --dry-run
llm-kosh --root ./my-cartridge brain migrate
llm-kosh --root ./my-cartridge brain health
llm-kosh --root ./my-cartridge brain context "Prepare the next project decision"

ソースのバイト列をコピーせずに、既存のファイルを登録します。

llm-kosh --root ./my-cartridge brain register ./report.xlsx --artifact-type worksheet
llm-kosh --root ./my-cartridge brain inspect <evidence-id> \
  --locator '{"sheet":"Summary","range":"A1:F25"}'
llm-kosh --root ./my-cartridge brain evaluate

登録済みの JSONL エクスポートから、再生可能なセッションまたはエピソードのグラフを構築します。

llm-kosh --root ./my-cartridge brain register ./session.jsonl --artifact-type structured_data
llm-kosh --root ./my-cartridge brain understand <evidence-id> --dry-run
llm-kosh --root ./my-cartridge brain understand <evidence-id>
llm-kosh --root ./my-cartridge brain episodes --query "what was implemented"

企業ナレッジ基盤を参照してください。

基本概念

重要な場所は 3 つあります。

1. リポジトリのルート — ソースのチェックアウト先です。
2. カートリッジのルート — --root または LLMKOSH_ROOT で選択される、稼働中のメモリストアです。
3. 監視対象の取り込みフォルダー — receipts/、intake/、および設定済みの外部ドロップフォルダーです。

ファイルがカートリッジの取り込み領域にドロップされると、サービスは非同期で処理できます。外部フォルダーも [daemon].watched_directories を通じて監視できます。

オプション機能

python -m pip install "llm-kosh[watch]"     # filesystem events
python -m pip install "llm-kosh[server]"    # FastAPI service
python -m pip install "llm-kosh[semantic]"  # local semantic search
python -m pip install "llm-kosh[ingest]"    # document conversion helpers
python -m pip install "llm-kosh[all]"       # all optional features

MCP サポートは基本インストールに含まれています。

セキュリティモデル

LLM-Kosh は、エージェントの権限とエクスポート境界に関して、意図的に保守的な設計を採用しています。

• ストレージと検索は、デフォルトでローカルです。
• 自動のクラウド同期やパッケージのテレメトリーはありません。
• MCP は読み取り専用で起動します。
• 書き込み、変更、プライベートエクスポートの機能には、明示的なオプトインが必要です。
• オプションの HTTP トランスポートは実際のネットワーク境界であり、それに応じた設定が必要です。
• エクスポートされるコンテキストは、共有前に一般的なシークレットのパターンについて検査されます。
• カートリッジのファイルは意図的にプレーンテキストで保存されるため、ローカルデータの保存時に暗号化が必要な場合は、オペレーティングシステムのディスク暗号化を使用してください。

正式な脅威モデル、報告のガイダンス、現在のセキュリティ境界については、SECURITY.mdを参照してください。

プロジェクトの状況

LLM-Kosh は、永続的なエージェントメモリを実現するための、積極的に保守されているオープンソースインフラストラクチャです。

Python パッケージ、CLI、MCP サーバー、ローカルサービス、Kosh Verify インターフェース、テストワークフロー、公開の仕組みは運用可能な状態です。現在は、相互運用性、パッケージング、ガバナンスが適用されたメモリ、エビデンスを考慮した検証、および外部のコントリビューターが安全にプロジェクトを拡張しやすくする取り組みに注力しています。

Electron デスクトップアプリは Python パッケージとは別にパッケージ化されています。ローカルでの開発ビルドと Windows インストーラーのスモークテストはサポートされていますが、デスクトップアプリの一般提供には、検証済みの Windows コード署名と macOS Developer ID による署名および公証が引き続き必要です。

詳細なリリース状況については、GA_READINESS.mdを参照してください。

開発者向けワークフロー

python -m pip install -e ".[server,watch,ingest]"
python -m pytest -q

小規模な公開検証受け入れ契約は、個別に実行してください。

python scripts/kosh_verify_acceptance.py

パッケージングまたはリリースに関する変更の場合：

python -m build
python -m twine check dist/*

ネイティブ C++ の数値計算アクセラレーションは任意です。テストするには、ビルド前に LLM_KOSH_BUILD_NATIVE=1 を設定し、pybind11 をインストールしてください。リリース用ホイールでは、移植性の高い純粋な Python のフォールバックを使用します。

コントリビューション

以下の分野を中心に、コントリビューションを歓迎します。

• MCP の相互運用性
• テストと回帰テストのカバレッジ
• パッケージングとクロスプラットフォームの信頼性
• ドキュメント
• ローカルファーストのメモリワークフロー
• セキュリティの強化
• エビデンスと検索品質
• 再現可能な検証とベンチマークの方法論

大規模な変更を提案する前に、CONTRIBUTING.md をお読みください。再現可能で機密情報を含まないバグや機能提案には GitHub Issues を使用し、セキュリティに関わる報告については SECURITY.md に従ってください。

ドキュメント

ガイド	目的
クイックスタート	初回のインストールとローカルでの使用
Kosh Verify	エビデンスを考慮した検証契約と再現可能なデモ
MCP 経由の信頼できるメモリ	MCP 経由での、管理されたエージェント間の想起、提案、競合、レビュー
アーキテクチャ	システムの構造と設計
CLI リファレンス	コマンドリファレンス
MCP ガイド	MCP のセットアップと使用方法
開発者ガイド	開発ワークフロー
MCP 開発者ガイド	MCP の内部仕様
サービス開発者ガイド	バックグラウンドサービスの内部仕様
デスクトップ開発者ガイド	デスクトップアプリのパッケージング
リリースエンジニアリング	ビルドとリリースのプロセス
セキュリティ	脅威モデルと報告方法
GA 対応状況	現在のリリース状況
アーカイブされた過去のドキュメント	過去の資料

オープンソース

LLM-Kosh は MIT License のもと、オープンに開発・保守されています。

バグ報告、目的を絞ったプルリクエスト、相互運用性の改善、テスト、ドキュメントへのコントリビューションを歓迎します。

---