MCPメモリサーバー「cachly」の実装から学ぶ：小規模チーム向け軽量AI記憶層の設計パターンと運用制約

AIエージェントに「記憶」が必要な理由：コンテキストの断片化と解決策の概要

LLMはステートレスな設計であり、セッションが切れるとそれまでの対話文脈が完全に失われる。開発現場では、あるセッションで「この関数は再帰深度が溢れるのでイテレーション方式に置き換えた」という判断がなされても、次のセッションではAIアシスタントがその経緯を一切知らない。結果として、開発者は同じ文脈を繰り返し説明するか、あるいはAIが以前と矛盾する提案を繰り返すという非効率に陥る。

従来の解決策として広く採用されているのが、コードベースのインデックス作成とRAG（検索拡張生成）の組み合わせである。しかし、このアプローチが対象とするのは「コードの静的構造」であり、「なぜこのように設計したか」「このパターンで過去に何が失敗したか」といった暗黙知の保持には向いていない。コードのdiffからは変更の事実が読めても、変更の動機や失敗の教訓までは抽出できない。このギャップこそが、AIエージェントの開発効率を制約する本質的なボトルネックである。

MCP（Model Context Protocol）は、AIモデルと外部データソースを標準化された方法で接続するプロトコルとして、近年注目が高まっている。MCPを介すことで、AIエディタ側が個別にデータソースとの連携ロジックを実装する必要がなくなり、メモリや知識ベースをプラグイン的に追加できる構成になる。本記事では、個人開発者が6週間の単一ユーザー実証実験を通じて構築した軽量メモリサーバー「cachly」の設計パターンに焦点を当てる。開発者の実証実験レポートでは、記憶サーバーが同じミスの繰り返しを防ぐ効果が確認されていると報告されている。

この6週間の個人利用という限定的なスコープは、逆に設計判断の透明性という利点を持つ。チームスケールでの運用が絡まないため、「キャッシュと永続化のバランス」「学習データの品質管理」など、本質的な設計問題がノイズなく浮かび上がる。以下では、cachlyの実装から抽出できる設計パターンと、小規模チームへの適用可能性を順に検討する。

MCPメモリサーバーのアーキテクチャ：cachlyの実装と連携範囲

cachlyは、Claude Code、Cursor、Copilotなどの主要AIエディタとMCP経由で連携し、コードベースに関する記憶を永続化するサーバーである（cachly.dev）。npmパッケージとして公開されており、npxコマンドによるセットアップが提供されている。個人開発者や小規模チームにとって導入の障壁を下げるための無料プランが提供されている点も注目される。

データはドイツのサーバーに保管され、GDPR準拠であることが明記されている。EU域外からアクセスする開発者にとって、データ主権とコンプライアンスの観点から、この点は実務上重要な判断材料になる。ただし、GDPR準拠であることは「データがEU域内に保管される」ことを意味するものであり、機密データの扱いについては別途評価が必要である。

アーキテクチャの核心は、単なるファイル検索やコードスニペットの保存ではなく、「開発者の意図」や「過去の失敗パターン」を構造化された教訓として保存することにある。AIエディタがコード変更を行う際にMCP経由で関連する教訓をリクエストし、cachlyサーバーはsemantic embeddingsを用いて意味的に類似した教訓を検索して返答する。変更が完了すると、その変更から得られた教訓を保存する。このリクエストと保存の往復が、セッションをまたいで記憶を継続させる仕組みの本体である。

flowchart LR
    A["AIエディタ"] -->|"MCP: 教訓リクエスト"| B["MCPプロトコル"]
    B --> C["cachlyサーバー"]
    C -->|"semantic embeddings検索"| D["教訓ストア"]
    D -->|"関連教訓"| C
    C -->|"教訓を返答"| B
    B --> A
    A -->|"MCP: 教訓保存"| B
    B --> C

この設計の意図を整理すると、cachlyは「検索エンジン」ではなく「学習した知識の保持層」として位置づけられている。RAGがコードの静的構造をインデックスするのに対し、cachlyが対象とするのはコード変更の背後にある動機と結果である。この違いが、後述する学習データ収集の設計に直結する。

学習データの自動収集：gitフックとブレスト初期化の仕組み

記憶サーバーの価値は、保存されている教訓の質と量で決まる。しかし、開発者が手動で「今日はこういう教訓を得た」と入力することを前提にすると、運用が継続しないリスクが高い。cachlyがこの問題を解決する手段として採用しているのが、gitのpost-commitフックによる自動学習である（実証実験レポート）。

