Exomem

exomem

MCP 対応エージェント向けの、情報源、証拠、履歴、レビューを備えた永続的なメモリです。

exomem は、所有する Markdown／Obsidian の Vault を、Codex、Claude Code、Cursor、チャットボット、CLI エージェント、および MCP ツールを呼び出せるあらゆるクライアント向けのローカルなナレッジ基盤に変えます。ファイルはプレーンな形式のまま、ローカルに保存され、移植可能で、サーバー外からも編集できます。

agent -> MCP tools -> exomem -> your Markdown / Obsidian vault

30 秒で動作を確認

uvx exomem demo

インストールも設定も不要で、自分の Vault も必要ありません。コマンドを 1 つ実行するだけです。

exomem demo — bundled sample vault, keyword mode, fully local
vault: /tmp/exomem-demo-XXXXXX

1. doctor: PASS (0.8s)
2. find "retrieval": PASS (0.1s)
   - Knowledge Base/Sources/Sessions/2026-06-30-sample-session.md
   - Knowledge Base/Notes/Insights/retrieval-needs-owned-files.md
3. get retrieval insight: PASS (0.0s)
   - title: Retrieval needs owned files
   - type: insight
   - excerpt: Local-first knowledge tools should retrieve from files the user already owns.
4. audit: PASS (0.0s)

demo PASS — total 1.0s. This is your proof: agents search files you own.
Next: connect your own vault with `exomem setup`

パッケージに同梱されているサンプル Vault に対して、完全ローカルかつ読み取り専用で実行されます。実行後もコピーをディスクに残して Obsidian で開くには、--keep を追加してください。

1 行でインストール

Mac／Linux — Terminal に貼り付けます。

curl -fsSL https://raw.githubusercontent.com/Artexis10/exomem/main/scripts/install.sh | sh

Windows — PowerShell に貼り付けます。

irm https://raw.githubusercontent.com/Artexis10/exomem/main/scripts/install.ps1 | iex

どちらのコマンドも uv と exomem をインストールし、exomem setup の手順を案内します。このセットアップでは、マシン上のすべてのエージェントクライアントを設定し、Claude Code と Codex の両方に MCP サーバー、10 個すべてのスキル、キャプチャ／取得フックを導入します。

後から再実行しても安全です。完了済みの作業はスキップされます。対話形式での入力ができない場合（たとえば別のスクリプトから実行する場合）は、推測せず、次に実行する正確なコマンドを表示します。各手順を自分で実行したい場合は、以下または QUICKSTART.md の詳しい手動セットアップ手順を参照してください。

Claude Code：プラグインとしてインストール

プラグインにはスキルとフックが含まれています。MCP エントリは共有 HTTP URL を任意で指定できます。各 Claude Code セッションで完全な stdio サーバーを自動起動することは意図的に行いません。

/plugin marketplace add Artexis10/exomem
/plugin install exomem@exomem

次に、利用方法を選択します。スマートフォンやホステッドアクセス向けに Exomem をすでにサービスとして実行している場合は、認証済みのコアを再利用してください。

exomem setup --vault "/path/to/vault" --mcp-url https://<host>/mcp

ローカルのみで利用する場合は、exomem setup --vault "/path/to/vault" --stdio を実行します。stdio は意図的に明示指定が必要です。各クライアントセッションがそれぞれのプロセスを所有し、独自の埋め込みランタイムを読み込めるためです。古いプラグインから更新する場合は、/plugin update exomem@exomem を実行し、その後 /reload-plugins を実行するか Claude Code を再起動してから、セットアップを再実行してください。

claude.ai と ChatGPT

どちらのプラットフォームもスキルをプログラムからインストールできないため、手動でアップロードする必要があります。アーカイブを作成し、クライアントの設定からアップロードしてください。

exomem package-skills          # writes dist/skills/*.zip (all ten)

クライアントをコネクターとしてサーバーに接続します（docs/remote-quickstart.md を参照）。どちらのプラットフォームにもフックシステムがないため、そこでのキャプチャは自動ではなく、スキルによって行われます。

5 分でセットアップ

uv tool install exomem   # or: pip install exomem
exomem setup --vault "/path/to/your/Obsidian"

1 行のインストーラーを再実行すると、既存の uv-tool インストールがアップグレードされます。古い exomem コマンドが PATH に残ることはありません。exomem --version --json はモデルを使わない来歴チェックなので、より完全なマネージドサービスと組み合わせる、意図的に軽量化された CLI でも動作します。

