knowledge

knowledge

AI コーディングエージェント向けの小規模なセルフホスト可能なナレッジサーバーです。MCP を通じて、どのデバイスでも Claude Code、Codex、Antigravity（agy）に同じ最新のドキュメントとメモリを提供し、ノート同士のつながりを示すグラフを備えた Web UI も利用できます。

ノートはディスク上のプレーンな Markdown ファイルです。サーバーはノートをインデックス化し、デバイスごとのトークンを使ってエージェントに提供するとともに、いくつかの運用ルールに照らしてチェックします。そのため、エージェントのメモリが増えても、見つけやすく整理された状態を保てます。

_{demo/ にある架空のデモ用ノートです。uv run --project server --with playwright python demo/screenshot.py で再生成できます。}

概要

• エージェント向け MCP ツール： 検索（正規表現およびセマンティック検索）、読み取り、一覧表示、関連メモ、競合チェック付きの書き込みと編集、新規メモ、コピーとして保持する削除、履歴、Lint、ウェブページ、PDF、テキストを未加工ソースとして取り込む機能。
• セッション開始時のコンテキスト： 各エージェントには、共有の指示、共通ルール、作業対象プロジェクトのメモリインデックスに加え、期限を過ぎた未完了項目とエージェント間の引き継ぎタスクが渡されます。
• セッション中の引き継ぎ： Claude Code、Codex、agy はプロンプトの前（最長でも2分ごと）に /tasks を呼び出し、引き継がれたタスクを確認します。セッション開始後に追加されたタスクは、エージェントに一度通知されます。同じターンごとの呼び出しによって、サーバーは開始フックが実行されなかった再開セッションも含め、すべてのセッションを制御できます。通知（ドキュメントがアーカイブフォルダーに移動された場合など）は、問い合わせを行ったデバイスの最初のセッションに送られます。そのセッションでその後ターンがなかった場合は、1時間後に再度通知されます。また、デバイスで最後に実行した同期から docs_sync_minutes（管理ページの「設定」）を超えている場合、いずれか1つのセッションにバックグラウンドでドキュメントミラー全体を同期するよう依頼します。
• 別のエージェントを起動する（同一マシン）： knowledge_edit／knowledge_write／knowledge_new_memo の実行後、プラグインはそのマシン上で、エージェントとプロジェクトごとに新しいタスクがある最新のアイドルセッションを起動します。Codex は codex queue --thread、agy はローカルの言語サーバー経由で起動します（agy セッションは、プラグインからの依頼に応じて、ターミナルコマンドとして agent_hooks.py register を一度実行して登録します）。Claude Code は asyncRewake 待機フック経由で起動します。起動されたエージェントはユーザーに通知し、同意を待ちます。管理ページには、トークンごとに過去1週間に確認されたセッション（エージェント、セッション ID、プロジェクト、起動可能かどうか）が表示され、それぞれに「忘れる」ボタンがあります。
• 使用量制限： 各プロンプトでエージェント自身の使用量制限の消費状況を確認し、セッションと制限ウィンドウごとに、50％、75％、90％に達したことを一度ずつ通知します。95％以上では、新しいサブエージェントの起動を拒否します（Claude Code の Agent、Codex の spawn_agent、agy の invoke_subagent）。数値は各エージェント自身のものです。Codex は rollout、agy は言語サーバー（初回の register 後）の数値を使います。数値がステータスラインにしか渡されない Claude Code では、プラグインがセッション開始時にステータスラインの前に小さなタップを設置します（既存のステータスラインは引き続き表示されます。元のコマンドは ~/.knowledge/statusline-original.json に保存されます）。数値が取得できない場合は、通知も拒否も行われません。
• シークレットガード： 既知のシークレット値をファイルに書き込む編集は拒否されます（Claude Code の Edit／Write、Codex の apply_patch、agy のファイルツールが対象です）。token.py push-secrets がハッシュファイルを作成します。新たに書き込まれるテキストのみを対象とするため、シークレットの削除は許可されます。
• トークン使用量： セッションログには、ログに記録された各部分のトークン数（キャッシュされていない入力、キャッシュへの書き込み、キャッシュからの読み取り、出力）も送信されます。Claude は1回の呼び出しに対するブロックごとのコピーを1回として数え、Codex は累計値の差分を使います。Lint は usage_outlier を報告します。これは過去1週間のセッションのうち、そのエージェントの通常値を大幅に超えるものです（過去1か月のデータに対する修正 z スコアが3.5を超える場合。セッション数が10件以上の場合）。
• プロジェクト： 各プロジェクトにはドキュメントルートとメモリルートがあります。セッションは作業フォルダーからプロジェクトを選びます。また、トークンを1つのプロジェクトに限定することもできます（ゲスト）。新しいサーバーには homelab というプロジェクトが1つあり、ドキュメントは data/docs、メモリは data/memory にあります。管理ページではプロジェクトを追加でき、ウェブ UI に表示する名前を設定できます。
• Lint： 約80ミリ秒で実行される決定的なチェックです。リンク切れ、ファイルのないインデックス行とその逆、フロントマターやセクションの欠落、メモのサイズ超過、期限切れの未完了項目、シークレットの可能性（値は表示されません）、未処理の未加工ソースを確認します。
• ウェブ UI： トピックごとのホーム画面、全文検索、関連メモ付きのメモプレビュー、エディター、変更履歴、Lint タブ、トークン・ユーザー・プロジェクトを管理するページがあります。ライトモードとダークモードを選べます。
• グラフ： メモをノード、リンクを線として表示し、トピックごとに島を形成します。線の太さと引力は、2つのメモの関連度（直接リンク、共通ソース、共通の隣接メモ、同じ種類）に応じて変わります。トピック間の弱いリンクは、ホバーすると表示されます。
• 外部スキル： 管理者はリンクを使って GitHub からスキルフォルダーを追加できます。コミットに固定され、プレーンテキストのみが取り込まれます（ツール、フック、読み込み時のコマンドは含まれません。また、コピーを許可するライセンスが必要です）。自作のスキルと同じように共有できます。週次チェックでは、小さな更新は自動で取り込み、大規模または安全でない更新は管理者の確認用に保留します。`` 内のローカル追加分は更新後も保持されます。
• アーカイブ： archief/、archive/、old/、history/ などのフォルダーは、指定がない限り検索対象から除外されます。
• オフラインコピー： 書き込みトークンを持つデバイスはメモリのコピーを保持し、差分のみを同期します。サーバーが停止している場合も、エージェントにはキャッシュ済みの開始時コンテキストが渡されます。
• シークレット： 既知のシークレット値はすべての回答でマスクされ、すべての書き込みで拒否されます。

