Kirok Memory

Kirok

英語 | 日本語

MCP を介して AI エージェントに永続的なメモリーを提供します。 Kirok（記録）は、エージェントに永続的で検索可能なメモリーを与える Model Context Protocol サーバーです。重要な情報を保持し、セマンティック検索とキーワード検索を組み合わせて想起し、蓄積したメモリーを再利用可能な知見へとまとめるために振り返ります。バックグラウンドの統合ループが、生のメモリーをより高次の観察へと自動的に変換します。

Kirok を選ぶ理由

一般的な「エージェントメモリー」は、単純なベクトルストア（検索はコサイン類似度による単純な top-k で、キーワードによる裏付けも忘却機能もありません）か、エージェントが各ターンで読み直さなければならない大量の Markdown のどちらかです。Kirok は、検索の仕組みを適切に実装した、小規模でセルフホスト可能なサーバーです。

• ベクトルだけではないハイブリッド検索。 セマンティック KNN と FTS5 BM25 を Reciprocal Rank Fusion で融合するため、完全一致するキーワードとセマンティック検索の結果が競合せず、互いを補強します。
• 調整された関連性の下限。 単純なコサイン類似度のしきい値は、実際の埋め込み分布では機能しません（検索品質を参照）。Kirok の下限は実データを基準に測定され、適切な状態を維持するための評価ハーネスも備えています。
• 自律的な統合。 メモリーは定期的に統合されて観察へと変換されます。また、破壊的な LLM の判断は、盲目的に実行するのではなく、監査証跡を残してソフト削除されます。
• まず信頼性を重視。 アトミックな書き込み、ソフト削除、起動時の自動スナップショット、そして retain を決して失わないフェイルオープン型のバックグラウンドパイプラインを備えています。

ローカルファーストではありません： ストレージはユーザー自身が管理するローカルの SQLite ファイルですが、埋め込みと LLM の推論は Google の Gemini API に送信されます。すべてをデバイス上に留める必要がある場合、Kirok は適していません（現時点では）。

アーキテクチャ

flowchart TB
    client["MCP Client<br/>(Claude Desktop / Claude Code / Cursor / …)"]
    subgraph server["Kirok MCP Server (FastMCP)"]
        direction TB
        tools["19 MCP tools<br/>Retain · Recall · Reflect · consolidate · CRUD"]
        pipeline["Hybrid search (RRF) · Smart dedup<br/>Consolidation · Auto-refresh"]
    end
    subgraph storage["Local SQLite (WAL)"]
        direction LR
        fts["FTS5 trigram<br/>(BM25 keyword)"]
        vec["sqlite-vec<br/>(KNN, brute-force fallback)"]
        tables["memories · observations<br/>mental_models · banks · system_events"]
    end
    gemini["Google Gemini API<br/>gemini-embedding-001 (3072-d)<br/>gemini-2.5-flash-lite"]

    client <-->|"stdio (JSON-RPC 2.0)"| tools
    tools --> pipeline
    pipeline <--> storage
    pipeline <-->|embeddings · entity extraction<br/>reflection · consolidation| gemini

ストレージは ~/.kirok/memory.db にある単一の SQLite データベースです。sqlite-vec がバンクごとのベクトル KNN を提供します。ネイティブ拡張機能を読み込めない場合、Kirok は同一の結果を返す NumPy の総当たりスキャンにフォールバックします。全体の設計については、docs/architecture.md を参照してください。

🚀 クイックスタート

要件： Python 3.12+、uv（uvx 用）、および Gemini API キー（無料枠で十分です）。

Kirok は PyPI で配布されているため、クローンは不要です。キーを ~/.kirok/.env に記述し（1 行で GEMINI_API_KEY=AIza...）、次のコマンドでセットアップを確認します。

uvx --from kirok-mcp kirok-doctor   # offline sanity check

MCP クライアントに接続する

Claude Code CLI：

claude mcp add kirok -s user -- uvx kirok-mcp

Claude Desktop — claude_desktop_config.json を編集します（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）。

{
  "mcpServers": {
    "kirok": { "command": "uvx", "args": ["kirok-mcp"] }
  }
}

