Enhanced Memory MCP Server

Model Context Protocol を介した、AIエージェントのための永続的かつ検索可能なメモリ。エンティティとその観測結果は、チェックサムとバージョン履歴を持つ圧縮SQLiteデータベースに保存されます。その上に階層型ストアとマルチストラテジ検索パイプラインが構築され、全体がMCPツールとしてクライアントに公開されます。

ツールの数はインストール内容に依存し、その差はバグではありません。バックエンドがないツールは単に登録されません。コアインストール（requirements.txt）では186個が登録され、オプションのバックエンド（requirements-optional.txt）を追加すると204個になります。pip install -r requirements.txt のみ実行して186個だった場合、何も壊れていません。

どちらの数値も、AGENTIC_SYSTEM_PATH が未設定の状態で、Python 3.11.11 上で stdio 経由の tools/list を用いて測定されました。この最後の条件は細かい話ではありません。その変数が GraphRAG で説明されている別個のシステムを指している場合、さらに7つのツールが登録され、代わりに193個と211個になります。このファイルの初期ドラフトでは188個と206個と記載されていましたが、これはその変数がエクスポートされたマシンで測定されたためであり、私たち2人がその原因に気づかず同じ誤った数値を再現していました。再測定する前に、変数を未設定にしてください。

コア機能はすべてローカルで動作し、APIキーやネットワークは不要です。オプションのベクタースタック（Qdrant + ollama）は、キーワードマッチングによる検索から意味ベースの検索へとアップグレードします。これがない場合も、正常に機能低下し、壊れることはありません。

最初に知っておくべきこと

これは2つのプロセスであり、1つではありません。 このプロジェクトに関するサポート質問のほとんどは、その半分だけを実行していることに起因します。

   your MCP client  (Claude Code, Claude Desktop, an SDK, curl)
            |
            |   stdio JSON-RPC, one server process per client session
            v
   +-------------------------------------------------------+
   |  MCP server            server.py                       |
   |  start with            setup/bin/mcp-server.sh          |
   +-------------------------------------------------------+
            |
            |   JSON over a Unix socket: $MEMORY_DB_SOCKET_PATH
            |   (default /tmp/memory-db.sock)
            v
   +-------------------------------------------------------+
   |  memory-db daemon      memory_db_service.py            |
   |  start with            setup/bin/memory-db-daemon.sh    |
   |  REQUIRED. Owns the database file exclusively so that   |
   |  several clients can share it without corrupting it.    |
   +-------------------------------------------------------+
            |
            v
     memory.db   (SQLite, default ~/.claude/enhanced_memories/)


   optional, off to the side:
     Qdrant  http://localhost:6333    vector index for semantic recall
     ollama  http://127.0.0.1:11434   local embeddings that feed that index

デーモンは必須であり、MCPサーバーによって自動起動されることはありません。デーモンがない場合、サーバーは起動し、応答し、以下のようなオブジェクトを返します：

{"query": "anything", "count": 0, "results": [],
 "error": "Memory-DB service error: [Errno 2] No such file or directory"}

{"error": "Memory-DB service error: ...", "entities": {"total": 0},
 "compression": {"ratio": "N/A"}}

整形式で、パース可能で、空です。それを読んだエージェントは、メモリが空であると結論づけ、メモリが機能していないとは判断しません。この2つを区別するために ./healthcheck.sh が存在します。

Related MCP server: Strata Memory MCP Server

前提条件

• Python 3.11 以上。一部のmacOSマシンでは、python3 だけだと3.9のままなので、インストーラーはまずバージョン指定された名前を探します。

• git、およびvirtualenv用のディスク容量。macOS arm64 + Python 3.11 で測定：コアインストールで 83 MB、オプションのバックエンドを含めると 964 MB（sentence-transformers と torch をプルするため）。Linux x86_64 ではコア部分は 131 MB（python:3.11-slim コンテナ内で測定）— ホイールはプラットフォームによって異なるため、その数値は環境に応じて変わります。チェックアウト自体は 5 MB です。

• オプション：podman または docker（コンテナパスまたはローカルの Qdrant が必要な場合）。

• オプション：ローカル埋め込み用の ollama。

どの時点でも sudo は必要ありません。システム全体にインストールされるものはありません。

enhanced-memoryシステムを既に実行していますか？

