memkeeper

ほとんどのソフトウェアは金魚並みの記憶力です。これは違います。

memkeeper

AI エージェント向けのローカルファーストなメモリです。エージェントの長期的なコンテキストを保存、ランク付け、取得する高速で組み込み可能なメモリエンジンで、必要なネットワーク接続や LLM 呼び出しはなく、すべてお使いのマシン上で動作します。

Memkeeper は、AI エージェントが実行されるオープンソースのローカルファーストなコントロールプレーンです。長期メモリ、プロジェクトコンテキスト、連携されたタスクの引き継ぎ、デフォルト拒否の権限をすべて決定論的に、お使いのマシン上で提供します。このリポジトリは、その中核となるメモリエンジンです。

ℹ️ 生成されたリリースミラーです。 このリポジトリは非公開の開発用リポジトリから生成され、リリースとして公開されています。main ブランチは再生成される可能性があるため、任意の main コミットではなく、タグ付きリリース（またはリリース成果物）を指定してください。タグ付きリリースは安定しています。貢献方法についてはCONTRIBUTING.mdをご覧ください。現時点では、イシュー、セキュリティ報告、設計に関するフィードバックが最適な方法です。

• ローカルファースト。 単一の SQLite データベースを使用します。サーバー、クラウド、テレメトリはありません。
• プロンプト実行時も高速。 決定論的な BM25/FTS 検索に、オプションの ONNX セマンティック埋め込みとクロスエンコーダーによる再ランキングを組み合わせます。
• 長期保存を考慮した設計。 アトミックな書き込み、スキーマバージョン管理されたストレージ、そして繰り返し現れる重要度の高いメモリを長期保存層に昇格させる保持モデルを備えています。

_{実際の CLI 出力を、scripts/mkfmtで読みやすく整形しています。検索クエリには、見つかったメモリとの共通キーワードがありません。}

ステータス：リリース前（v0.5.3）。API とワイヤープロトコルは 1.0 より前に変更される可能性があります。

クイックスタート

# Install the latest release binary (macOS arm64 / Linux x86_64) to ~/.local/bin.
# It's self-contained — nothing else to install.
curl -fsSL https://raw.githubusercontent.com/teflon07/memkeeper/main/install.sh | bash

# Optional, one-time: fetch on-device semantic models. Lexical search works without it.
memkeeper pull-models

# Create a store, remember something, search it back.
memkeeper init
memkeeper remember --json '{"content":"memkeeper stores memories in a local SQLite database"}'
memkeeper search   --json '{"query":"where are memories stored","limit":3}'

インストールはこれだけです。自己完結型のバイナリで、実行時のネットワーク接続、LLM、API キーは必要ありません。スクリプトをシェルにパイプしたくない場合は、リリースページからバイナリをダウンロードして.sha256を検証するか、ソースからビルドしてください。--storeを省略すると、ストアは~/.memkeeper/store.sqliteになります。--jsonの値にはインライン文字列のほか、@<file>や-（stdin）も指定できるため、シェルでの引用符の扱いによる問題を避けられます（Windows PowerShell で便利です）。

v0.2.x からのアップグレード

v0.3.0 ではスキーマ 5 からスキーマ 6 へのアップグレードが導入されました。v0.4.0 から v0.5.3 ではスキーマ 6 が維持されています。移行はトランザクションで実行されますが、スキーマ 6 のストアは v0.2.x では開けません。長時間実行中のmemkeeperプロセスを停止し、アップグレードを確認するまでスキーマ 5 のバックアップを保管してください。

現在のリリースをインストールする前に、v0.2.x のバイナリでストアをバックアップしてください。

STORE=~/.memkeeper/store.sqlite
memkeeper backup --store "$STORE" --output "$STORE.schema5.bak" --json

現在のリリースをインストールし、移行を明示的に実行して、長時間実行中のプロセスを再起動する前に結果を確認してください。

curl -fsSL https://raw.githubusercontent.com/teflon07/memkeeper/main/install.sh | bash
memkeeper init --store "$STORE" --json
memkeeper doctor --store "$STORE" --json

initは安全に再実行できます。ロールバックが必要な場合は、古いバイナリを起動する前にスキーマ 5 のバックアップを復元してください。

エージェントから利用する（MCP）