具体的には、git commitが実行された際にpost-commitフックが発火し、コミットされた修正内容やリVERT（取り消し）が自動的にcachlyに送信される。リVERTは特に価値が高いシグナルであり、「この変更は失敗した」という否定的な教訓を自動的に捕捉できる。コードの変更履歴から「なぜこのように修正したか」「なぜ取り消されたか」という文脈を抽出し、構造化された教訓として保存する流れが、開発者の追加作業なしに回っていく。

sequenceDiagram
    participant Dev as 開発者
    participant Git as gitリポジトリ
    participant Hook as post-commitフック
    participant C as cachlyサーバー

    Dev->>Git: git commit
    Git->>Hook: フック発火
    Hook->>C: コミット内容・diffを送信
    C->>C: 教訓を抽出・構造化
    C->>C: 教訓ストアに保存
    C-->>Hook: 保存完了

もう一つの重要な仕組みが、初期セットアップ時のブレスト（思考の種）自動生成である。cachlyを初めて導入する際、git履歴から過去のコミットパターンを解析し、既存の教訓を自動的に抽出して初期化する。これにより、記憶サーバーが空の状態でスタートし、数週間かけて徐々に蓄積していくという「冷開始」の問題を回避できる。npxコマンドでセットアップが完了する構成と組み合わさることで、導入から最初の有効な教訓が参照可能になるまでの時間が大幅に短縮される。

ただし、自動収集には本質的な限界がある。gitのコミットメッセージやdiffからは、変更の意図が十分に読み取れない場合がある。例えば、コミットメッセージが「fix: bug」程度の内容しかない場合、どのようなバグが修正されたのか、その根本原因は何だったのかは推測に頼らざるを得ない。また、リVERTが「設計判断の変更」によるものか「単純なミス」によるものかを区別するロジックの精度にも依存する。このため、自動収集単体ではノイズが混入する可能性があり、後述する品質管理メカニズムとの併用が設計上不可欠である。

検索とマッチング：semantic embeddingsによるクロスラングージ対応

教訓が蓄積されてくると、いかに正確に「今必要な教訓」を抽出するかが効率的な運用を左右する。cachlyがこの問題に対して採用しているのは、semantic embeddings（意味的埋め込み）を用いたベクトル類似度検索である。テキストを数値ベクトルに変換し、コサイン類似度などで近いベクトルを抽出する手法であり、文字列の一致ではなく「意味の近さ」でマッチングを行う。

このアプローチがもたらす最も実用的な利点は、クロスラングージでのヒットである。例えば、Reactのステート管理に関する失敗パターン（「useEffectの依存配列を空にすると、コンポーネントの再レンダリング時に古い値が参照される」）が保存されている場合、Vueのリアクティブシステムに関する質問に対しても、概念的に類似した教訓として関連付けられる可能性がある。これはキーワード検索では原理的に実現できない。キーワード検索は「useEffect」や「React」という語が一致しなければヒットしないが、embeddingsは「ステート管理の副作用」という抽象的な概念レベルで対応付けを行う。

キーワード検索とのトレードオフ

しかし、semantic embeddingsには明確なコストが存在する。第一に、embeddingモデルへの推論コストが発生する。テキストをベクトルに変換するたびに計算リソースを消費し、教訓の規模が大きくなると検索レイテンシが線形に増加する傾向がある。第二に、embeddingモデルの質が検索精度の上限を決定する。モデルが特定のドメイン用語のニュアンスを十分に捉えられない場合、意味的に近いはずの教訓がヒットしない、あるいは無関係な教訓が上位に来るという失敗モードが生じる。

キーワード検索は計算コストがほぼゼロで、結果が再現性を持つという利点がある。一方、semantic embeddingsは柔軟性が高いが、結果がモデルのバージョンや設定に依存し、デバッグが難しい。実際の運用では、まずキーワードで候補を絞り、embeddingsで順位付けを再計算するハイブリッド手法が有効な場合がある。

小規模チームが自前でこの層を構築する場合、embeddingモデルの選定が最初の設計判断になる。オープンソースの多言語モデルを使うか、APIベースのサービスに委譲するかで、コスト構造とデータガバナンスの要件が大きく変わる。また、教訓のテキストが短すぎる場合（1〜2文程度）、embeddingの表現力が十分には発揮されず、キーワード検索と大差ない精度になることがある。教訓の記述粒度をある程度確保することも、検索品質を左右する運用上の注意点である。

記憶の更新戦略：上書きロジックと失敗パターンの扱い