このマシンにすでにシステムが存在する可能性がある場合、以下のステップ2の前にこれを読んでください：古いチェックアウト、2番目のクローン、数ヶ月前にインストールしたサービスなど。デフォルトでは、すべてのインストールは同じ2つのもの — ソケット /tmp/memory-db.sock とデータベース ~/.claude/enhanced_memories/memory.db — を必要とし、これらは共有できません。

まず確認：

lsof /tmp/memory-db.sock        # macOS or Linux
ss -xl | grep memory-db.sock    # Linux
pgrep -af memory_db_service.py

リストされたものは、インストールが動作中であることを意味します。占有されたソケットで2番目のデーモンを起動しようとすると拒否されます：ゼロ以外の終了コードで終了し、ソケットパスと応答しているデーモンが使用しているデータベースを表示します。ソケットを奪い取ることはありません。これは防御策であり、共存ではありません。2番目のデーモンはまったく実行されません。

2つのインストールを並行して実行するには、このインストールに .env で独自の設定をすべて与えてください：

ENHANCED_MEMORY_DIR=/home/you/.enhanced-memory-second
MEMORY_DB_SOCKET_PATH=/tmp/memory-db-second.sock
# Only if you want the Neural Memory Fabric somewhere else again; by default it
# follows ENHANCED_MEMORY_DIR:
# NMF_SQLITE_PATH=/home/you/.enhanced-memory-second/nmf.db
# NMF_FILES_ROOT=/home/you/.enhanced-memory-second/nmf_files

ENHANCED_MEMORY_DIR は忘れられがちです。1つの memory.db を共有する2つのソケット上の2つのデーモンは、共存ではありません。それは1つのファイルに対する2つの排他的な所有者であり、まさにデーモンが防止するために存在するものです。

クイックスタート

git clone <this-repo> enhanced-memory-mcp
cd enhanced-memory-mcp

# 1. venv, dependencies, .env, database directory. Idempotent, re-runnable.
setup/setup.sh

# 2. start the daemon (foreground). Leave it running, or install it as a
#    background service: setup/service/install-services.sh
setup/bin/memory-db-daemon.sh &

# 3. prove the install works before you trust it
./healthcheck.sh

正常な実行は Required checks passed. と終了コード0で終わります。それ以外は実際の問題です：トラブルシューティングを参照してください。

設定は .env に保存されます。ステップ1は、.env が存在しない場合のみ .env.example から .env を作成します。そのファイルを編集することが設定を永続化する方法です；setup/setup.sh を再実行しても上書きされることはありません。

次に、MCPクライアントにサーバーを登録します。~/.claude.json 内：

{
  "mcpServers": {
    "enhanced-memory": {
      "command": "/absolute/path/to/enhanced-memory-mcp/setup/bin/mcp-server.sh"
    }
  }
}

クライアントは ランチャー を指し、python server.py を直接指さないでください。ランチャーはこのチェックアウトの .env を適用し、それがMCPサーバーとデーモンが同じデータベースファイルを解決することを保証します。クライアントが直接 python を実行すると、そのクライアントがたまたま持っていた環境のみを継承し、2つのプロセスは静かに乖離します。スプリットブレイントラップを参照してください。

この時点でインストールは完了し、ツールは呼び出されると動作します。しかし、何も自動的には呼び出しません。すべてのセッションはコールドスタートし、エージェントが選択しない限り何も書き戻されません。それは障害ではなく、どのチェックもそれを報告しないため、動作するインストールと動作するメモリを混同しがちです。docs/AUTOMATION.md では、そのギャップを埋める方法について説明しています。最初に、すべてのプロンプトで実行されるリコールフックについて説明します。

代替案：1つの共有HTTPサーバー

stdioは、クライアントセッションごとに1つのサーバープロセスを生成します。これはデスクトップクライアントが期待する動作です。代わりに、HTTP経由で1つの共有サーバーを実行する場合は、SSEトランスポートを使用します：

MCP_TRANSPORT=sse setup/bin/mcp-server.sh     # or setup/bin/mcp-server-sse.sh

{
  "mcpServers": {
    "enhanced-memory": { "type": "sse", "url": "http://127.0.0.1:9106/sse" }
  }
}

そのポートには認証はありません。MCP_HOST は 127.0.0.1 のままにしてください。

設定