その後、クライアントを再起動してください。サーバーは ~/.kirok/.env から GEMINI_API_KEY を読み込みます。クライアント設定の env ブロックも使用でき、その場合はこちらが優先されます。

ソースから（開発）

git clone https://github.com/TadFuji/kirok-mcp.git
cd kirok-mcp
uv sync                       # installs deps, including sqlite-vec
cp .env.example .env          # then put your key in it: GEMINI_API_KEY=AIza...
uv run kirok-doctor           # offline sanity check of the whole setup

uvx kirok-mcp の代わりに、uv run --directory /absolute/path/to/kirok-mcp kirok-mcp を使って、MCP クライアントからチェックアウト先を指定します。

ヒント

uv run でサーバーを起動できない場合（Windows やクラウド同期フォルダーでよく発生します。uv run は起動のたびに再同期するため、ロック中の .venv ファイルや使用中のエントリーポイント .exe によって問題が発生することがあります）、同期を完全にスキップできるよう、仮想環境の Python を直接呼び出してください。

{
  "mcpServers": {
    "kirok": {
      "command": "/absolute/path/to/kirok-mcp/.venv/bin/python",
      "args": ["-m", "kirok_mcp.server"],
      "env": { "PYTHONPATH": "/absolute/path/to/kirok-mcp/src" }
    }
  }
}

Windows では .venv\\Scripts\\python.exe を使用し、JSON 内のパスではバックスラッシュを二重にしてください。

skills/kirok/ に同梱されているエージェントスキルは、メモリツールをいつ、どのように自律的に使うかをエージェントに教えます。有効にするには、クライアントから skills/kirok/SKILL.md を指定してください。

🛠️ ツール

MCP ツールは 19 個あります。以下に概要を 1 行ずつ記載しています。全パラメーターの一覧は docs/tools-reference.md をご覧ください。

コア

ツール	目的
KIROK_retain	メモリを保存します。エンティティ／キーワードの抽出＋埋め込み＋スマートな ADD／UPDATE／NOOP 重複排除を行います
KIROK_recall	セマンティック検索とキーワード検索を組み合わせたハイブリッド検索（RRF）を行い、観察結果を先に表示します
KIROK_reflect	メモリを統合してメンタルモデル（インサイト）を作成し、必要に応じて自動更新します
KIROK_smart_retain	まず重要度をスコア化（1～10）し、しきい値を超えた場合にのみ保存します
KIROK_consolidate	バンクの観察結果の統合を手動で実行します

メモリ管理

ツール	目的
KIROK_get_memory / KIROK_list_memories	1 件のメモリを取得／ページネーションでバンク内を閲覧します
KIROK_update_memory	内容またはコンテキストを編集します（内容の変更時は再抽出と再埋め込みを行います）
KIROK_forget	1 件のメモリを削除します（元に戻せません）

メンタルモデル

ツール	目的
KIROK_list_mental_models / KIROK_get_mental_model	Reflect のインサイトを一覧表示／確認します
KIROK_refresh_mental_model	現在のメモリをもとに再分析します
KIROK_delete_mental_model	メンタルモデルを削除します（元に戻せません）

バンク

ツール	目的
KIROK_list_banks / KIROK_stats	件数付きでバンクを一覧表示／バックグラウンドでの失敗を含む、バンクごとの詳細な統計情報を表示します
KIROK_clear_bank	バンクのメモリと観察結果を削除します（confirm=true が必要です。それ以外の場合はプレビューを表示します）
KIROK_delete_bank	バンク全体を削除します（confirm=true が必要です。それ以外の場合はプレビューを表示します）

設定

ツール	目的
KIROK_set_bank_config / KIROK_get_bank_config	バンクの保存と観察の「ミッション」（重点を置く内容）を設定／表示します

⚙️ 設定

すべての設定は環境変数（通常は .env 内）で行います。必須なのは GEMINI_API_KEY のみです。