動作の仕組み

• サーバー（server/）：Python 製で、ステートレスなストリーム可能 HTTP MCP とウェブ UI を 1 つの Docker コンテナーで実行します。すべてのテキストをメモリー上に保持するため、数千件のファイルでも数十ミリ秒で検索できます。監視プロセスが変更されたパスを送信して即時更新し、60 秒ごとの stat のみの再スキャンが安全策として機能します。埋め込み（セマンティック検索と関連メモ用）は ONNX でローカル実行され、データがマシンの外に出ることはありません。
• クライアント（plugin/）：Claude Code、Codex、agy のプラグインとしてインストールする 1 つのフォルダーです。MCP サーバー、セッション開始フック、セッションログ、ゲストプロジェクト用のドキュメントミラーが追加されます。Codex と agy は小規模な stdio リレーを介してサーバーに接続するため、トークンが設定ファイルに保存されることはありません。clients/knowledge-agent.py がすべてをセットアップします。
• **トークン：**デバイスごとに 1 つの長いランダムトークンを OS のキーリング（Linux Secret Service、macOS Keychain、Windows Credential Manager）に保存します。トークンは読み取り専用、マスク、単一プロジェクトに制限、または共有スキルの同期を許可する設定にできます。
• **ウェブサインイン：**1 人の管理者用パスワード（KNOWLEDGE_UI_PASSWORD、30 日間有効な署名付き Cookie、1 分あたりの誤入力は最大 5 回）、または複数人で使う場合は、ユーザーヘッダーと共有シークレット（KNOWLEDGE_PROXY_SECRET）を設定する forward auth 対応のリバースプロキシ（Authentik など）を使用します。

