Everkeep

Everkeep

AI に何度も同じ説明をするのはやめましょう。

Everkeep は、メモ、決定事項、プロジェクトを自分のサーバー上の1つのフォルダーにまとめます。チャットが始まると AI アシスタントがその内容を読み取り、取り組んだことを書き留めるため、翌日の会話は今日の続きから始められます。何を変更できるかは自分で決められます。許可していないものを削除したり上書きしたりすることはありません。

Claude およびあらゆる MCP クライアントで動作 · Linux、Docker、Home Assistant で実行可能

ドキュメントも保存できます

契約書、請求書、マニュアル、価格表、エクスポートしたレポートを、PDF、Word、Excel、PowerPoint、メールのままフォルダーに入れられます。AI はそれらをテキストとして読み取り、まとめて検索し、回答が見つかった場所を教えてくれます。「支払い期限が30日の契約書はどれ？」と尋ねると、ファイルとページを返します。チャットのたびにファイルをアップロードしたり、コピー＆ペーストしたりする必要はありません。ファイルの新しいバージョンは、次に必要になったときに読み取られます。スキャンされたページは画像として確認します。

ファイルは、ほかのフォルダーと同じように通常のコピー操作でフォルダーに入れられます：ファイルの追加方法をご覧ください。

クイックスタート

Docker を使って自分のコンピューターで Everkeep を起動し、Claude を接続します。所要時間は約 10 分で、プログラミングの知識は不要です。

1. Docker をインストールします。 Windows または macOS では、Docker Desktop をインストールして起動し、Docker が実行中と表示されるまで待ちます。Linux では、Docker Engine をインストールします。

2. Everkeep を起動します。 ターミナルを開き（Windows の場合は PowerShell、macOS の場合はターミナル）、お使いのシステムに対応する 2 行を貼り付けます。1 行目でホームフォルダーに everkeep-notes フォルダーを作成します。このフォルダーにノートが保存されます。2 行目で Everkeep をダウンロードし、バックグラウンドで起動します。再起動後も自動的に起動します。

Windows（PowerShell）：

mkdir $HOME\everkeep-notes
docker run -d --name everkeep --restart unless-stopped -p 127.0.0.1:3100:3100 -v "$HOME\everkeep-notes:/vault" -v everkeep-data:/data ghcr.io/st412m/everkeep:1.0.0

macOS または Linux：

mkdir -p ~/everkeep-notes
docker run -d --name everkeep --restart unless-stopped -p 127.0.0.1:3100:3100 -v "$HOME/everkeep-notes:/vault" -v everkeep-data:/data ghcr.io/st412m/everkeep:1.0.0

Linux では、フォルダーにユーザー ID 1000 の書き込み権限が必要です。コマンド id -u の出力が別の数値の場合は、代わりに Docker：フォルダーの所有者 の手順に従ってください。

3. ノートを保護します。 同じターミナルで、もう 1 行実行します。

docker exec everkeep everkeep policy set . --mode rev --trash

以降、Claude はフォルダーに新しいファイルを作成できますが、既存のファイルを変更するには、まずそのファイルを読み込む必要があります。そのため、Claude が内容を確認していないファイルを上書きすることはありません。ファイルは削除されません。Claude が破棄したファイルは everkeep-notes 内の .vault-trash フォルダーに入るので、そこから取り戻せます。

4. トークンを取得します。 Everkeep は初回起動時にシークレットトークンを作成しています。次のコマンドで表示します。

docker exec everkeep everkeep token

2 行が表示されます。1 行目は claude.ai 用のシークレットパス、2 行目はその他のクライアント用のヘッダーです。

/private_<token>/mcp
Authorization: Bearer <token>

どちらもパスワードと同じように扱ってください。これらを持つ人は、ノートの読み取りや変更ができます。

5. Claude を接続します。

• 同じコンピューター上の Claude Code：

  claude mcp add --transport http everkeep http://127.0.0.1:3100/mcp --header "Authorization: Bearer <token>"
  

• 同じコンピューター上の Claude Desktop： Claude Desktop の設定ブロックを設定ファイルに追加し、再起動します。

• ブラウザーの claude.ai、または Claude アプリ： インターネット経由で接続するため、Everkeep には一般公開されている HTTPS アドレスが必要です。リモートアクセス では、無料で利用できる 2 つの方法を手順に沿って説明しています。その後、claude.ai → Settings → Connectors → Add custom connector で、https://<your public address>/private_<token>/mcp を貼り付けます。

6. 試してみます。

