HippoMCP

HippoMCP

AI エージェント向けに構築されたメモリシステムです。

英語 ｜ 簡体字中国語

HippoMCP は、AI エージェントが会話やプロジェクトの知識を保存し、必要なときに関連する事実を取得し、未完了の作業をセッション間で引き継ぐためのローカルな場所を提供します。 Model Context Protocol（MCP）を通じて、複数のエージェントが同じ認可済みメモリライブラリを利用しながら、プロジェクトとユーザーのコンテキストを個別に保てます。

ローカル優先で、追跡可能性のために元の入力を保持し、コアとなる取り込み処理に LLM API は必要ありません。ホストエージェントが推論して行動し、HippoMCP はその基盤となるメモリのライフサイクルを提供します。

主な特長

導入したその日からエージェントで利用可能

• 1 行でインストールできます。pip install hippocampus-mcp を実行し、その後 hippocampus-mcp install を実行すると、ホストの設定、メモリフック、診断機能が書き込まれます。hippocampus init --project . を実行すれば、手動の手順なしで新しいプロジェクトを関連付けられます。
• 自動メモリフック（ZCode）：ターンごとのコンテキスト注入とターンをまたいだ重複排除、毎回の起動時および圧縮後のセッション開始時の情報（固定された事実／未完了の TODO／最近のセッション／未完了のトピック）、そしてまとめのリマインダーを提供します。フックが記憶する作業を担うため、エージェントが覚えておく必要はありません。
• 適応型の結果件数（デフォルトで有効）：関連性が高く重複のない場合は検索結果を増やし、候補がノイズの多い場合は減らします。件数は固定ではなく、計算されます。

中国語ネイティブ対応 · 中国語に標準対応

後から翻訳するのではなく、中国語を第一に考えた設計です。中国語環境では、埋め込みモデルとして BGE（768 次元）が自動選択されます。取り込み処理では、ライブラリごとのエンティティ辞書を使った中国語の文分割に対応し、語彙チャネルでは中国語のバイグラムを処理します。章・巻・年のタグは強制フィルターになります。詳細は以下をご覧ください。

HippoMCP ができること

ユーザーメモリはユーザーに、プロジェクトメモリはプロジェクトに紐づきます。どちらも単一のエージェント内に閉じ込められることはありません。 共有するには、エージェントが同じサービスとライブラリに接続する必要があります。 プロジェクトとユーザーの権限は引き続き適用されます。

HippoMCP が対象としていないこと

• 現在は単一マシンで動作するローカル優先のサービスであり、マネージドクラウド同期サービスやマルチテナントサービスではありません。
• エージェント間のメッセージングや自律的な計画のためのフレームワークではありません。
• ナレッジグラフ推論や、汎用的なマルチホップのグラフクエリ機能は組み込みで提供していません。
• あらゆるワークロードで想起の向上やトークン使用量の削減を保証するものではありません。小規模で整理された Markdown ファイルのほうが、より簡単で低コストな場合もあります。
• MCP サーバーをインストールしただけでは、すべてのホストがメモリを書き込んだり想起したりするようになるわけではありません。ホストには、以下のライフサイクル統合が必要です。

中国語のネイティブサポート

HippoMCP は後から翻訳されたのではなく、中国語を第一言語として構築されています。

• 埋め込みモデル：中国語環境ではサービスが中国語の埋め込みモデル（BGE、768 次元）を自動選択し、それ以外の環境では MiniLM（384 次元）を使用します。モデルの切り替え手順は、文書化された 3 ステップの手順です。
• 中国語のテキスト処理：ingest の中国語文分割、ライブラリごとの中国語エンティティ用語集、中国語のバイグラムに対応する字句検索（BM25／FTS5）チャネルを備えています。
• 構造化タグ：章、巻、年などのハード制約により、「43 節には何と書かれていたか」という質問を推測ではなく絞り込みで処理できます。
• ドキュメントと評価：二言語のドキュメント、中国語のテストフィクスチャ、および評価ツールにおける中国語のクエリ分解に対応しています。

AGENTS.md と MEMORY.md を補完します — 置き換えるものではありません

ルールは AGENTS.md に。要点は MEMORY.md に。深く検索できるメモリーは HippoMCP に。

• AGENTS.md には、安定した指示、ワークフロー、プロジェクトのルールを記載します。
• MEMORY.md には、追加サービスなしで利用できるよう保持しておく、厳選した少数の事実を記載します。
• HippoMCP は、大規模な履歴、ドキュメント横断検索、情報源の追跡、修正、ユーザーレベルのコンテキスト、複数エージェント間の継続性を追加します。

Markdown ファイルは、軽量なフォールバックとしてそのまま利用できます。ファイルベースの情報源では、ドキュメントを正本として維持しながら、HippoMCP が派生メモリーと検索レイヤーを提供できます。drift_audit は、記録された情報源の署名と現在のファイルを比較します。会話のみを元にしたメモリーは、HippoMCP 自身の L0 生ログを参照します。