memkeeper は MCP（stdio 経由の JSON-RPC 2.0）に対応しているため、Claude Code、Cursor などの MCP クライアントは、セッション中にメモリを読み書きできます。クライアントの MCP 設定で ネイティブバイナリ を指定してください（Python や追加の依存関係は不要です）。

{ "mcpServers": { "memkeeper": { "command": "memkeeper", "args": ["mcp"] } } }

エージェントは remember を呼び出して永続化する情報を記録し、後の別のセッションで search を呼び出して、CLI と同じ検索方法でそれを呼び出します。

_{実際の memkeeper mcp の JSON-RPC ラウンドトリップを、scripts/mcpfmt で読みやすく整形しています。}

保存する内容

memkeeper が保持するのは、自己完結したメモリです。事実、決定事項、好み、教訓などを保存します。remember の呼び出しごとに、文脈と意図を保ったまま単独で成立するメモリを1つ書き込みます（「ユーザーはピザにパイナップルを載せるのが好き」と保存し、「パイナップル」だけにはしません）。アトミックであるとは、メモリ1つにつきアイデア1つという意味であり、キーワードだけに切り詰めることではありません。検索、重複排除、置き換え、エンティティグラフは、この粒度で最も効果を発揮します。

避けるべき両極端は次のとおりです。

• 小さすぎる場合： 要点が抜け落ちた単なるキーワードや断片。
• 大きすぎる場合： 文書全体。厳選されたメモリ層ではチャンク分割を行わず、埋め込みモデルが各エントリの先頭約512トークンしか認識しないため、長いファイル（たとえば、Markdown ライブラリ全体）を読み込むと、そのエントリのセマンティック検索の精度が低くなります（字句検索の BM25 では全文がインデックスされます）。文書全体を取り込むには、メモリとして保存せず、memkeeper の独立した RAG 層であるドキュメントストアを使用してください。この層では、ファイルをチャンク分割して、分離されたスペースに埋め込みます（memkeeper-ingest アドオンを使うと、フォルダー全体をこの方法でインポートできます）。または、文書の要点をまとめて、それをメモリとして保存してください。

メモリの記録

memkeeper は、意図的に追加していく厳選型のメモリであり、自動で会話記録をログに残すものではありません。メモリを追加する方法は2つあります。

• 直接追加する — CLI またはスクリプトから memkeeper remember --json '{"content":"…"}' を実行します。
• エージェントから追加する — ネイティブのMCP サーバーを使うと、MCP クライアント（Claude やその他のエージェント）がセッション中に remember を呼び出し、永続化する情報が会話に登場した時点で記録できます。確認済みのメモリでエンティティを指定したり、関係性を述べたりする場合、MCP ツールはエージェントに対し、同じ呼び出しで制約されたグラフ表現を含めるよう求めます。memkeeper はメモリ、正確な別名、型付きの関係性を検証し、アトミックにコミットします。1つのメモリ ID が関係性の根拠となります。

memkeeper がこのために別の LLM やバックグラウンド抽出器を実行することはありません。MCP ホストエージェントが通常の remember 呼び出しを行う際に、構造化されたグラフフィールドを提供します。CLI から直接呼び出す場合は、同じ graph オブジェクトを明示的に指定できます。

検索側では、memkeeper hook retrieve は Claude Code の UserPromptSubmit フッククライアントとして関連するメモリをプロンプトに挿入するため、エージェントは明示的に検索しなくても情報を呼び出せます。この機能は検索を行うものであり、記録には引き続き意図的な remember が必要です。

セマンティック検索（デフォルト）

memkeeper には 3 つの検索モードがあります。ローカルセマンティックはデフォルトであり、デバイス上で完結する推奨モードです。 モードは最初に選んでください。埋め込みバックエンドはストアに記録されるため、変更するには切り替えるのではなく、再埋め込み（reindex --embed）が必要です。

_{決定的な基盤（モデルもネットワークも不要）と、その上に追加されるセマンティック検索と再ランキング。同じストア、同じ検索経路です。scripts/mkfmt による実際の出力です。}

モード	ネットワーク	セットアップ
ローカルセマンティック（デフォルト）	不要	バイナリをインストールしてから pull-models を実行
語彙検索のみ	不要	そのまま使えます。pull-models を実行しないでください
デバイス外セマンティック	API を介して埋め込みを実行	MEMKEEPER_EMBED_PROVIDER=openai とベース URL、キーを設定