変数	デフォルト	説明
GEMINI_API_KEY	—	必須。 Google Gemini API キーです。
KIROK_DB_PATH	~/.kirok/memory.db	SQLite データベースの保存場所です。
KIROK_DEDUP_THRESHOLD	0.85	類似度がこの値を超えると、retain が LLM による重複排除の判定（ADD／UPDATE／NOOP）を実行します。
KIROK_RECALL_MIN_SIMILARITY	0.62	recall におけるセマンティックメモリ検索結果の類似度の下限です。キーワード／FTS 検索結果は対象外です。
KIROK_OBS_MIN_SIMILARITY	0.62	recall における観察結果の類似度の下限です。
KIROK_CONSOLIDATION_BATCH_SIZE	5	保留中のメモリがこの件数に達した場合にのみ、自動統合を実行します（1 = 保存のたびに実行）。
KIROK_CONSOLIDATION_TIMEOUT	120	統合のタイムアウト時間（秒）です。
KIROK_REFLECT_TIMEOUT	300	Reflect のタイムアウト時間（秒）です。
KIROK_AUTO_SNAPSHOT_HOURS	24	起動時の自動スナップショットの最小間隔（時間）です（0 で無効）。
KIROK_SNAPSHOT_KEEP	5	自動スナップショットの世代を保持する数です。古いものから順にローテーションで削除します。

🔍 検索品質

Recall はセマンティック KNN と FTS5 BM25 を並行して実行し、Reciprocal Rank Fusion（k=60）で統合します。短い日本語キーワードクエリは特別に処理します。1〜2 文字の漢字／カタカナのトークンは、トライグラムトークナイザーの 3 文字のウィンドウを下回るため、MATCH に一致することはありません。そのため、BM25 のヒットの後に追加する完全一致の部分文字列 LIKE 補完で取りこぼしを防ぎます（ひらがなのみの短いトークンは引き続き除外します。機能語では銀行内の半分ほどに部分文字列一致する可能性があるためです。トークンは OR で結合され、MATCH 側と同様に照合されます）。

ハイブリッド検索の精度を保つため、次の 3 点に配慮しています。各ソースは最終ページより深く取得する（max(limit*3, 30)）ため、両方のリストでカットオフのすぐ外にランクされた項目も RRF で上位に浮上できます。FTS のすべてのテキストはインデックス側とクエリ側の両方で NFKC 正規化されるため、幅の異なる文字（ＭＣＰ と MCP、ﾊﾞｸﾞ と バグ）が実際に一致します。また、観察にもメモリと同じハイブリッド処理を適用します。セマンティックヒットには下限を適用し、キーワードヒットは下限の対象外とすることで、セマンティック下限を通過した場合にしかアクセスできない状態を防ぎます。

類似度の下限は実データに基づいて調整されています。 単純なコサイン類似度のしきい値はここでは機能しません。実際の gemini-embedding-001 ベクトルでは分布の幅が狭く、無関係なクエリは無関係なバンクに対して 0.55〜0.62、真のヒットは 0.66〜0.73 のスコアになります。そこで、使用可能な下限を無関係なクエリの上限をわずかに超える 0.62 に設定しています。これがないと、無関係なクエリでも、空でないバンクからは常にメモリが 1 ページ分返されます（コンテキスト汚染）。これより大幅に低くすると、下限は何もフィルタリングしません（以前のハードコードされた 0.4 は、無関係なクエリのスコアよりも低い値でした）。FTS のキーワードヒットは下限を完全に迂回します。文字列そのものの一致は独立した証拠であり、弱いベクトルスコアではありません。

検索パラメーターは勘で調整していません。scripts/search_eval.py は、サーバーが使用する正確な検索パイプライン（hybrid_search_memories として抽出されており、ハーネスが本番環境の処理と乖離することはありません）を通してゴールデンクエリセットを実行し、hit@1／hit@5／hit@k と MRR を報告します。

cp scripts/search_eval.example.json my_golden.json   # add 30–50 real cases
uv run python scripts/search_eval.py my_golden.json --limit 10

🛡️ 信頼性