1 つのコマンドでローカルセットアップ全体を実行します。ウィザードが Vault をスキャンして既存の内容を表示し、Knowledge Base/ を初期化し、doctor の事前チェックを実行し、検出したすべてのクライアント（Claude Code と Codex）にサーバーを登録して、それぞれにスキルをインストールします。

cwd の .env またはプロセス環境に EXOMEM_BASE_URL が含まれている場合、セットアップは正規の /mcp エンドポイントを Claude Code と Codex に登録し、既存のサービスを共有します。それ以外の場合は、明示的なローカル stdio フォールバックを使用します。サービスを直接選ぶには --mcp-url、ローカル stdio を強制するには --stdio、既存の手動ルートを意図的に置き換えるには --replace-client-registration を使用してください。ネイティブクライアントが OAuth を処理するため、セットアップでベアラートークンが保存されることはありません。

作成元が exomem ではない設定ファイルは、ユーザーのものとして扱われます。上書きせずにマージし、最初にファイルをバックアップして、差分を表示します。 すでにメモが詰まった Vault をお持ちですか？それが一般的なケースです。adopt を使うと、既存の内容をスキャンして読み取り専用でレポートし、推奨されるナレッジパックと、安全なコピー／コンパイル計画の次のアクションを提示します。Exomem が書き込むのは常に Knowledge Base/ の下だけです。選択した内容を明示的にコピーまたはコンパイルしない限り、既存ファイルには手を加えません。デイリーノート用 Vault を含む、すべての仕様については QUICKSTART.md § Already have a vault full of notes? をご覧ください。setup は安全に再実行でき、完了済みの手順には [skipped] と表示されます。非対話型の場合： exomem setup --yes --vault "/path" --lean

個々の手順（exomem init / doctor / install-skill / install-hook、および claude mcp add）も、手動で行う方法として引き続き利用できます。詳しくは QUICKSTART.mdをご覧ください。

スキルは Claude Code の名前 exomem でインストールされます。コネクターと同じ名前なので、スキル、サーバー、ツールがすべて一つの製品としてまとまって見えます。スキルは Claude Code での利用を推奨します。 サーバーが Claude にツールを提供し、スキルがそれらを使う方法を教えます。フックは Claude Code と Codex 向けのローカルクライアントの信頼性を高める補助機能です。回答前の読み取り側リマインダー、自然な区切りでの書き込み側リマインダー、そしてコンパクション前後で共有するローカルの継続チェックポイントを提供します。チェックポイントに保存されるのは、範囲を限定した構造的な証拠（リポジトリの状態、成果物のハッシュ／件数、トランスクリプトの出所を示すハッシュ）だけです。会話、ツール、要約、成果物の内容は保存されません。MCP 接続や Exomem の認証情報も必要ありません。 読み取り側フックは、continue、merge it、are you done? など、明らかに制御やステータス確認を目的とするプロンプトでは動作を抑制します。また、オプトインでこのリマインダーを実際に取得した KB の内容に置き換えることもできます（EXOMEM_RETRIEVE_INJECT=1。従来の KB_RETRIEVE_INJECT という名前も引き続き使用できます）。あるいは EXOMEM_RETRIEVE_INJECT=working_set を設定すると、データヘッダー付きのコンパイル済み recall_context パケットに置き換えます。このパケットのサイズは EXOMEM_RETRIEVE_INJECT_MAX_CHARS（デフォルトは 4,000）で制限されます。Codex の場合は exomem install-hook --client codex、Claude Code の場合は exomem install-hook を実行してください。詳しくは QUICKSTART.md § 7 をご覧ください。どちらのクライアントも、手動または自動の PreCompact でチェックポイントを作成し、SessionStart(compact|resume) で再注入します。Claude では SessionEnd でもチェックポイントを作成します。固定バージョンの Codex CLI 0.144.3 には SessionEnd フックがないため、Exomem は存在しないフックを追加しません。 ほかの MCP クライアントでもサーバーを利用できます。Skills に対応していない場合は、セッション開始時に一度 bootstrap() を呼び出すよう設定してください。MCP を通じて同じ簡潔な運用仕様が返され、検索するタイミング、保存するタイミング、ワークフロースキルの見つけ方、アップロードのガイダンス、パフォーマンスプロファイルが含まれます。また、作成の流れも説明します。まず検索し、型付きノートの下書きを作成し、suggest_links を実行し、適切なツールで書き込み、警告や提案を確認してから、パスを報告します。