設定は環境変数です。setup/setup.sh は .env.example から .env を書き込み、すべての設定をインラインで文書化します。.env の編集が永続的な仕組みです：コピーは .env が存在しない場合にのみ行われるため、編集内容はインストーラーの再実行後も保持されます（同じ理由で、新しいリリースのデフォルトは自動的に適用されません — アップグレード後は2つのファイルを比較してください）。環境ですでに設定されている変数は、その1回の呼び出しにおいてファイルよりも優先されます：

MEMORY_DB_SOCKET_PATH=/tmp/other.sock ./healthcheck.sh

ENHANCED_MEMORY_SURFACE と MEMORY_PROFILE は両方とも tools/list が返すツール数を変更し、インストールされているオプションの依存関係も同様です。バックエンドが欠落しているツールは登録されません。コアのみのインストールとオプションの追加機能があるインストールでは、同じコードでも異なるカウントが報告されます。期待されるツール数は、これら3つすべての隣でのみ意味を持ちます。

オプションのサービスと、それらがない場合に失うもの

どちらも必須ではありませんが、両方とも持つ価値があります。

どちらかまたは両方をプロビジョニングします：

setup/setup.sh --with-qdrant     # container on 127.0.0.1:6333, named volume
setup/setup.sh --with-ollama     # verifies ollama, pulls the embedding model

./healthcheck.sh は両方をOPTIONALとして報告し、それらがないことでゲートに失敗することは決してありません。より厳格な契約が必要な場合は --require-optional を渡してください。

すでにQdrantを実行していますか？ MEMORY_QDRANT_URL をそこに向け、--with-qdrant を完全にスキップしてください。ここでインスタンスを所有する必要はありません。以下のコンテナプロファイルで説明するポートの競合は、そのプロファイルに固有のものです。そのプロファイルは自身のコンテナを6333で公開し、他の何かがすでに保持しているポートをバインドできません。ホストインストールはアウトバウンドリクエストのみを行います。

GraphRAGはオプションであり外部です

GraphRAGツール（graph_enhanced_search、get_entity_neighbors）はここに出荷されません。graphrag_tools.py はその実装を $AGENTIC_SYSTEM_PATH/scripts/graph-rag.py からロードします。これは別のシステムに属するファイルであり、このパッケージの一部ではありません。AGENTIC_SYSTEM_PATH はデフォルトでチェックアウトの親ディレクトリの親を指すため、スタンドアロンインストールではそのパスは存在しません。

何も壊れません。登録はラップされており、サーバーは GraphRAG integration skipped: ... をログに記録し、それらのツールなしで起動します。そのシステムがある場合は、AGENTIC_SYSTEM_PATH をそのルートに向ければ、それらが登録されます。スキップメッセージはターミナルではなくログファイルに送られるため、存在しないツールは最初からなかったツールのように見えることに注意してください。

コンテナでの実行

共有環境への配信パス。Podmanが優先、dockerと互換性あり。

podman-compose up --build                              # core only
WITH_OPTIONAL=1 podman-compose --profile qdrant up     # with a USABLE vector store

WITH_OPTIONAL=1 はqdrantプロファイルでは重要です。 デフォルトのイメージは requirements.txt のみをインストールします。これには qdrant-client が含まれていません。そのため、--profile qdrant をそれなしで使用すると、正常で到達可能な、完全に使用されないQdrantが提供されます。ヘルスチェックはサービスが到達可能である（真）と報告する一方、サーバーは「qdrant-client not installed - vector search disabled」をログに記録し、すべての検索は字句のままです。不活性な機能の横にある緑色のシグナルは、まさにこのプロジェクトが排除するために存在する障害モードであるため、ここで名前を付けて、あなたが見つけるために残されているのではありません。WITH_OPTIONAL=1 は requirements-optional.txt でイメージを構築し、ベクターパスが実際に機能します。（測定値：qdrantプロファイルと並んだコアイメージは /readyz に「all shards are ready」と応答し、それを何にも使用しませんでした。）

ハイフンを使用してください。Fedora 44では、podman compose（スペース）は外部プロバイダー (/usr/libexec/docker/cli-plugins/docker-compose) に処理を委譲し、Docker互換のAPIソケットを必要とします。podman.socket が非アクティブ（デフォルト）の場合、podman compose up は失敗します：

failed to connect to the docker API at unix:///run/user/1000/podman/podman.sock:
  connect: no such file or directory