プライバシー： デバイス外セマンティックでは、メモリのテキストをベクトル化するために埋め込みプロバイダーへ送信します。許容できる場合にのみ使用してください。2 つのデバイス上で完結するモードでは、メモリの内容が外部へ送信されることはありません。

ローカルセマンティック（デフォルト）

リリースバイナリはセマンティック検索に対応しており（ONNX ランタイムは静的にバンドルされています）、再ビルドは不要です。必要なのは、埋め込みモデルと再ランキングモデルだけですが、これらは自動ではダウンロードされません。一度だけ取得してください。

# Needs curl; ~2.1GB, or --quantized for ~0.6GB (slightly lower recall).
memkeeper pull-models

pull-models は ~/.memkeeper/models/ に書き込みます（MEMKEEPER_MODELS_DIR または --dir で変更可能）。これは memkeeper がデフォルトで参照する場所です。そのため、設定する環境変数はありません。その後 search を実行すれば、セマンティック検索が有効になります。

モデルがない場合、memkeeper は黙って機能を低下させることはありません。モデルがないことをログに記録して pull-models を案内し、検索結果にセマンティック検索が利用できないことを示します（例："semantic":{"attempted":false,"reason":"missing_embedding"}）。そのうえで、検索を継続できるよう、語彙検索（BM25/FTS）にフォールバックします。語彙検索のみが黙って実行されることを絶対に避ける必要があるデプロイでは、MEMKEEPER_REQUIRE_SEMANTIC=1 を設定して、代わりにフェイルクローズにしてください。つまり、機能が低下した検索結果を返さず、リクエストを拒否します。

埋め込みはメモリの書き込み時に計算されます。モデルが用意される前に保存したメモリ（上記のクイックスタートで保存したものなど）は、埋め込みが行われるまで語彙検索のみで処理されます。既存のメモリは、次のコマンドで一度バックフィルしてください。

memkeeper reindex --embed

モデルが用意された状態で新しく書き込まれたメモリは、自動的に埋め込まれます。

語彙検索のみ

pull-models を実行せずにリリースバイナリを使用すると、決定的でモデル不要の語彙検索のみ（BM25/FTS）が実行されます。ネットワークもモデルも不要です。ソースから --no-default-features を指定してビルドすると、ONNX ランタイムを完全に除外した、より軽量なバイナリが生成されます（ソースからビルドを参照）。

デバイス外セマンティック（モデルのダウンロード不要）

ONNX モデルをダウンロードしたくない場合は、代わりに memkeeper を OpenAI 互換の埋め込み API（OpenAI、OpenRouter、または互換プロキシ）に接続してください。このモードではローカルモデルを読み込まず、ネットワーク経由で埋め込みと再ランキングを行うため、pull-models は不要です。

# Embeddings (required for semantic): any OpenAI-compatible /embeddings endpoint.
export MEMKEEPER_EMBED_PROVIDER=openai     # "openai" = the OpenAI-compatible API dialect
export MEMKEEPER_EMBED_BASE_URL=https://api.openai.com/v1/embeddings   # or your provider, e.g. OpenRouter
export MEMKEEPER_EMBED_API_KEY=sk-...
export MEMKEEPER_EMBED_MODEL=text-embedding-3-small
export MEMKEEPER_EMBED_DIMS=1536

# Reranking (optional, recommended): Cohere /rerank dialect, which OpenRouter speaks.
export MEMKEEPER_RERANK_PROVIDER=openrouter
export MEMKEEPER_RERANK_API_KEY=sk-...
export MEMKEEPER_RERANK_MODEL=cohere/rerank-v3.5

ビルド済みリリースバイナリは 3 つのモードすべてに対応しています（--features semantic,api）。pull-models を実行すると、デバイス上で完結するローカルセマンティック（デフォルトかつ推奨モード）が利用できます。デバイス外セマンティックを使うには API キーを設定してください。どちらも設定しない場合は、語彙検索（BM25/FTS）が実行されます。MEMKEEPER_REQUIRE_SEMANTIC=1 を設定すると、機能が低下した結果を返さずにリクエストを拒否します。

ビルド済みバイナリは macOS（Apple Silicon） と Linux x86_64 向けに公開されています。Windows は実験的な対応です。 ビルド済みバイナリはありませんが、ソースからビルドして実行できます。docs/windows.md を参照してください（serve --socket は Unix 専用ですが、HTTP ダッシュボードと stdio によるサーブはクロスプラットフォームです）。