この動作をどの程度積極的に行うかは調整できます。4 段階の表示レベル（off / light / balanced / maximal）があり、exomem prominence <level> で設定するか、Web アシスタントのカスタム指示に貼り付けて設定できます。フックを備えたクライアントのデフォルトは balanced、Web およびホスト型の環境では maximal です。これらの環境では、ターン間にチェックを再設定する手段がないためです。各レベルとコピーして貼り付けられるブロックについては、docs/prominence.mdをご覧ください。

クライアントごとのアシスタント指示については、 docs/ai-assistant-guide.mdをご覧ください。Exomem とチャット製品に組み込まれたメモリの境界については、 docs/vs-built-in-memory.mdをご覧ください。

ローカル環境のセットアップ手順はQUICKSTART.mdにあります。リモート／モバイル環境のセットアップ手順は docs/remote-quickstart.mdおよび docs/deployment.mdをご覧ください。 リモート OAuth では、GitHub を一度使って設定済みのログイン情報と変更不可能なユーザー ID を確認した後、Exomem が所有する永続セッションを発行します。運用担当者は exomem auth sessions、exomem auth revoke <session-id>、exomem auth revoke --all でこれらのセッションを確認および失効できます。セッション管理が MCP ツールになることはありません。

製品モデルは意図的にシンプルです。組み込みの AI メモリは好みやルーティングを記憶し、Exomem はソース、証拠、履歴、判断、記録、レビューを備えた、永続的でガバナンスの管理されたナレッジを保存します。全体像については docs/product-model.md、人が所有する長期的な記録については docs/records.md、対話型ターミナル UI（exomem tui、オプションの tui エクストラ）については docs/tui.md、パッケージに含まれるブラウザレビューのワークフローについては docs/review-studio.md、日々のレビューと関係性の修復については docs/epistemic-inbox.md、パックと管理の詳細については docs/knowledge-packs.md、名前付きエージェントワークフローについては docs/workflow-skills.md を参照してください。

開発する場合、またはパッケージをインストールせずにチェックアウトからサンプルの Vault を実行する場合：

git clone https://github.com/Artexis10/exomem.git
cd exomem
uv sync
uv run exomem demo

エージェントを接続する

codex mcp add exomem --env EXOMEM_VAULT_PATH="/path/to/vault" -- exomem --transport stdio

exomem install-hook --client codex

exomem install-hook --check

[mcp_servers.exomem]
command = "exomem"
args = ["--transport", "stdio"]
env = { EXOMEM_VAULT_PATH = "/path/to/vault" }

{"mcpServers": {"exomem": {"command": "exomem", "args": ["--transport", "stdio"], "env": {"EXOMEM_VAULT_PATH": "/path/to/vault"}}}}

claude mcp add exomem -- docker run -i --rm -v "/path/to/vault:/vault" -e EXOMEM_VAULT_PATH=/vault ghcr.io/artexis10/exomem:latest --transport stdio

初回起動時に検索モデルがバックグラウンドでダウンロードされます。すぐに find を使い始められ、キーワードによるランキングで検索できます。モデルのダウンロードが完了すると、自動的にセマンティック検索に切り替わります。事前にダウンロードしておくには exomem warm を実行してください。

リソースモード

Exomem はデフォルトで CPU 優先のため、アイドル状態のサーバーが GPU メモリをひそかに占有することはありません。コードを編集せずに、マシンへの負荷を調整できます。

exomem mode quiet          # low-resource: no heavy warm-up, evict caches, defer semantic reindex
exomem mode normal         # default: CPU steady-state, warm CPU caches allowed
exomem mode performance    # explicit opt-in for GPU-capable bulk/model work
exomem status --resources --json

ゲームなど、フォアグラウンドで負荷の高い作業をする前に quiet を使用してください。キーワード／BM25 による鮮度、ファイル変更の鮮度、被リンク、リゾルバーの状態は常に最新に保たれます。負荷の高いセマンティック／CLIP の再インデックス処理は延期でき、その状況はリソースのステータスに表示されます。延期したセマンティック処理を修復するには、後で exomem index または kb reconcile を実行してください。