• アトミックな統合。 すべての作成／更新用の埋め込みは、DB に書き込む前に生成されます。観察へのすべての変更と「統合済み」マークは、単一のトランザクションでコミットされます。どの段階で失敗しても、データベースは変更前の状態を保ち、ソースのメモリは後で再試行できるよう保留中のままになります。バッチの一部だけが適用されることはありません。
• 失敗を表面化し、成功を偽装しません。 統合 LLM が失敗するとエラーが発生し、system_events に記録されます。生成結果がないままバッチが統合済みとして黙ってマークされるのではなく、後で再試行できるよう保留中のままになります。実行はバンクごとに直列化されるため、2 つの retain が同時に到着しても、同じバッチが重複した観察に二重処理されることはありません。
• 監査証跡付きの論理削除。 統合 LLM が削除すると判断した観察には deprecated_at を設定し、破棄せずに検索／一覧／統計から除外します。また、重複排除時の UPDATE では、マージ前の内容をマージ処理と同じトランザクション内に記録します。どちらも system_events に記録されるため、LLM の誤った判断から復旧でき、データが黙って失われることはありません。
• 起動時の自動スナップショット。 起動時に、最新の自動スナップショットが KIROK_AUTO_SNAPSHOT_HOURS より古い場合、VACUUM INTO と integrity_check によるスナップショットを ~/.kirok/backups/ に保存し、最新の KIROK_SNAPSHOT_KEEP 世代を保持します。途中で失敗したスナップショットは破損ファイルを残さず、手動バックアップはローテーションされません。
• 並行性。 接続では PRAGMA busy_timeout=30000 を設定するため、2 つ目の MCP クライアントは database is locked で失敗せず、書き込み中の処理が終わるまで待機します。
• バックグラウンド処理のフェイルオープン。 自動統合とメンタルモデルの更新は retain の背後で実行され、retain を失敗させることはありません。エラーは握りつぶされて system_events に記録され、KIROK_stats 経由で確認できるため、気付かれないままの劣化を可視化できます。

💾 バックアップと復元

すべての状態は1つのSQLiteファイルに保存されます。オフラインのkirok-backup CLIではAPIキーは不要です：

uv run kirok-backup snapshot        # byte-level DB copy (safe while server runs)
uv run kirok-backup export          # portable JSON of all banks + memories + observations + models
uv run kirok-backup import ~/.kirok/backups/kirok-export-YYYYMMDD-HHMMSS.json

snapshotとexportは~/.kirok/backups/の下にタイムスタンプ付きのファイルを書き込み、上書きは行いません。importは1つのトランザクション内で実行され（すべて成功するか、すべて取り消されます）、既存のIDは上書きせずにスキップし、FTSインデックスとベクトルインデックスを再構築するため、すぐに検索できます。別のデータベースファイルを対象にするには--dbを使用してください。

🩺 診断

uv run kirok-doctor            # offline: Python version, .env, key presence (never printed),
                               # required modules, FTS5, sqlite-vec, DB writability
uv run kirok-doctor --json     # machine-readable, for automation
uv run kirok-doctor --online   # adds one live embedding call to verify Gemini connectivity

🧑‍💻 開発

uv sync
uv run --no-sync pytest        # 164 offline tests; no API key or network needed

テストスイートは完全にオフラインで実行できます。kirok_mcp.serverのインポートには副作用がなく（APIキーの確認はインポート時ではなく起動時に行われます）、テストではGeminiクライアントを偽物に差し替えます。CIでは、プッシュのたびにUbuntuとWindowsで同じテストスイートを実行します（.github/workflows/test.yml）。PRを作成する前にCONTRIBUTING.mdを確認してください。

📚 ドキュメント

• docs/architecture.md — 内部設計、データモデル、統合エンジン
• docs/tools-reference.md — 19個すべてのツールのパラメーターリファレンス
• CHANGELOG.md — バージョン履歴（現在：1.4.2）

📄 ライセンス

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

謝辞

• Model Context Protocolと公式のMCP Python SDK（FastMCP）
• 埋め込みとLLMに使用しているGoogle Gemini API
• Mem0 — スマートな重複排除とナレッジレイヤーの着想を得ました
• Reciprocal Rank Fusion（Cormackほか、2009年）