pack がセマンティック検索とグラフ検索を組み合わせる方法

pack は、単一の検索経路を使用します。セマンティック一致と字句一致からメモリのシードを取得し、完全一致したエンティティと別名からグラフのシードを取得します。その後、根拠に裏付けられた範囲制限付きのグラフ走査によって、両方の集合を正規メモリ ID で結合します。すべての候補は、同じクロスエンコーダーの再ランキングプールで競合します。グラフ候補に優先枠が割り当てられたり、自動的に順位を下げられたりすることはなく、本番環境でグラフのオン／オフを切り替えるモードもありません。対象となるグラフ経路がないストアでは、セマンティック検索と字句検索のプールがそのまま返されます。

埋め込みモデルの切り替え

埋め込みバックエンドはストアごとに記録されます。異なるモデルのベクトルは異なるベクトル空間に存在するため、memkeeper はそれらを混在させません。ローカルからデバイス外への切り替え、またはモデル間の切り替えを行うには、埋め込み用の環境変数を変更し、新しいモデルで一度にすべてのメモリを再埋め込みします。

./target/release/memkeeper reindex --embed --store ~/.memkeeper/store.sqlite

これにより古いベクトルが削除され、新しいアクティブモデルが記録され、すべてのアクティブなメモリが 1 つのトランザクション内で再埋め込みされます。モデルを切り替える際にサポートされている方法はこれだけであり、一部だけを混在させることはできません。

ドキュメントストア（RAG）

キュレーションされたメモリに加えて、memkeeper では、検索拡張用途向けに取り込んだドキュメントチャンクを別の階層に保持できます。チャンクは独自の領域（デフォルトは documents）に保存され、キュレーションされたメモリ階層から分離されているため、上書き、重複排除、グラフ化、昇格の対象にはなりません。

• ingest — ドキュメントソースを、埋め込み済みの分離されたチャンクとして保存します。同じ source_path を再取り込みすると、そのチャンクの来歴がその場で修復されます。異なるパスにある同一コンテンツは、独立したチャンクとして保持されます。
• document-search — チャンクを対象にハイブリッド検索（BM25 + ベクトル検索）を行い、source_path とチャンクインデックスへの引用を返します。
• document-get — パスを指定してドキュメントのチャンクを取得するか、ID を指定して 1 つのチャンクを取得します。
• document-duplicates — 完全に同じ内容の重複チャンク（異なるソースにある同一コンテンツ）をクラスターとして表示します。stats では document_duplicate_clusters の数も報告されるため、確認が必要な重複があるかどうかを把握できます。
• document-prune — 選択した特定のチャンクを削除します（dry_run に対応）。削除は常に明示的に行います。重複を確認し、どのコピーを残すか決めてから、残りを削除してください。
• promotion-candidates / mark-extracted — 検索トラフィックを獲得したチャンクを順位付けし、チャンクがメモリに昇格されたら抽出済みとしてマークします。

各コマンドで受け付ける JSON フィールドについては、memkeeper schema <command> を実行してください。serve --http では、読み取り操作（search/get/duplicates）を読み取り専用ダッシュボードで利用できます。書き込み操作（ingest、document-prune）は、書き込みトークンを設定しない限り無効です。環境変数に MEMKEEPER_HTTP_WRITE_TOKEN=<secret> を設定してサーバーを起動し、書き込みリクエストでは Authorization: Bearer <secret> として送信してください。トークンを設定しない場合、HTTP サーバーは読み取り専用になります。

ダッシュボード

memkeeper serve --http は、メモリとエンティティグラフを閲覧するための読み取り専用ローカルダッシュボード（デフォルトは http://127.0.0.1:7777）を起動します。--store <path>（または MEMKEEPER_STORE）を指定してストアを設定できます。指定しない場合はデフォルトのストアが使用されます。

新しいストアは空の状態で始まります。これは想定どおりです。 2 つのビューには、それぞれ異なる方法でデータが追加されます。