自動で quiet に切り替える機能は任意です。手動で quiet を選択した場合、EXOMEM_MODE でモードを固定した場合、または EXOMEM_AUTO_QUIET を無効にした場合、監視機能は GPU の負荷を確認しません。自動 quiet は、以前のモードに復帰できるよう、引き続き負荷を監視します。

影響を受ける WSL／NVIDIA システムでは、Linux の nvidia-smi プロセスを繰り返し起動すると、Windows ドライバーのカーネルメモリが増加し、フォアグラウンドの作業に支障が出ることがあります。 Microsoft WSL issue #12756 に再現方法が記録されています。古いバージョンの Exomem では、EXOMEM_AUTO_QUIET=0 を設定したサービスは、そのサービスの再起動後に監視機能を停止します。 CUDA_VISIBLE_DEVICES が空の場合も、GPU 処理と GPU の空き容量の確認が無効になります。 これらの設定に Windows の再起動は必要ありませんが、既存のドライバーの状態は残る場合があります。

できること

• すでにお持ちの保管庫を検索します。 Markdown ファイルはそのままの場所に保持され、exomem が独自のノートストアにコピーを取り込むことはありません。
• 整理されていない保管庫を安全に取り込みます。 adopt は読み取り専用のレポートから始まり、コピーとコンパイル計画のオプションを明示的に指定できるため、選択するまでは元のファイルがアーカイブとして保持されます。
• テキストとメディアを横断して検索します。 Markdown、PDF、Office ドキュメント、画像、スクリーンショット、音声、動画を、ローカルで抽出して検索可能にできます。
• 情報源と結論を分けて保持します。 生のキャプチャ、コンパイル済みノート、エンティティ、エビデンス、置き換えられた結論は、種類ごとにフォルダーに保存されます。
• 確認が必要な作業を提示します。 監査キューや確認キューに、未処理の情報源、古くなったノート、リンク切れ、確認する価値のある関連性の高い主張を表示できます。
• 評価は行わず、測定します。 サーバーが行うのは、検索、抽出、ランキング、埋め込み、ファイル書き込み、グラフのチェックといった決定論的な処理です。推論はクライアントのモデルが担います。

選ぶ理由

多くの AI ノートツールでは、専用アプリに移行するか、ファイルを独自のストアに取り込む必要があります。exomem はその逆で、エージェントがあなたの保管庫を利用します。

ある時点での詳しい比較については、 docs/comparison-engraph.md をご覧ください。Basic Memory との再現可能なグラフのみの比較は、 docs/comparison-basic-memory-graph.md にあります。 チャット製品に内蔵されたメモリ機能との実用上の違いについては、 docs/vs-built-in-memory.md をご覧ください。

検索品質と速度を測定済みです。 検索品質は、主張ではなく再現可能なゴールデンセット評価ハーネスで評価され、レイテンシーはコーパス規模でレーンごとに測定されています。ハイブリッドな find() は、50,000 件のノートを対象に、エンドツーエンドで 1 秒未満で実行されます（基準となるデスクトップでは 864 ms、ホットキャッシュなし）。キーワード／BM25 レーンは、FTS5 のサイドカーインデックスからミリ秒単位で処理されます。FTS5 は標準ライブラリの SQLite に組み込まれているため、軽量インストールでも動作します。方法と測定値については docs/benchmarks.md をご覧ください。

シンプルな入り口

エージェントは、通常のユーザーリクエストにはまずシンプルなアクションで対応し、その後で下位の型付きツールを使用してください。

コアツール

exomemは、一般的なナレッジベース作業向けに型付きMCPツールを提供します。

Tier 2ツールでは、ディレクトリの一覧表示、ファイルの作成、ページの移動、ファイルのゴミ箱への移動、ゴミ箱からの復元など、ガバナンス管理とファイルシステムへの直接アクセスを提供します。ツールの種類を少なくしたい場合は、 EXOMEM_DISABLE_TIER2=1を設定してください。

書き込みのたびに、Knowledge Base/log.mdに永続的な履歴が記録されます。サービス呼び出しもlogs/exomem.logに記録されます。

1つの操作、3つの入り口

各操作は一度だけ宣言され、次の方法で利用できます。

• エージェント向けのMCP。
• ターミナルとスクリプト向けのCLI。
• EXOMEM_REST_API_KEYが設定されている場合の、個人向けHTTP連携用REST。

例：