教訓が蓄積されると、同じトピックについて新しい知見が得られるたびに、古い教訓と新しい教訓のどちらを信頼するかという問題が生じる。cachlyの設計では、教訓はトピックごとにキー付けされ、同じトピックで新しい教訓が得られると以前のテキストが上書きされる。つまり、各トピックには常に「最新の理解」だけが保持され、古いバージョンは履歴として退避される。

この単純な上書きモデルは、記憶の鮮度を保つ点では合理的である。古い情報が残ったままでは、AIが矛盾した文脈を参照して誤った提案を行うリスクがある。しかし、単なる上書きだけでは設計が不十分になる。ここで重要になるのが、失敗パターンの扱いである。

失敗記録の分離ロジック

cachlyの設計では、失敗した記録は既存の成功した教訓を上書きせず、空のスロットがある場合のみ占有する。具体的には、あるトピックに「こうすれば成功する」という教訓が既に存在する場合、新たに「こうすると失敗する」という記録が発生しても、その成功教訓は上書きされない。代わりに、別のスロットに失敗パターンとして格納される。

この分離が設計上不可欠な理由は、AIエージェントの行動判断に直結する。AIが「何をするべきか」と「何を避けるべきか」を区別して参照できるようにするためには、両者を同じスロットに混在させるべきではない。もし失敗パターンが成功パターンを上書きしてしまった場合、AIは「このアプローチは失敗する」という情報しか持たなくなり、本来有効な手法を提案できなくなる。逆に、成功パターンが失敗パターンを上書きしてしまうと、過去のミスを繰り返すリスクが高まる。

この「成功と失敗のスロット分離」は、実装上はトピックキーの設計に「成功/失敗」のディメンションを追加することで実現できる。例えば、トピックキーを「react:useEffect:dependency-array:success」と「react:useEffect:dependency-array:failure」のように分けることで、同じ技術的トピックでも別々のスロットとして管理する。この設計判断は、教訓の粒度が細かすぎるとスロット数が爆発的に増えるというトレードオフを持つため、トピックの粒度設計が運用上の重要なパラメータになる。

データガバナンスとライフサイクル：期限切れと履歴管理の設計

上書きロジックにより、教訓はトピックごとに最新バージョンが保持される。しかし、上書きされた古いバージョンも完全に削除するわけではなく、履歴としてデータストアに保存される場合がある。実証実験では、データストアに過去638件の上書き済みバージョンが蓄積されていたという事例が報告されている。これは6週間という短期間での数字であり、教訓の更新頻度が想像以上に高いことを示唆している。

一方で、これらの履歴には90日後に期限切れとなるというTTL（生存期間）が設定されている場合がある。一定期間を経過した履歴は自動的に削除され、データストアのサイズが無限に増大することを防ぐ。この「忘却」のメカニズムは、単なるストレージコストの削減策ではない。古い教訓は文脈の変化とともにノイズとなり得るため、意図的に削除することで、検索結果の鮮度を維持する設計判断であると考えられる。

stateDiagram-v2
    [*] --> 新規作成 : 教訓の初回保存
    新規作成 --> 保存中 : トピックキーに格納
    保存中 --> 保存中 : 検索・参照
    保存中 --> 上書き : 同トピックに新教訓
    上書き --> 保存中 : 最新バージョンが有効
    上書き --> 履歴退避 : 旧バージョンを退避
    履歴退避 --> 期限切れ : 90日経過
    期限切れ --> [*] : 自動削除

90日というTTLの設計根拠とチーム適用時の考慮

90日という期間は、開発プロジェクトのライフサイクルと整合させるための実務的な判断と推測される。多くのソフトウェアプロジェクトでは、1〜3ヶ月で技術スタックや設計方針が変更されるため、それ以前に記録された教訓は文脈が陳腐化している可能性が高い。逆に、90日以内であれば、同じプロジェクトの文脈が維持され、教訓の妥当性が高いと見なせる場合がある。

小規模チームがこの設計を適用する際、TTLの値をどう設定するかが運用上の重要な判断材料になる。30日に短くすると、教訓の蓄積が追いつかないうちに削除され、記憶の厚みが不足する可能性がある。180日に長くすると、陳腐化した教訓が検索結果に混入し、AIの提案品質が低下するリスクがある。適切な値は、チームのプロジェクトサイクル（スプリントの長さ、技術スタックの変更頻度）に依存する。

また、履歴の保持件数にも上限を設けるべきであるという指摘もある。638件という数字は単一ユーザー・6週間での値であり、チーム規模で数ヶ月運用すれば数千件に達する可能性がある。履歴はデバッグや教訓の進化を追溯するために有用だが、検索の主要パスには載せない設計（検索対象は最新バージョンのみ、履歴は管理用のアーカイブ）にすることで、検索性能とストレージコストのバランスを取るのが現実的なアプローチであると考えられる。