systemctl --user start podman.socket で修正できます。または、podman-compose (ここでは 1.6.0) を直接使用する方法もあります。これは Podman を直接操作するため、ソケットは不要です。Fedora 44 上の Podman 5.8.4 で測定した結果: podman compose up は上記のように失敗しましたが、podman-compose up -d はスタックを起動し、コンテナは healthy を報告しました。

イメージは container-entrypoint.sh の下で両方のプロセスを実行します。このスクリプトはデーモンを起動し、ソケットが応答するのを待ってから、SSE トランスポート上で MCP サーバーを起動します。いずれかのプロセスが終了すると、コンテナは終了します。なぜなら、動作している MCP サーバーが停止したデーモンの隣にあると、永遠に正しい形式のゼロを返す状態になるからです。

時間を節約できる注意点:

• podman build は HEALTHCHECK を破棄します。 Podman はデフォルトで OCI イメージ形式を使用しますが、この形式には HEALTHCHECK フィールドがありません。ビルド時に一度だけ警告が表示されます:

  HEALTHCHECK is not supported for OCI image format and will be ignored.
  Must use `docker` format

  ビルド出力でその行を見逃しても、その後は何も言及されません。イメージにはヘルスチェックが含まれず、podman ps はヘルス状態を表示しません。Podman 5.8.4、Fedora 44 で測定: OCI イメージの .HealthCheck は nil として検査され、podman build --format docker で再ビルドすると [CMD /app/setup/lib/container-health.sh] が得られます。

  3 つの回避策（すべて検証済み）: --format docker でビルドする。compose を使用する（compose のサービスレベルのヘルスチェックは compose.yaml で定義され、イメージ形式に関係なく適用されます。compose 管理のコンテナは、nil と検査される同じイメージから healthy を報告します）。または、podman exec <name> /app/healthcheck.sh --skip-mcp でオンデマンドで確認する。

• MCP ポートは ホストのループバックのみ に公開されます (127.0.0.1:9106:9106)。コンテナ内ではサーバーは 0.0.0.0 にバインドします。これはコンテナ内では正しいですが、ワークステーションでは間違っています。

• Qdrant のホストポートは ${QDRANT_PORT:-6333} と ${QDRANT_ADMIN_PORT:-6334} です。すでに Qdrant を 6333 で実行している場合は .env で設定してください。そうしないとバインド競合が発生し、プロファイルが起動しなくなります。

• イメージはコアインストールのため、qdrant プロファイル単独では何もしません。 podman-compose --profile qdrant up を実行すると Qdrant が起動し、ヘルスチェックを通過してポートで応答しますが、サーバーにはそれと通信する qdrant-client がありません。すべてが正常に見えても、何もインデックス化されません。実際に使用するには、オプションのスタックでビルドしてください:

  podman build --build-arg WITH_OPTIONAL=1 -t enhanced-memory:local -f Containerfile .
  # or, through compose:
  WITH_OPTIONAL=1 podman-compose up --build

  ./healthcheck.sh は 2 つのケースを区別します。Qdrant が到達可能かつ使用可能であるのは、クライアントライブラリがインポート可能な場合のみで、サービスは稼働しているがそれを使用できるものがない場合に警告します。

• データベースは名前付きボリューム enhanced-memory-data に保存されます。ボリュームがないと、メモリはコンテナとともに消滅します。

• ollama はホスト上で実行されており、コンテナは 127.0.0.1 では到達できません。compose.yaml の MEMORY_OLLAMA_URL のコメントを解除してください（podman の場合は host.containers.internal、docker の場合は host.docker.internal）。

• 実行中のコンテナを確認するには、ホストインストールと同じ方法で行います。絶対パスを使用してください。すべてのエンジンが相対パスを WORKDIR に対して解決するわけではありません。

  podman exec enhanced-memory /app/healthcheck.sh --skip-mcp

• ローカルの .env はコンテナの設定ではありません。イメージは意図的に空の .env を出荷し、実際の設定はすべて compose.yaml のランタイム環境から来ます。.containerignore と .dockerignore はファイルを除外しますが、すべてのエンジンがそれらを尊重するわけではないため（Apple の container build は尊重しませんでした、2026-08-14 確認）、Containerfile は破棄されたビルドステージでファイルを空にし、その後、生存しているファイルが存在する場合はビルドを失敗させます。

バックグラウンドサービスとしての実行