サーバーを実行する

Docker を使う場合、すべてのメモは compose.yaml と同じ場所にある ./data に保存されます。

git clone https://github.com/To0wnn/knowledge && cd knowledge
mkdir data && echo "KNOWLEDGE_UI_PASSWORD=<a long password>" > .env
docker compose up -d

http://localhost:8766/ui を開き、パスワードでサインインして、管理者ページでデバイストークンを作成します。メモは data/memory（MEMORY.md インデックス付きのメモ）、data/docs、data/shared（すべてのエージェントと共有する CLAUDE.md、運用ルール、スキル）に保存されます。管理者ページでは、プロジェクトをさらに作成できます。他のマシンから接続する場合は、.env の KNOWLEDGE_ALLOWED_HOSTS にそのマシンの host:port を追加します（KNOWLEDGE_PORT を変更する場合も同様です）。また、HTTPS 対応のリバースプロキシを前段に配置してください。平文の HTTP では、パスワードとトークンがネットワーク上で読み取れる状態で送信されます。コンテナーは uid 1000 で実行されます。./data の所有者が別のユーザーの場合は、.env で KNOWLEDGE_UID と KNOWLEDGE_GID を設定してください。イメージ（埋め込みモデル込みで約 1.5 GB）はリリースごとにビルドされます。また、MCP レジストリには io.github.To0wnn/knowledge として登録されています。

.env の設定（すべて任意）：KNOWLEDGE_PUBLIC_URL（エージェントの指示に記載する、ユーザーがアクセスするアドレス）、KNOWLEDGE_LANGUAGE（en または nl。メモのセクションは ## Status と ## Decisions、または ## Stand と ## Keuzes です。どちらも常に受け付けます）、TZ。各エージェントに適用される運用ルールは、data/shared に独自の house_rules.md を配置するまでは default_house_rules.md です。

要件：Docker と約 2 GB の RAM（埋め込みモデルは 1.2 GB で、イメージに含まれているため、実行時にダウンロードされることはありません）。

元のインストール方法では動作が異なります（server/compose.yaml：エージェントを実行するマシンから NFS 経由でメモを共有し、デプロイ時にダウンタイムなしで切り替え、KNOWLEDGE_BUILTIN_PROJECTS=homelab,anpitek,trade を設定）。local.env.example を local.env にコピーして、ボリュームをフォルダーに合わせて設定し、./deploy.sh を実行します。このスクリプトはテストを実行し、server/ を Docker ホストにコピーしてビルドと切り替えを行い、/health の応答を待ちます。

クライアントを接続する

サーバーのヘルプページ（/ui/help）に、クライアントと OS ごとの正確な手順が記載されています。概要は次のとおりです。

curl -fsSL https://raw.githubusercontent.com/To0wnn/knowledge/main/install.sh | sh   # Linux, macOS

irm https://raw.githubusercontent.com/To0wnn/knowledge/main/install.ps1 | iex        # Windows

どちらにも git と Python 3.9 以降が必要です（macOS 標準の python3 は 3.9 です）。スクリプトは ~/knowledge（git チェックアウト。履歴が書き換えられた場合も復元されます）に保存し、clients/knowledge-agent.py setup を実行します。毎回同じ手順です。初回は Claude Code、Codex、agy を見つけ、それぞれについて y/n を尋ねます。2 回目以降はプラグインがあるエージェントを更新し、プラグインがない状態で見つかったエージェントについてのみ y/n を尋ねます。また、サーバーが保存済みのトークンを拒否した場合にのみ、トークンを尋ねます。

install claude（または codex、agy）を実行すると、どのエージェントを使うか尋ねずに 1 つのエージェントをセットアップします。install はサーバーのアドレスを尋ねます（1 回だけ使う場合は KNOWLEDGE_URL を設定します。例：KNOWLEDGE_URL=http://localhost:8766）。インストーラーにデフォルト値はないため、指定していないサーバーにトークンが送られることはありません。 応答したアドレスは、すべてのエージェントのフック用に ~/.config/knowledge/url に保存され、Claude プラグインの「Knowledge server URL」オプションにも設定されます。そのため、以降のセッションや update では、ほかに何もする必要はありません。