リスク警告機能：brain_predictによるデプロイ前チェック

メモリサーバーの役割は、リクエストに応じて関連する教訓を返す「受動的検索」に限定されない。cachlyには brain_predict という機能があり、デプロイ前に過去の失敗パターンをスキャンしてリスクを警告する可能性がある（cachlyの公式サイト）。これは、AIエージェントが「今やるべきこと」を提示するだけでなく、「この操作は過去に失敗したことがある」という能動的なガードレールとして機能し得る例である。

ガードレールとしての設計意図

従来のCI/CDパイプラインでは、静的解析やテストがコードの「構造的な正しさ」を検証する。一方、brain_predict が検出するのは「構造的には正しいが、このコードベースの文脈では過去に問題を起こした」というパターンである場合がある。例えば、特定のリファクタリングがプロダクションで障害を引き起こした履歴があれば、次回同じパターンが検出された時点でデプロイ前に警告を発する可能性がある。これはテストがカバーできない「経験則的なリスク」に対する防御層として機能し得る。

この機能を有効に活用するには、前提条件が2つある。第一に、過去の失敗データが十分に蓄積されていることである。教訓が数件しか存在しない段階では、スキャンのヒット率が低く、警告の信頼性も限定的になる。第二に、失敗パターンの記録が「何が起きたか」だけでなく「なぜ失敗したか」を含む構造化された形式で保存されていることである。単純なエラーメッセージの蓄積では、文脈の異なる類似パターンまで誤検出される可能性がある。

品質保証プロセスへの組み込み方

実務的に組み込む場合、brain_predict の出力をデプロイゲートの「必須条件」にするのではなく、開発者へのアドバイスとして提示する形が現実的である。警告をブロックとして機能させると、誤検出時に開発フローが停滞する可能性がある。代わりに、警告の履歴を蓄積し、どの警告が実際に問題に繋がったか（true positive）を定期的に分析することで、警告の信頼性を段階的に向上させるフィードバックループを回すのが有効であると考えられる。

小規模チームが同様の機能を自前で構築する場合、gitのpre-deployフックやCIのステージにLLMを呼び出すステップを追加する形が考えられる。ただし、この場合のレイテンシ（LLMの応答待ち時間）がデプロイパイプラインのボトルネックになり得るため、非同期で警告を通知する設計や、キャッシュを活用して応答時間を短縮する工夫が必要になる。

実証結果：6週間の単一ユーザーテストで確認された効果と限界

開発者は6週間の単一ユーザーテストを実施し、記憶サーバーが同じミスの繰り返しを防ぐことを数値で確認したという報告がある（開発者のDev.to記事）。このテストの価値は、実環境での定量的な検証がなされた点にある。メモリサーバーが「理論上は有用」ではなく、実際に開発フローの中で効果を発揮するかを、一人の開発者のワークフローで検証したものである。

確認された効果の構造

効果が確認された背景には、以下のような構造がある。AIエディタへのプロンプトは毎回ゼロから文脈を構築する必要があるが、メモリサーバーが存在することで、過去の教訓が自動的にコンテキストに注入される場合がある。これにより、開発者が「前回このパターンで失敗したから、今回はこうする」という指示を毎回繰り返す必要がなくなる可能性がある。AIアシスタントとの対話効率が向上するのは、この「暗黙知の自動補完」が機能しているためであると考えられる。

ただし、この検証は単一ユーザー・単一プロジェクトのスコープに限定されている。テスト期間中の技術スタックの変化が少なかった場合、教訓の鮮度が高く、検索のヒット率も高かった可能性がある。プロジェクトの技術スタックが頻繁に変わる環境では、同じ教訓がすぐに陳腐化し、効果が薄れる可能性を排除できない。

チーム規模への外挿の限界

個人利用とチーム利用で根本的に異なるのは、「教訓の所有者」が複数になる点である。個人利用では、教訓の品質は一人の開発者の判断で担保される。しかしチームでは、Aが「このパターンは危険」と記録した教訓を、Bが「この文脈では問題ない」と判断する競合が発生し得る。このコンフリクトをどう解決するか（多数決、権限による優先順位付け、文脈条件の付与など）は、単一ユーザーテストでは検証されていない。