setup/service/install-services.sh              # daemon only
setup/service/install-services.sh --with-sse   # and a shared SSE server
setup/service/uninstall-services.sh

macOS では launchd ユーザーエージェント（~/Library/LaunchAgents）、Linux では systemd ユーザーユニット（~/.config/systemd/user）。root は不要、システムユニットは不要。すべてのパスはこのチェックアウトの場所からレンダリングされるため、異なる --label-prefix 値、異なる MEMORY_DB_SOCKET_PATH 値、そして異なる ENHANCED_MEMORY_DIR 値 を指定すれば、2 つのチェックアウトを共存させることができます。3 つすべてが必要です。最初の 2 つだけでは不十分です。ソケットを分離しても、両方のデーモンが同じ memory.db を開くことになり、各デーモンはそのファイルを排他的に所有することを意図しています。

インストーラーはソケットを待機し、サービスが起動しない場合はログの末尾を表示して大きなエラーを出します。ログは ~/Library/Logs/enhanced-memory または ${XDG_STATE_HOME:-~/.local/state}/enhanced-memory/log に保存されます。チェックアウト内には意図的に保存されません。launchd は生成時に外部ボリューム上にログファイルを作成できず、ジョブはコードが実行される前に終了コード 78 で停止します。

Linux では、ユーザーユニットはログアウト時に停止します。lingering を有効にしない限り:

loginctl enable-linger $USER

インストールの確認

2 つのゲート。この順序で。

./healthcheck.sh                 # the post-install gate
python3 comprehensive_test.py    # the functional suite (needs the daemon running)

3 つ目の開発者向けスイートは tests/ にあり、最初に pip install -r dev-requirements.txt が必要です。pytest は意図的にランタイム要件ファイルには含まれておらず、上記の 2 つのゲートは stdlib のみで実行されます。

comprehensive_test.py は終了コードで判断し、合格数ではありません。チェックの数は選択されたモードに依存します。ENHANCED_MEMORY_* または MEMORY_DB_* 変数が設定されていない場合は、独自のサンドボックスを構築してすべてを実行し、設定されている場合はデプロイメントに対して実行し、作成していないサンドボックスを説明するチェックをスキップします。1 台のマシン、1 つのコミットで測定: 106 の分離テストと 102 のオペレーター指向テスト、両方とも終了コード 0。実行は自身のモードを出力し、スキップした内容を名前で示します。

オプションのバックエンドをインストールしても、その数は ゼロ 変化しません。両方の方法で測定済み。このファイルの以前のリビジョンでは、バックエンドが原因であると述べていました。実際はそうではなく、同じ誤った推測が、誰もテストする前に pytest のスキップ数に付けられていました。実際に何がその数を動かすかについては、RELEASE_NOTES.md のテストスイートセクションを参照してください。

./healthcheck.sh は失敗できるように設計されています。デーモンソケットを介してプローブエンティティを書き込み、それを検索し、削除します。どの応答にも error または daemon キーがある場合、ペイロードの残りに関係なく失敗とみなし、デーモンが報告するデータベースパスと環境が解決するパスを比較します。以下をチェックします:

1. venv、インタープリターバージョン、.env、ソケットパスの長さ、ソースの存在

2. デーモンのラウンドトリップ（ステータス、データベースの一致、書き込み、読み戻し、クリーンアップ）およびスキーマチェック: このデータベースを所有する 2 つのファイル内のすべてのリテラル INSERT をライブテーブル定義と比較します。スキーマにない列はすべての書き込みを失敗させ、デーモンは各行ごとに失敗を報告し、例外を発生させないためです。

3. MCP ハンドシェイク（stdio 経由）、ツール数、および stdout が汚染されていないこと

4. Qdrant と ollama。OPTIONAL とマークされ、決して致命的ではありません

便利なフラグ: --skip-mcp（高速なデーモンのみのチェック）、--expect-tools N（カウントを固定）、--require-optional（ベクタースタックを要求）

ログの場所

/tmp/enhanced-memory-mcp.log。常に、ホスト上のすべてのインストールで。

MCP サーバーは起動時にすべてのロギングハンドラーをクリアし、すべてをその 1 つのローテーションファイル（50 MB、2 バックアップ）に送信します。stdio トランスポートでは、stdout 上の何かがプロトコルを破壊するためです。通常の INFO はそこにのみ存在し、パスは固定されているため、1 台のマシン上の 2 つのチェックアウトは、タイムスタンプと pid のみを区切りとして同じファイルにインターリーブされます。