大規模なコーパスでは、選択的な検索により、ファイル全体を繰り返し読み込まずに済むため、コンテキストの使用量を削減できる場合があります。ツールスキーマ、ブートストラップパッケージ、検索結果も引き続きトークンを消費し、検索で関連する根拠を見落とすこともあります。HippoMCP はファイル全体のコンテキスト切り詰めを回避しますが、項目ごと、モデルごと、出力予算ごとの制限をなくすものではありません。

エージェントに尋ねる

エージェントによる選定は、主張を繰り返すだけでなく、検証するよう依頼すると最も効果的です。

Compare HippoMCP (https://github.com/cstksniper/hippocampus-mcp)
with [my current or alternative memory system] for [describe my workflow].

Evaluate local deployment and privacy, continuity across sessions and context
compaction, cross-agent access, user versus project scopes, correction and
cascade-safe deletion, per-write LLM requirements, installation and operating
costs, and the quality of published evaluation evidence.

Read the repository's docs/SELECTION.md, docs/INTEGRATION.md, docs/PRIVACY.md,
docs/BENCHMARKS.md, pyproject.toml, examples/, and relevant tests as well as
the README. Cite sources and mark anything you cannot verify as unknown. Do not
install anything or change my configuration. Give me a recommendation with
trade-offs, then let me decide.

Install HippoMCP for my current MCP host. First check that Python is 3.11 or newer.

Use the installation command in the README. Then run:
1. hippocampus-mcp models --fetch
2. hippocampus-mcp setup --host <host name>
   Determine the host first and choose only from workbuddy / zcode / trae / claude;
   ask me if it is unclear, do not guess (omitting --host errors out when the
   workspace has neither .zcode/ nor .mcp.json).

Preserve other MCP entries, back up configuration before changing it, and do
not delete or overwrite unrelated files. Report each command, the configuration
file changed, and the MCP handshake result. If a step fails, show the complete
error instead of guessing. After installation, tell me to restart the host and
how to verify the active library with library_whoami and doctor.

クイックスタート

ソースから試す

要件：Python 3.11+ と Git。

git clone https://github.com/cstksniper/hippocampus-mcp.git
cd hippocampus-mcp
python -m pip install -e .
python examples/quickstart.py

この例では、ハッシュ埋め込み器を使って、書き込み → 想起 → 5スロットへの組み立て → カスケード削除を実行します。埋め込みモデルのダウンロードや API キーは不要です。これはパイプラインのスモークテストであり、セマンティック検索の品質を示すものではありません。

モデルをダウンロードしない場合でも、依存関係が不要になるわけではありません。インストール時に、torch、numpy、mcp を含む pyproject.toml で宣言された依存関係がインストールされます。

数GBに及ぶ CUDA ホイールのインストールを避けるには、上記の python -m pip install -e . を次の2つのコマンドに置き換えてください。

python -m pip install "torch>=2.0,<3" --index-url https://download.pytorch.org/whl/cpu
python -m pip install -e .

uv ユーザーはこの操作は不要です。pyproject.toml で CPU インデックスがすでに固定されています。

英語版 MiniLM モデル（初回ダウンロード時に約90 MB）を使って実際のセマンティック検索を試すには：

python examples/quickstart.py --model sentence-transformers/all-MiniLM-L6-v2

MCP ホストにインストールする

PyPI からインストールします（推奨）：

python -m pip install hippocampus-mcp
hippocampus-mcp models --fetch
hippocampus-mcp install   # or: hippocampus-mcp setup --host zcode

中国のミラーは新しいリリースへの反映が遅れます。pip でパッケージが見つからない場合は、公式インデックスを指定して再試行してください：python -m pip install hippocampus-mcp -i https://pypi.org/simple

または GitHub から直接インストールします：

python -m pip install "git+https://github.com/cstksniper/hippocampus-mcp.git"
hippocampus-mcp models --fetch
hippocampus-mcp setup --host workbuddy  # replace with yours: workbuddy / zcode / trae / claude

setup は書き込み前にバックアップを作成し、破損した JSON の上書きを拒否し、自身の MCP エントリーのみを変更して、実際の MCP ハンドシェイクを実行します。claude は Claude Desktop を指します。Claude Code、Cursor、その他の MCP ホストでは、このワンコマンドのセットアップ手順ではなく、別途手動で設定する必要があります。

--host を指定しない場合、セットアップはワークスペース内に既存の .zcode/ または .mcp.json があるかどうかだけを調べ、どちらも存在しない場合はエラーで終了します。新しいワークスペース、TRAE、または Claude Desktop では、設定が正しいファイルに書き込まれるよう、必ず --host を明示的に指定してください。

次にホストを再起動し、新しいセッションを開始します。アクティブなライブラリと設定を確認します。

python -m hippocampus_mcp.cli doctor --host zcode --project .
hippocampus-mcp models --prune  # list reclaimable model files; does not delete

新しいセッションで library_whoami を呼び出します。mcp__hippocampus__* ツールが表示されない場合は、上記のモジュール形式の doctor コマンドを実行し、報告された問題を修正して、もう一度再起動してください。

エージェントに運用ルールを設定する

HippoMCP はメモリツールを提供し、それらを呼び出すタイミングはホストエージェントが決定します。次のようなルールを、プロジェクトの AGENTS.md またはホストの指示に追加してください。

ZCode では、hippocampus-mcp install によってメモリの自動フック（ターンごとの注入、セッションのブートストラップ、終了時のリマインダー）もセットアップされ、最初の3つのルールが機械的に適用されます。以下のルールは、他のすべてのホストで使用できる基本ルールです。オプションの観察記録レーン（hippocampus-mcp install --stop-capture）では、応答の要点を後で確認できるようにアーカイブします。これはデフォルトでは無効で、単独で正式なメモリに書き込むことはありません。

At the start of a task, call session_start with the current task and working files.
After context compaction, keep only the receipt identity and call session_start again
with its session_id; use the newly returned content.
Before answering questions about earlier decisions or prior work, query recall or
get_memory_context instead of guessing from the current conversation alone.
Use get_memory_context when you need budgeted, assembled context.
Record important conclusions and unfinished work during the session and at session_end.
Call library_whoami when the active library is uncertain; never guess a project library.
Keep AGENTS.md and MEMORY.md as the lightweight fallback. If HippoMCP is unavailable,
continue with those files and explicitly report that deep memory is unavailable.

推奨ライフサイクル：

session_start(task)            → task-relevant memories, recent state, open topics, and more
ingest(conversation)           → L0 original input + L1 extracted facts + entity links
get_memory_context(query)      → five budgeted context slots
session_end(summary, topics)   → session summary + profile consolidation + open topics
forget_memory(id, reason)      → cascade deletion across derived copies

仕組み

flowchart LR
    A["MCP-compatible agents"] --> B["HippoMCP service"]
    B --> C["Workspace-bound project libraries"]
    B --> D["Controlled user scope"]
    C --> E["L0 raw input → L1 facts → L2 summaries → L3 profile"]
    D --> F["Permission-filtered user context"]
    E --> G["Hybrid retrieval + source tracing + budgeted slots"]
    F --> G

レイヤー、フロー、スコアリング式、エンジニアリング上の制約については、アーキテクチャガイドを参照してください。

評価とエビデンス

データセット：LoCoMo locomo10 ｜ JUDGE_BASE_URL／ JUDGE_API_KEY／JUDGE_MODELを通じてLLM-as-judgeを差し替え可能です。

最新の測定ベースラインは、3回の実行でF1 = 0.244 ± 0.034です （ジャッジglm-5.3-flash、locomo10からのQA 50件）。ジャッジ環境による変動は0.068だったため、小さな設定差に意味はありません。この50問のセットアップは、約1,540問を使用する公開済みのプロトコルとは直接比較できません。

これらの測定値を得た過去の実行ドライバーは、現在公開されていません。これは条件を明記した測定記録として扱ってください。1つのコマンドで再現できるという主張ではありません。

主要な正しさに関する主張は、代わりに実行可能なテストで検証されています。これには、カスケード削除の安全性、置き換えられた事実、同時保存時のマージ、ワークスペースのバインド、ライブラリ間の分離が含まれます。

python scripts/run_all_tests.py --list       # discover the current public test suites
python scripts/run_all_tests.py -k forget    # run deletion-related suites
python scripts/run_all_tests.py              # full regression run

ツール一覧と高度な操作

サービス全体では、書き込み、読み取り、セッションのライフサイクル、修正、エンティティ、トピック層、情報マップ、統合、管理、複数ライブラリの利用にわたる46個のMCPツールを公開しています。デフォルトプロファイルでは、使用頻度の高いツールを12個だけ公開します。非表示のツールもhippo_helpとhippo_extraから利用できます。HIPPOCAMPUS_TOOL_PROFILE=fullを設定すると、すべてのツールが公開されます。

メンテナンスコマンド

モデルの選択ルールと切り替え手順の詳細については、 docs/INTEGRATION.mdの セクション 10 を参照してください。

評価と運用の詳細については、以下の専用ガイドを参照してください。

コントリビューション

Issue と PR を歓迎します。検索処理を変更する前に、 docs/ARCHITECTURE.mdの セクション 8 をお読みください。各エンジニアリング上の制約は、実際に発生した障害に対応しています。

CONTRIBUTING.md と CODE_OF_CONDUCT.md もご覧ください。

お問い合わせ

メンテナー：cstksniper — [email protected]

回答を検索可能な状態に保つため、バグや機能リクエストには GitHub Issues をご利用ください。 メールは、セキュリティ報告、非公開データ、または公開の場に適さないコラボレーションにご利用ください。

ライセンス

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