• Claude に次のように依頼します：「Everkeep を使って、現在のプロジェクトについてあなたが知っていることをまとめた about-me.md ファイルを作成して。」 ファイルは everkeep-notes フォルダーに表示されます。
• フォルダーを開きます。Windows では、同じ PowerShell で explorer $HOME\everkeep-notes と入力します（または、「This PC」→「Users」→自分の名前→everkeep-notes の順に開きます）。macOS では、ターミナルで open ~/everkeep-notes と入力します（または、Finder でホームフォルダーを開きます）。Linux では、ファイルマネージャーでホームフォルダーを開きます。
• 契約書、請求書、その他の PDF や Word ファイルを、他のフォルダーと同じように、ドラッグするかコピーして貼り付けてフォルダーに入れます。Everkeep はすぐに認識するため、再起動は不要です。フォルダー内にフォルダーを作成するのも便利です。例：contracts/、projects/…。
• Claude に次のように依頼します：「Everkeep を使って、ノートにある契約書の支払い条件を確認して。ページ番号も教えて。」

すべてのチャットの開始時に Claude にノートを読ませるには、Settings → Account → Instructions for Claude に次のような行を追加するか、プロジェクトの指示に追加します：「チャットの開始時に、Everkeep を使って /vault/about-me.md を読んでください。」 Docker 内では、フォルダーは /vault です。

フォルダーのルールを変更する方法については、書き込みポリシー を参照してください。

概要

Everkeep は MCP サーバーです。MCP は、Claude などの AI クライアントが他のマシン上のツールを呼び出すための仕組みです。Everkeep のツールは、vault と呼ばれる 1 つのディレクトリツリー上で動作し、ファイルの読み取り、検索、編集、移動、破棄、ドキュメントや PDF の読み取り、SQLite データベースの読み取り専用でのクエリを行います。vault の外部にはアクセスできません。

アシスタントが変更できる範囲は、ディレクトリごとに 書き込みポリシー で設定します。ディレクトリを読み取り専用にする、ファイルの現在のバージョンを読み取った人だけが編集できるようにする、新規ファイルの追加だけを許可する、または制限を設けない、といった設定が可能です。削除機能はありません。破棄すると、ファイルはそのゾーンのゴミ箱ディレクトリに移動します。アシスタントはポリシーを変更できません。サーバー上で設定してください。

1 つのプロセスとして動作し、claude.ai などのリモートクライアントには HTTP で、Claude Desktop などのローカルクライアントには stdio で接続します。

動作イメージ

アシスタントがディレクトリを一覧表示します。最初の行に、そのディレクトリで許可されている操作が示されます。

Policy: overwrite=rev, trash=.vault-trash, auto-purge after 30 d — own marker (/vault/wiki/.vault-policy)

[FILE] .vault-policy
[DIR] .vault-trash
[FILE] decisions.md
[FILE] todo.md

todo.md を読み取らずに上書きしようとすると、拒否されます。

Error: Refused — policy "overwrite: rev": changing an existing file requires its current rev, which is 5db20d56. Nothing was written. Repeat the call with rev: "5db20d56".

検索して行番号とファイルの rev を取得し、1 行を編集します。

/vault/wiki/todo.md · rev 5db20d56 · 212 lines
  148: - [ ] Check backup-rotation settings on the NAS

— 1 match(es) in 1 file(s) · scanned 37/37 files, 190 KB, 12 ms

要件

Docker	Docker Desktop（Windows、macOS）または Docker Engine（Linux）。amd64 および arm64（Raspberry Pi 4/5）用のイメージ
Docker を使わない Linux	Node.js ≥ 22.17、poppler-utils（pdfinfo、pdftoppm）、sqlite3
Home Assistant	OS または Supervised。ha-filesystem-mcp アプリ経由
ディスク	Docker イメージは約 340 MB、依存関係を含む npm パッケージは約 48 MB
claude.ai を使う場合	パブリック HTTPS アドレス。リモートアクセスを参照してください

インストール

Docker

イメージ ghcr.io/st412m/everkeep は、ユーザー ID 1000 としてポート 3100 で everkeep serve を実行します。vault は /vault に、トークンやドキュメントキャッシュなどの状態データは専用ボリューム /data に保存されます。クイックスタートでは docker run を紹介しています。compose.example.yaml でも同じことを Docker Compose で行えます。フォルダーの所有権、更新、自分でイメージをビルドする方法については、インストールを参照してください。

Docker を使わない Linux

パッケージマネージャーで poppler-utils と sqlite3 をインストールしてから、npx で実行します。

npx --yes --package=everkeep everkeep serve --vault /home/me/notes