WARNING 以上は、MEMORY_LOG_STDERR=0 を設定しない限り、追加で stderr に送信されます。これは意図的です。... integration skipped: <reason> の行はすべて、ロードされなかった機能であり、それらを /tmp 下のファイルにのみルーティングすると、誰も読まないからです。MCP クライアントが stderr 出力をエラーとして扱う場合は、変数を 0 に設定してファイルを読んでください。

./healthcheck.sh もこれらを報告します。WARN mcp-startup 行として、個別の警告をリストアップします。そのため、欠落した機能はゲートに表示され、ログにのみ表示されることはありません。このブランチで測定: コアインストールでは 11 個の警告（numpy、qdrant-client、sentence-transformers、redis、neo4j など）、フルインストールでは 3 個。いずれもゲートを失敗させません。これらはインストールにないものの一覧であり、一度読んで後は無視する価値があります。

このリリースの署名の検証

コミットは SSH で署名されています。Git は、どのキーを信頼するかを指示するまで署名を検証しません。その設定はクローンとともに移動しません:

git config gpg.ssh.allowedSignersFile .allowed_signers
git log --show-signature -1

最初の行がない場合、git log --format=%G? はすべてのコミットに対して N を報告します。これは「検証不能」を意味し、「未署名」ではありません。署名はどちらの場合も存在します。git cat-file commit HEAD は gpgsig ブロックを表示します。

トラブルシューティング

すべてのツールがゼロまたは error フィールドを返す

デーモンが実行されていません。これは圧倒的に一般的なケースです。

{"count": 0, "results": [], "error": "Memory-DB service error: ..."}

setup/bin/memory-db-daemon.sh          # foreground, watch it
./healthcheck.sh --skip-mcp            # confirm the round trip

サーバーとデーモンがデータベースについて一致しない

症状: 書き込みは成功したように見えるが、検索で見つからない、または get_memory_status が保存したものと一致しないカウントを報告する。2 つのプロセスが異なるファイルを解決し、どちらもエラーにならない。

./healthcheck.sh はこれを直接検出します:

FAIL db-agreement  SPLIT BRAIN: daemon holds /path/A/memory.db,
                   this environment resolves /path/B/memory.db

原因: いずれかのプロセスが、異なる ENHANCED_MEMORY_DIR、ENHANCED_MEMORY_DB_PATH、または HOME で開始された。通常は、MCP クライアントが .env を適用するランチャーをバイパスして、python server.py を直接実行するように設定されている。クライアント設定を修正して setup/bin/mcp-server.sh を使用するようにし、両方のプロセスを再起動してください。

コンテンツクエリがゼロを返すが、名前クエリは機能する

e9ca30c 以降、これは静かに発生することはありません。検索が観察コンテンツを認識できない場合、応答は次のように述べます —

{"count": 0, "results": [], "degraded": "name-only (observations_fts missing)"}

degraded は、データベースが全文インデックスより前のものであり、アップグレード以降にデーモンが初期化していないことを意味します。デーモンを再起動してください: init_database() はインデックスを作成し、既存のすべての行をバックフィルするようになりました。もう 1 つの値 name-only (FTS query error) はクエリごとであり、クエリテキストがサニタイズ後に FTS 構文を壊したことを意味します。名前/タイプの一致は引き続き実行されました。

シードの再インポートで重複した観察が追加される

e9ca30c で修正: create_entities は、そのエンティティにまったく同じ内容の観察が既に存在する場合、それをスキップし、応答で observations_deduped としてスキップを報告するため、シードの再インポートは冪等です。真に新しい観察は引き続き追加されます。修正前の再インポートによって作成された重複は自動的には削除されません。問題 #8 に 1 回限りのクリーンアップ SQL があります。

言い換えられた 再インポート（同じシードファイルが軽く編集されたもの）も、決定論的 simhash によって検出されます。LLM は関与しません。デフォルトでは、保存され、報告されます。near_duplicates 応答フィールドに、各々がどの既存行に似ているかを示します。修正（「62Gi」→「125Gi」）はこのレイヤーでは言い換えと区別できず、メモリストアは修正を静かにドロップしてはなりません。再インポートしていることを認識しているインポートパイプラインは、代わりにそれらをドロップするために ENHANCED_MEMORY_NEAR_DUP_POLICY=skip を設定できます。その変数の他の値は、安全な保存および報告にフォールバックします。距離しきい値と測定されたキャリブレーションバンドは simhash_dedup.py にあります。