小規模チーム（1〜5名）では、教訓の競合が起きる頻度が低く、個人利用と近い挙動が期待できる場合がある。しかし5名を超えると、教訓の「正しさ」を誰が判断するかのガバナンス設計が不可欠になる。組織的なナレッジベース化（全社共通のベストプラクティス文書のようなもの）とは、スケーリングの方向性が異なる点に注意が必要である。

小規模チームへの適用：導入のハードルと運用上の落とし穴

cachlyはnpmパッケージとして提供され、npxコマンド一つでセットアップが完了する構成を採用している（cachlyの公式サイト）。導入コストが低いことは事実だが、自前ホストやカスタマイズを検討する場合、技術的負荷は相当に高くなる可能性がある。以下に、クラウドサービス利用とローカル自前ホストの比較を示す。

自動学習への過剰依存と品質管理

gitのpost-commitフックによる自動学習は強力だが、コミットメッセージが不十分だったり、意図しないリVERTが含まれたりする場合、誤った教訓が蓄積されるリスクがある。例えば、緊急時のホットフィックスが「教訓」として学習され、後からリファクタリングで撤回された場合、一時的な対応が永続的なベストプラクティスとして残り得る。これを防ぐには、週次で教訓のリストをレビューし、不要なものを手動で削除するプロセスを運用に組み込む必要がある。レビューの負荷を考えると、教訓の総数を一定の範囲に収める設計（TTLや件数上限）が重要になる。

データ配置とプロトコル標準化の課題

社内機密データ（顧客情報の処理ロジック、未公開のアルゴリズムなど）を含むコードベースの場合、データを外部サーバーに送信すること自体が許容できないことがある。cachlyのデータはドイツのサーバーに保管されGDPR準拠であることが明記されている場合がある（cachlyの公式サイト）が、これでも社内ポリシー上問題になる場合がある。その場合、自前ホストへの移行が必要になるが、その際の手間やカスタマイズの複雑さを事前に評価しておくとよい。

もう一つの課題は、MCPプロトコル自体の標準化が進行中の段階である点である。現在は主要なAIエディタ（Claude Code、Cursor、Copilotなど）と連携可能だが、プロトコルの仕様が変化した場合、メモリサーバー側の対応が求められる。ツール間の互換性が確立するまでの間は、特定のMCP実装にロックインされるリスクを認識した上で、データのエクスポート・インポート手段を確保しておくことが、将来の移行コストを軽減する現実的な対策であると考えられる。

まとめ：軽量記憶層が拓くAI開発支援の未来

本記事では、cachlyというMCPメモリサーバーの実装事例を通じて、小規模チームがAIエージェントに「記憶」を付与するための設計パターンを整理してきた。抽出された主要な設計判断を振り返ると、以下のような点が浮かぶ。

第一に、自動学習と品質管理のバランスである。gitフックによる自動収集は開発者の負担を減らす一方、定期的なレビュープロセスとの併用が不可欠である。第二に、検索戦略の選択である。semantic embeddingsによるクロスラングージ対応は強力だが、計算コストとのトレードオフを理解した上で、チームの規模と用途に合った方式を選ぶ必要がある。第三に、記憶のライフサイクル管理である。TTLや上書きロジック、失敗パターンの分離保存といった設計は、記憶の「鮮度」と「厚み」を両立させるための基盤となる。

これらのパターンは、cachlyという特定のツールに依存するものではなく、MCPプロトコルやsemantic embeddingsの技術的な制約下で導き出された、一般的な設計原則として読み替えることができる。小規模チームが自前の軽量な記憶層を構築する場合、これらの判断基準を起点に、自チームのプロジェクトサイクルやデータポリシーに合わせた設計を行うことが可能である。

今後は、MCPプロトコルの標準化が進むことで、異なるメモリサーバー間のデータポータビリティが向上し、ツール変更時の移行コストが低下することが期待される。また、チーム規模に応じた教訓の競合解決メカニズムや、組織的なナレッジガバナンスとの統合方法については、さらなる実証と議論が必要である。軽量な記憶層は、AI開発支援の「必須インフラ」になりつつあるが、その価値は導入した瞬間に最大化されるのではなく、運用の中で教訓の品質が磨かれていく過程で漸次高まっていくものである。

関連記事

• AIエージェントの暴走を防ぐ：while(true)ループの限界とEventStoreによる状態管理の実践
• AI時代の「中級エンジニアの消滅」と技術的負債：エージェント活用における品質保証の設計思考
• AI生成コードの信頼性を担保する「メンテナンスレシート」の考え方

参考

本記事は海外の技術トレンド「I built an MCP memory server for one user (me, for six weeks)」（DEV）で話題のテーマをもとに、両儀システムソリューションズが独自に解説したものです。