初回起動時にトークンが一度だけ表示されます。everkeep token で再度確認できます。常時使える everkeep コマンドの設定、AVX を搭載していない CPU（一部の Celeron、Atom、Pentium モデル）への対応、systemd サービスの設定については、インストールを参照してください。Docker を使わない Windows と macOS はサポートされていません。

Home Assistant

ha-filesystem-mcp アプリをインストールしてください。vault を /media または /share に配置して Everkeep を実行し、サイドバーに Vault ポリシーページを追加します。

設定

設定はフラグ、環境変数、任意の JSON ファイル（EVERKEEP_CONFIG、または ~/.config/everkeep/config.json）から読み込まれます。まず確認しておきたい設定は次のとおりです。

設定	フラグ / 変数	デフォルト
vault	--vault、EVERKEEP_VAULT	なし。必須
host	--host	127.0.0.1
port	--port	3100
state_dir	EVERKEEP_STATE_DIR	~/.local/state/everkeep
token	--token-file、EVERKEEP_TOKEN	<state_dir>/token に生成

everkeep check-config を実行すると、有効な設定が表示され、Everkeep が必要とするツールが確認されます。すべてのキー、トークンのルール、リクエストログについては、設定を参照してください。

接続

• claude.ai、Claude Desktop コネクター、Claude アプリ： Settings → Connectors → Add custom connector で https://<your-host>/private_<token>/mcp を指定します。アドレスは公開 HTTPS である必要があります：リモートアクセス。

• Claude Code： Bearer ヘッダーを使った HTTP、または stdio で接続します：

  claude mcp add --transport stdio everkeep -- npx --yes --package=everkeep everkeep --vault /home/me/notes
  

• 公開アドレスがない場合の Claude Desktop： Docker 経由で stdio を使用して Everkeep に接続します。Claude Desktop を参照してください。

• Cursor およびその他のクライアント： URL http://127.0.0.1:3100/mcp（または HTTPS アドレス）とヘッダー Authorization: Bearer <token> を使用します。インストール方法を参照してください。

OAuth はありません。トークンだけが鍵です。パスが誤っていると空の 404 が返され、Bearer トークンが誤っていると 401 が返されます。

ツール

20 個のツールがあります。パラメーターと戻り値の形式については、ツールを参照してください。

読み取り

• read_text_file — ファイル全体、head／tail の行、または行数と rev を指定した offset／limit 範囲を読み取ります。ドキュメントは行番号付きで返します
• read_file — read_text_file の非推奨エイリアス
• read_multiple_files — 複数のファイル全体を 1 つの応答で返します
• read_media_file — 画像または音声を base64 で返します。PDF のページは JPEG で返します（パスの末尾に #N を付けます）
• read_pdf_text — PDF のテキストまたはページ範囲を読み取ります。read_text_file と同様に行番号付きで返します
• read_pdf_page — PDF の 1 ページを JPEG でレンダリングします

検索

• grep_files — ドキュメントを含むファイル内容を正規表現で検索し、パス、rev、行数、該当行を返します
• search_files — 名前でファイルとディレクトリを検索します

書き込み

• write_file — ファイルを作成または上書きします
• edit_file — リテラルの oldText を置換するか、rev で保護された行指定の編集を行います
• create_directory — ディレクトリとその親ディレクトリを作成します
• move_file — ファイルまたはディレクトリを移動または名前変更します。ゴミ箱からの復元にも使用できます
• trash_file — ファイルをそのゾーンのゴミ箱に移動します。削除機能はありません

一覧表示

• list_directory — ポリシー行の後に、1 つのディレクトリ内の項目を表示します
• list_directory_with_sizes — ファイルサイズ付きで項目を表示し、名前またはサイズで並べ替えます
• directory_tree — 2 階層までのツリー表示
• get_file_info — サイズ、日時、形式を表示します。テキストファイルの場合は行数と rev も表示します
• list_allowed_directories — Vault のルート

SQLite（読み取り専用）

• sqlite_schema — すべてのオブジェクトの DDL、ファイルプラグマ、必要に応じて行数を返します
• sqlite_query — 行数制限付きで、SELECT／WITH／VALUES／EXPLAIN ステートメントを 1 つ実行します

検索してから編集するワークフローについては検索と編集、SQLite については sqlite を参照してください。

書き込みポリシー

ポリシーがない場合、どのツールでも Vault 内の任意の場所に書き込めます。ポリシーはディレクトリ内に置く小さなファイル .vault-policy で、そのディレクトリとその配下すべてに適用されます。サーバー上で設定します：

everkeep policy set wiki --mode rev --trash --purge-days 30 --vault /home/me/notes
everkeep policy set raw --mode readonly --vault /home/me/notes