kb find "project handoff" --mode keyword
kb find "stale decision" --json
kb get "Notes/Insights/retrieval-needs-owned-files" --json
kb note --note-type insight --title "Agents need durable context" \
  --content "# Agents need durable context"

curl -s -X POST http://127.0.0.1:8765/api/find \
  -H "Authorization: Bearer $EXOMEM_REST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "project handoff", "mode": "keyword"}'

CLIとRESTは同じJSONエンベロープを共有します。

{"success": true, "data": []}

マルチモーダル機能を標準搭載し、作業中のみ常駐

ネイティブのリリースサービスコマンドでは、standard プロファイルがインストールされます。これには、ローカル埋め込み、PDF／Office ドキュメント、OCR バインディング、ASR、CLIP が含まれます。重いモデルはサービスの起動時には読み込まれません。メディアジョブは永続キューに入り、使い捨ての子プロセス1つで順番に実行されます。子プロセスは5分間アイドル状態が続くと終了するため、RAM と MPS／MLX／CUDA の状態がホストに戻ります。

手動インストールまたはソースからのインストールでは、同じ機能を直接選択できます。

uv sync --extra embeddings
uv sync --extra media

• embeddings：ローカルのテキスト埋め込みと CLIP による画像検索。
• media：画像の OCR、PDF 抽出、Office ドキュメント抽出、音声／動画向けの faster-whisper ASR。

CSV、TSV、JSON のエビデンスアップロードには、検索と正確なクエリに対応するデータセットソースカードが付与されます。YAML、JSONL、XML、TOML のエクスポートには、長さを制限したテキストプレビューが付与されます。これらの処理経路にオプションの追加機能は必要ありません。制限とガバナンスの動作については、ソース形式をご覧ください。

制約のあるマシンでは、引き続き lean と hybrid を使用できます。生成画像のキャプション付けと話者ダイアライゼーションは、高度なオプトイン機能であり、標準のマルチモーダル処理経路では必須ではありません。

システムツール：画像 OCR には Tesseract が必要です。Windows の場合：

winget install --id UB-Mannheim.TesseractOCR -e

GPU アクセラレーションは有用ですが、必須ではありません。定常状態で使用する torch モデルは、normal と quiet ではデフォルトで CPU を使用します。performance は、対応する NVIDIA CUDA または Apple Silicon MPS／Metal の処理経路を明示的に有効にするための設定です。CUDA、Blackwell、Apple Silicon、ダイアライゼーション、リモートサービスの詳細については、docs/deployment.mdをご覧ください。

設定

サーバーは環境変数または .env ファイルを読み込みます。主な変数は次のとおりです。

EXOMEM_CLAIM_NLI_MODEL は廃止されています。モデルの識別情報はリポジトリ内のピンレジストリからのみ取得されます。この変数に値を残しても何も選択されず、exomem doctor によって無視されたと報告されます。

同梱されているピンは、多言語対応の MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7 チェックポイントの、上流の特定リビジョンです。採用判定用フィクスチャでは、英語、ドイツ語、フランス語、エストニア語、および英語／エストニア語の混在例を確認します。これはそれらの例に関する限定的な根拠であり、モデルカードに記載されたすべての言語で同等の品質を保証するものではありません。ラベルはNLI関係を表し、contradict、duplicate、refine、neutral のいずれかです。neutral には、無関係な組み合わせ、両立する組み合わせ、不確かな組み合わせが含まれます。「無関係であると証明された」という意味ではありません。

劣化モード

オプションのティアはデフォルトでは存在せず、代替手段に置き換わるのではなく、何も行わない状態になります。各ティアで「存在しない」とは、次の状態を指します。

レガシーの EXOMEM_* 名（プロジェクトの以前の作業名 exomem に由来）も引き続き使用できます。起動時にそれぞれ対応する EXOMEM_* 名へ昇格され、競合する場合は明示的に設定された EXOMEM_* の値が優先されます。import exomem と python -m exomem も、非推奨のエイリアスとして引き続き使用できます。

リモート専用の変数とデプロイに関する詳細は、docs/deployment.md を参照してください。

プロジェクトのステータス

exomem は PyPI でパッケージとして公開されており、バージョン管理に Release Please を使用し、docs/release.md に記載された軽量な SemVer ポリシーに従っています。公開 CLI エントリーポイントは exomem です。kb は、ナレッジベース操作で日常的に使う短縮エイリアスです。

ライセンス

AGPL-3.0-or-later。LICENSE を参照してください。