トークンを一度だけ尋ね、サーバーで確認してから、キーリングに保存し、プラグインをインストールします。プラグインはすべてのエージェントで自動的に最新の状態を保ち、セッション開始時にその旨を一度通知します。Claude Code ではマーケットプレイスの自動更新を有効にします（/plugin > Marketplaces で無効化できます）。Codex と agy にはプラグインの自動更新機能がないため、プラグインは 1 日に最大 1 回 GitHub を確認し、エージェント独自の CLI で自ら更新します（プラグインなしのセットアップでは、git チェックアウトを GitHub の main に合わせます。内容に変更がなければ履歴が書き換えられた場合も合わせたうえで、セットアップを再実行します。knowledge-agent.py update でも同じことを手動で行えます）。 無効化するには、KNOWLEDGE_AUTO_UPDATE=0 を設定します。新しいバージョンは次回の起動時に読み込まれます。各セッションの開始時にプラグインのバージョンが通知されます。管理ページではデバイスとエージェントごとに確認でき、2 日経っても最新バージョンより古いデバイスには、手動での更新方法が案内されます（lint では plugin_behind として表示されます）。

プロジェクトフォルダーをプロジェクトに一度だけ紐付けます。エージェントに依頼すると（スキル knowledge-init）、フォルダーのルートにプロジェクト名を記した .knowledge-project ファイルが作成されます。そのフォルダーで開始するすべてのセッションに、そのプロジェクトが適用されます。紐付けられた git worktree（Codex と agy はチャットごとに 1 つ作成します）は、メインのチェックアウトとして扱われます。プロジェクトは同じで、ドキュメントはメインのチェックアウトからのみミラーされます（フォルダーがソースです。次回の同期で変更が取り消されるため、UI と同様に knowledge_write／edit／delete はミラーへの変更を拒否します）。また、セッションには別のチェックアウトで実行されていることが伝えられます。Windows では、agy に PATH 上の python3 コマンドが必要です（python.org のインストールマネージャーまたは Microsoft Store から入手した Python に含まれています）。これがない場合、セットアップではプラグインなしで agy が設定されます。Windows で Codex と agy のフックは、plugin/python3.cmd 経由で Python を起動します。py ランチャー、PATH 上の Python、レジストリにあるインストール（PEP 514）の順に、それぞれをテスト実行してから使用するため、Microsoft Store のスタブはスキップされ、py も PATH 上の Python もない python.org のインストールでも動作します。

プラグインには開発用スキルも含まれており、どのエージェントでも同じものを使えます。plan-change、debug-root-cause、verify-done、 review-diff、project-setup、efficiency-pass、knowledge-init、verified-goal（チェックコマンドでタスクの完了が証明されるまで作業を続けます。上限を設け、各エージェント向けの無人ループの手順も用意します）、および fan-out-verify（広範な作業をサブエージェントに分割し、各指摘を新たな検証担当に反証させ、反証されなかった内容だけを報告します）。

開発

• server/graph.py、server/lint.py、server/vectors.py には __main__ の下に自己チェックがあり、server/test_server.py でサーバーをテストします。deploy.sh は最初にこれらをすべて実行します。
• tests/clients_e2e.py は、実際のサーバーに対してクライアント側を実行します。対象はプラグインフック、インストーラー、Codex 独自の MCP サーバー起動、オフラインコピー、スキルの同期です。CI では、すべてのプッシュ時に Windows、macOS、Linux で実行します （.github/workflows/clients.yml）。
• tests/ui_smoke.py は Playwright で Web UI をチェックします。
• プラグインを変更した場合は、plugin/.claude-plugin/plugin.json と plugin/.codex-plugin/plugin.json のバージョンを上げる必要があります（テストで両者が一致するか確認します）。そうしないと、インストール済みのコピーが更新されません。

ブラウザーライブラリはライセンスとともに server/static/vendor/ に同梱されています（force-graph、marked、DOMPurify）。CDN は使用しません。

ライセンス

MIT。詳しくは LICENSE を参照してください。