モード	効果
readonly	書き込み、編集、移動（内外への移動を含む）、破棄を禁止します
rev	新規ファイルは自由に作成できます。既存ファイルの変更、移動、破棄には現在の rev が必要です
never	新規ファイルのみ作成できます。既存ファイルは変更できません
free	チェックを行いません

Docker では、コンテナー内で同じコマンドを実行します：docker exec everkeep everkeep policy show。Home Assistant アプリでは、サイドバーの Vault policies ページを使用します。ゴミ箱、自動消去、および破損したマーカーの動作については、書き込みポリシーを参照してください。

ドキュメントと形式

read_text_file と grep_files は、PDF、Word、Excel、PowerPoint、OpenDocument、EPUB、FB2、RTF、HTML、メールファイルを、ページ、シート、スライドのマーカー付きの行番号付きテキストとして読み取ります。grep_files は一致箇所を報告します（L8 (p.1)、L2 (sheet Data)）。スキャンされたPDFにはテキストがないため、read_pdf_page で画像として読み取るページを回答で示します。ドキュメントは読み取り専用です。抽出されたテキストはボルトの外部にキャッシュされます。形式、制限、キャッシュについては、ドキュメントを参照してください。

制限事項

• Dockerを使用しない場合はLinuxのみです。 WindowsとmacOSではDockerで実行します。
• OAuthには対応していません。 パス内のトークンまたはBearerヘッダーのみがキーになります。
• 削除はできません。 trash_file はファイルをゴミ箱ディレクトリに移動します。ただし、ゴミ箱ディレクトリがあるゾーンに限ります。
• SQLiteは読み取り専用で、今後も変更されません。
• ドキュメントは読み取り専用で、スキャン画像はテキストとして認識されません（OCRなし）。
• ポリシーが制限するのはEverkeepのツールのみです。 フォルダーに書き込むそれ以外のもの（ユーザー自身、同期ジョブ、ファイル共有など）には適用されません。
• クライアントはツール一覧をキャッシュします。 ツールが変更される更新の後も、開いている会話には古い一覧が残ります。

トラブルシューティング

• ClaudeにEverkeepのツールが表示されません。 コンテナが実行中であること（docker ps）、URLまたはヘッダー内のトークンが最新であること（everkeep token）、またclaude.aiの場合はHTTPSアドレスに外部からアクセスできることを確認してください。
• 書き込みがすべてEACCESで失敗します。 ボルトのフォルダーに、Everkeepの実行ユーザー（DockerではユーザーID 1000）が書き込めません。
• 400 / 401 / 403 / 404 / 405 / 406。 401：Bearerトークンが間違っています。404：パスまたはパス内のトークンが間違っています。403：127.0.0.1でリッスンしているサーバーに対し、HostまたはOriginがローカルでもallowed_hosts内でもありません。405：POSTではありません。406：AcceptヘッダーにJSONもイベントストリームも指定されていません。400：JSONが不正、またはMCP-Protocol-Versionがサポートされていません。
• 書き込みがすべて拒否され、一覧に⚠ Policy: BROKEN MARKERと表示されます。 .vault-policyファイルが壊れており、そのゾーンがロックされています。everkeep policyを使用するか、手動で修正してください。

詳細：トラブルシューティング。

セキュリティ

• トークンはパスワードです。サーバーによって生成され、32文字以上で、ログに記録されることはありません。マシンの外部に公開するアドレスの前には、TLSを設定してください。
• シンボリックリンク経由や大文字と小文字を区別しないファイルシステム上も含め、すべてのパスはボルト内に制限されます。
• 127.0.0.1（Dockerを使用しない場合のデフォルト）では、HostまたはOriginがローカルでないリクエストは拒否されるため、ブラウザー内のウェブサイトからのアクセスを防止できます。
• トークンとドキュメントキャッシュは、ボルトの外部に置く必要がある状態ディレクトリに保存されます。
• grep_files は子プロセス内で実行され、10秒後に終了します。ドキュメントはタイムアウトとメモリ上限を設定したワーカースレッドで抽出されます。SQLiteはsqlite3 -readonly -safeで実行されます。

詳細：セキュリティ。

リンク

• ドキュメント — インストール、 ファイルの追加、 リモートアクセス、 設定、 書き込みポリシー、 ツール、 検索と編集、 ドキュメント、 sqlite、 セキュリティ、 トラブルシューティング、 内部構造
• Home Assistant アプリ
• 変更履歴
• Issue：サーバーの問題はこちらに報告してください。Home Assistant アプリのインストールまたは実行に関する問題は、ha-filesystem-mcp に報告してください。

ライセンス

MIT — st412m によるライセンスです。