デーモン起動時に OSError が発生し、有用なメッセージがない

ソケットパスが長すぎます。AF_UNIX はパス文字列を macOS で 104 バイト、Linux で 108 バイトに制限しており、bind() は上限もパスも言及しないエラーで失敗します。深いチェックアウトでは、ソケットがその中に配置された瞬間にこれが発生します。

MEMORY_DB_SOCKET_PATH を短くし、チェックアウトの外側に置いてください。例: /tmp/em-myproject.sock。setup/setup.sh はそれを測定し、長すぎる場合は続行を拒否します。

macOS: サービスはインストールされるが、デーモンが起動しない

ログにランチャーパスに対して Operation not permitted と表示される場合、チェックアウトは launchd が実行を許可されていない場所にあります。2026-08-14 確認: /Volumes 下の外部ボリューム上のチェックアウトは、インストールとロードは正常に行われますが、その後 spawn ごとに EPERM で失敗します。launchd はターミナルが持つディスクアクセスなしで実行されるためです。

チェックアウトをホームディレクトリまたは他のローカルパスに移動して再インストールするか、場所が交渉不可能な場合は launchd にフルディスクアクセスを許可してください。インストーラーはこれを隠さずに表示します。ソケットを 30 秒待機し、失敗したらエラーログの末尾を表示します。

ConnectionRefusedError が発生するが、ソケットファイルは存在する

強制終了されたデーモンがファイルを残しました。デーモンを再起動すると、それ自体がファイルを削除し、removed stale socket <path> とログに記録します。ランチャーも実行前に同様の処理を行います。習慣としてソケットファイルを手動で削除しないでください — まだサービス中のファイルは古いファイルとまったく同じように見え、削除するとそのデーモンのすべてのクライアントが切断されます。

REFUSING TO START: another daemon is already serving ...

意図した動作です: 他の何かがそのソケットパスで応答しています。メッセージはソケットを指定し、他のデーモンがステータス要求に応答した場合は、それが保持するデータベースも示します。そのデーモンを停止するか、このデーモンに独自の MEMORY_DB_SOCKET_PATH および ENHANCED_MEMORY_DIR を指定してください — Already running an enhanced-memory system? を参照。

The MCP client fails at the handshake with a JSON parse error

何かが標準出力に出力されました。標準出力は stdio トランスポート上の JSON-RPC ストリーム専用です。./healthcheck.sh のチェック 3 は、問題のある行とともにこれを FAIL mcp-stdout として報告します。

python3 is 3.9

macOS ではよくあることです。サポートされているインタプリタをインストールし (brew install python@3.11)、setup/setup.sh を再実行してください。これはバージョン付きの名前を優先します。特定のものを強制するには: setup/setup.sh --python /path/to/python3.11。

Gaps and known issues

再確認のために書かれており、信頼しないでください。

• ヘルスチェックは SSE トランスポートを実行せず、個々のツールを呼び出さず（リストするのみ）、複数クライアントからの同時アクセスをテストせず、ベクタースタックの有無による再現品質を測定しません。

• この README の以前のリビジョンで引用されていたパフォーマンス数値はここでは再現されておらず、繰り返す代わりに削除されました。このファイル内のいかなる記述も、スループット、レイテンシ、圧縮率を主張するものではありません。

• コンテナパスは Fedora 44, linux/amd64 上の podman 5.8.4 で検証済み: ビルド、実行、内部で完全なヘルスチェックがグリーン、スーパービジョンテストではエントリポイントがどの半分が死んだかを示す Exited (1) を生成、podman-compose でスタックが正常に起動。開発中は Apple の container および macOS/arm64 上の Docker でもビルド・実行されました。対象外: Fedora 44 以外のディストリビューション、および rootful podman（上記はすべて rootless でした）。

• サービスユニットはインストーラによってインストールおよび起動され、インストーラはソケットを待ち、現れない場合は大きなエラーを出して失敗します。実際の再起動やログアウトをまたいだ生存性はテストされていません。

• ツールの数は、サーフェス、プロファイル、およびインストールされているオプションの依存関係によって異なります。単一の数値は特定のマシンの構成に固有のものとして扱ってください。

License

MIT