• メモリリストは、remember を実行するとデータが追加されます。
• グラフは、エンティティと関係を可視化します。これらは生のメモリとは別のレイヤーです。ネイティブ MCP の remember は、ホストエージェントから提供された場合、確認済みのメモリとともに、範囲制限付きのエンティティ、別名、型付き関係を取り込みます。生の CLI 呼び出し元は、同じグラフ構造を渡すか、entity-upsert / relationship-upsert でキュレーションできます。dream graph タスクでは、可視化のために汎用の related_to リンクが追加される場合がありますが、それらのリンクは検索の根拠にはなりません。グラフフィールドのない通常のメモリもリストには追加されますが、グラフのエッジは追加されません。

ベンチマーク

LoCoMo（複数セッションにわたる対話10件、根拠を含む質問1,982件）において、memkeeper のデフォルトのセマンティック検索スコアは次のとおりです。

指標	スコア
recall@20	0.768
hit@20	0.880
MRR	0.668

ウォーム状態の serve デーモン（ONNX モデルを一度だけ読み込み）でのプロンプト時検索は、p50/p95 で 約25 ms で実行されます。クエリごとにモデルを再読み込みするコールド状態の単発バイナリより約32倍高速です。

詳細な手法、設定ごとの結果（レイトインタラクションによるアップグレードを含む）、再現用スクリプトについては、docs/benchmarks.md をご覧ください。

ソースからビルド

ビルドは任意です。クイックスタートのバイナリは自己完結型です。 最新の main を利用する場合、より軽量な語彙検索のみのバイナリを作成する場合、または開発を行う場合は、ソースからビルドしてください。

前提条件： Rust ツールチェーン（rustup 経由の stable。edition 2021、Rust 1.56 以降）と、ネイティブ依存関係のための C ツールチェーン（バンドルされた SQLite とセマンティック検索用の ONNX ランタイム）が必要です。macOS の場合：Xcode Command Line Tools（xcode-select --install）、Debian/Ubuntu の場合：build-essential。初回のビルドでは crates.io からクレートを取得しますが、その後はクリーンビルドをオフラインで実行できます。

# Semantic build (default): local embeddings + cross-encoder rerank.
cargo build --release
# ...or lexical-only — omits the ONNX runtime and models entirely:
cargo build --release --no-default-features

# The binary lands at ./target/release/memkeeper (not on PATH). To install it:
cargo install --path crates/memkeeper-cli   # then a bare `memkeeper` works

続いて memkeeper pull-models を実行すると、クイックスタートと同様にセマンティック検索が有効になります。

ワークスペースの構成

クレート	役割
memkeeper-core	コア型と検索ポリシー
memkeeper-store	SQLite ストレージ、スキーマ、インデックス作成、昇格
memkeeper-embed	ONNX 埋め込みとクロスエンコーダーの再ランキング
memkeeper-protocol	ワイヤープロトコル（memkeeper.v0.1）
memkeeper-cli	memkeeper バイナリ（CLI とデーモン）

エディター／エージェントとの統合機能は adapters/ 以下にあります（MCP ブリッジと薄い拡張クライアント）。

関連記事

memkeeper ブログで、設計に関する記事やベンチマークをご覧いただけます。

• AI エージェント向けのローカルファーストなメモリ：ホスト型ベクトル DB ではなく、自分のマシンをデフォルトにすべき理由です。
• ハイブリッド検索が純粋なベクトル検索を上回る理由：BM25、密な埋め込み、クロスエンコーダーがそれぞれどのような情報を捉えるかを説明します。
• 「わかりません」と言えるメモリ：回答の棄権と、それを実証するために公開している数値について説明します。
• LoCoMo でエージェントメモリをベンチマークする：数値を再現するための手法とスクリプトを紹介します。
• memkeeper の位置づけ：mem0、Zep、Graphiti との率直な比較です。
• 10分で始める：インストールから記憶の検索まで、MCP の接続方法も含めて説明します。

Memkeeper ファミリー

Warden は、コンパニオン機能として動作するケイパビリティブローカー兼実行ゲートです。エージェントが要求したアクション（シェルコマンド、ファイルの読み書き）が、宣言された監査可能なポリシーで許可されているかを判断し、すべての判断を記録します。memkeeper は記憶し、Warden は保護します。

ライセンス

任意で、MIT または Apache-2.0 のいずれかのデュアルライセンスが適用されます。

コントリビューション

CONTRIBUTING.md をご覧ください。コントリビューションには、プロジェクトのコントリビューターライセンス契約への署名が必要です。初回のプルリクエスト時に CLA ボットから案内があります。コントリビューションの著作権はご自身に保持されます。