Reverie

Reverie — 夢を見るグラフメモリ

Reverie は KnowAll AI の、AI エージェント向け Neo4j ナレッジグラフメモリです。MCP 経由で提供されます。npm では @knowall-ai/reverie として公開されています（旧パッケージ @knowall-ai/mcp-neo4j-agent-memory の後継です）。GitHub リポジトリは現在 knowall-ai/mcp-reverie で、古い URL はリダイレクトされます。

Reverie は、エージェントのメモリを事実の寄せ集めから、エージェントの世界にあるエンティティと、それらの関係を示すマップへと変え、そのマップを健全な状態に保ちます。MCP サーバーなので、Model Context Protocol に対応するあらゆるエージェント（Claude Desktop、OpenClaw、Azure AI Foundry、Cursor…）が同じグラフを利用できます。Hermes Agent 向けのメモリプロバイダー版は hermes-reverie にあります。

Reverie を選ぶ理由

• 事実のストアではなく、型付きエンティティグラフです。 人物、組織、プロジェクト、場所、概念、会議、決定が、型付きの関係を持つノードになります。「Winnie について話したことのあるアイルランドサッカー協会の人は誰ですか？」という問いには、類似検索ではなく、グラフをたどって答えます。
• 「Benjamin」と言ったときに「Ben」を見つける検索機能です。 キーワード検索、セマンティック検索、あいまいな名前検索を組み合わせています。デフォルトではローカル埋め込みを使用するため API キーは不要で、設定を切り替えるだけで OpenAI、Azure OpenAI、Ollama、Voyage も利用できます。
• 夢を見ます。 dream ツールは、重複を安全に統合し、ラベルを標準化し、埋め込みを再生成し、孤立ノードを数え、プロパティの寄せ集めになったノードにフラグを立てます。これにより、夜間ジョブでグラフをきれいな状態に保てます。
• 1 つのグラフをあらゆるエージェントで使えます。 KnowAll は Sallie（OpenClaw）と Poppie（Hermes）を同じ規約で動かしています。Reverie によって、それぞれが知っていることを共有できます。
• LLM 主導の、透明性の高いツールです。 シンプルでアトミックな操作を提供し、エンティティの認識と競合の解決はモデルが行います。すべてのアクションが明示されます。
• 自分で運用できます。 Neo4j を自分のマシンまたは VM で動かせます。リモート埋め込みプロバイダーを選ばない限り、データが外部に送信されることはありません。

クイックスタート 🚀

この MCP サーバーは npx を使って直接実行できます。

npx -y @knowall-ai/reverie

または、Claude Desktop の設定に追加します。

{
  "mcpServers": {
    "reverie": {
      "command": "npx",
      "args": ["-y", "@knowall-ai/reverie"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

機能

• 🧠 永続的なメモリストレージ - 会話をまたいでメモリを保存、取得できます
• 🔗 セマンティックな関係 - メモリ間に意味のあるつながりを作成できます（KNOWS、WORKS_AT、CREATED など）
• 🔍 ハイブリッド検索 - デフォルトのローカル埋め込みを使い、すべてのメモリプロパティを対象にキーワード検索とセマンティック検索を実行します
• 🏷️ 柔軟なラベル付け - メモリには任意のラベルを使用できます（人物、場所、プロジェクト、アイデアなど）
• ⏰ 時間情報の追跡 - タイムスタンプの自動記録と日付ベースのクエリに対応します
• 🌐 グラフ探索 - 関係をたどって、関連情報を見つけられます
• 🎯 コンテキスト対応 - 深さを指定して検索し、関連するメモリも含められます
• 🔧 LLM に最適化 - シンプルなツールを使い、複雑な処理は AI に任せられます
• 🏢 エンタープライズ対応 - 複数の Neo4j データベースをサポートします
• 📚 組み込みガイド - ベストプラクティスや使用パターンに関するヘルプを提供します

哲学：LLM 主導のインテリジェンス

複雑なロジックをツールに組み込む従来の手法とは異なり、このサーバーはシンプルでアトミックな操作を提供し、あらゆる判断を LLM に任せます。

• 隠れたロジックはありません：ツールはその説明どおりに動作します。自動的な曖昧さの解消やスマートなマッチングは行いません。
• すべてを LLM が決定します：エンティティの認識、関係の推論、競合の解決を行います。
• 透明性の高い操作：すべてのアクションが明示的で予測可能です。
• 最大限の柔軟性：ツールの制限に縛られず、LLM があらゆる戦略を実装できます。

検索の動作

search_memories はハイブリッド検索です。各結果は、キーワード、セマンティック検索、または名前のあいまい検索のうち、最も高いシグナルに基づいて順位付けされます。詳しくは、以下の検索を参照してください。

このアプローチにより、システムの性能と適応性が向上します。LLM の機能が改善されると、その成果がメモリー管理の向上に直接反映されます。

検索

search_memories は、以下のモードを通じて、キーワード、セマンティック、あいまい、完全一致の4つの照合シグナルに対応しています。

• hybrid（デフォルト）：最も高いシグナルに基づいて順位付けします。クエリ語のキーワード一致率、セマンティック検索のコサイン類似度、または名前のあいまい一致度を使用します
• keyword：検索可能なコンテンツプロパティのいずれかに、クエリ内の単語のいずれかが部分文字列として含まれているものを検索します（タイムスタンプ、status、埋め込みフィールドは照合対象になりません）
• semantic：埋め込みのみを使用します。埋め込みが利用できない場合はキーワード検索にフォールバックします（hybrid ではキーワードとあいまい検索のシグナルも維持されます）
• fuzzy：スペル、接頭辞、発音を使って、誤記された名前や聞き間違えた名前、別名を照合します。埋め込みがなくても、「Ben Wicks」から「Benjamin Weeks」を検索できます
• exact：name、aliases、email を大文字と小文字を区別せずに完全一致で照合します。メモリーを作成する前に実行する正確な検索です。「ben weeks」なら「Ben Weeks」だけが見つかり、それ以外は見つかりません

アーカイブ済みのメモリー（status = 'archived'）は、include_archived: true を渡さない限り、検索結果および list_memory_labels から除外されます。返されるリレーションシップには _start と _end のノード ID が含まれるため、接続の向きを常に特定できます。

similarity_threshold（デフォルトは 0.4。0 から 1 の間で指定する必要があり、それ以外の値は拒否されます）を使って、セマンティック検索の一致条件を調整します。あいまい検索の厳密さは、fuzzy_threshold（デフォルトは 0.85、範囲は 0～1）で調整します。結果には _score、_match、およびあいまい検索のヒットの場合は _matched（保存されている名前または別名）が含まれます。名前が異なる場合はユーザーに確認してください。Bill／William のような愛称には aliases が必要です。

Neo4j Enterprise のサポート

このサーバーは、Neo4j Enterprise Edition の特定のデータベースへの接続に対応しました。デフォルトでは「neo4j」データベースに接続しますが、NEO4J_DATABASE 環境変数を使って別のデータベースを指定できます。

メモリツール

• search_memories：ナレッジグラフからメモリを検索・取得します

  • ハイブリッド検索：キーワード検索、セマンティック検索、あいまいな名前検索を組み合わせます。Ben Wicks で Benjamin Weeks を見つけられます
  • search_mode に hybrid、keyword、semantic、fuzzy、exact のいずれかを指定します
  • similarity_threshold（デフォルトは 0.4）と fuzzy_threshold（デフォルトは 0.85）を調整できます
  • 返されるメモリには、あいまい検索で一致した場合、_score、_match、_matched が含まれます
  • メモリの種類（大文字と小文字は区別されないため、person と Person のどちらも使用できます）、日付、深さ、結果の上限、並べ替え順で絞り込めます

• create_memory：ナレッジグラフに新しいメモリを作成します

  • 柔軟な型システムです。通常の識別子であれば任意のラベルを使用できます。先頭を大文字にした単数形が標準です（Person、Place、Project、Skill など）。dream は小文字のラベルを標準形に変換します
  • 任意のプロパティをキーと値のペアとして保存できます
  • 時系列の追跡に使うタイムスタンプを自動で記録します

• create_connection：メモリ間のリレーションシップを作成します

  • 意味を表すリレーションシップの種類（KNOWS、WORKS_AT、LIVES_IN など）でメモリをリンクします
  • リレーションシップにプロパティ（since、role、status など）を追加できます
  • 複雑なナレッジネットワークを構築できます

• update_memory：既存のメモリのプロパティを更新します

  • ノードがプロパティ上限を超えると、_hint が返されます。グラフはエンティティとリレーションシップのためのものであり、ノートブックではありません
  • 任意のプロパティを追加または変更できます
  • プロパティを null に設定すると削除できます

• update_connection：リレーションシップのプロパティを更新します

  • リレーションシップのメタデータを変更します
  • 時間の経過に伴う変化を追跡します

• delete_memory：メモリと、それに関連するすべての接続を削除します

  • 削除は恒久的なため、慎重に使用してください
  • すべてのリレーションシップを自動的に削除します

• delete_connection：特定のリレーションシップを削除します

  • リレーションシップを正確に削除します
  • メモリはそのまま保持されます

• list_memory_labels：使用されている一意のメモリラベルをすべて一覧表示します

  • 件数とともにすべてのラベルを表示します
  • 一貫性の維持に役立ちます
  • ラベルの重複や表記ゆれを防ぎます

• query_memories：読み取り専用の Cypher クエリを実行します

  • Cypher 文字列と、任意のパラメーターを受け取ります
  • Neo4j の READ トランザクションで実行されます（サーバーは書き込みを拒否します）。200 行で停止し、10 秒でタイムアウトします
  • 書き込み句、CALL サブクエリ、および読み取り専用の少数の許可リスト（db.labels、db.propertyKeys、db.index.*.query*、スキーマプロシージャ）以外のプロシージャを拒否します。念には念を入れて、可能な場合は読み取り専用の Neo4j ロールでサーバーを実行してください

• memory_stats：現在のグラフを要約します

  • ノード、リレーションシップ、ラベル、リレーションシップの種類、埋め込み、孤立ノードの件数を返します

• dream：グラフを決定的に整理・統合します

  • 小文字のラベルを先頭大文字の形式に変更し（person → Person）、APOC が利用可能な場合は同じ名前のノードを統合し、埋め込みを更新します
  • 統合後に残るノードの name、タイムスタンプ、ベクトルは保持され、その他すべてのプロパティが統合されます（値が競合する場合はリストになり、何も破棄されません）。識別フィールド（email、phone、website、company、organisation、organization）が異なるペアはスキップされるため、別人の「John Smith」が統合されることはありません。レポートの duplicates には、統合またはスキップされた各グループと、その理由が記載されます。まず dry_run: true で実行し、内容を確認してください
  • REVERIE_MAX_PROPERTIES（デフォルトは 30、実プロパティ数）を超えるプロパティを持つ「肥大化した」ノードを検出し、日付付きの事実や文章に見えるキーを表示します。これにより、夜間の整理でそれらを属性、リレーションシップ、またはノートにまとめられます
  • 書き込みを行わないレポートを生成する dry_run に対応しています

• get_guidance：メモリツールを効果的に使うためのヘルプを取得します

  • トピック：ラベル、リレーションシップ、ベストプラクティス、例
  • LLM 向けの包括的なガイダンスを返します
  • ラベルやリレーションシップの命名に迷った場合に使用してください

前提条件

1. Neo4j Database 5.9 以降（dream ツールでは COUNT {} と IS :: STRING を使用します）。重複の統合には APOC が必要です

   • Neo4j Community または Enterprise Edition をインストールします
   • neo4j.com/download からダウンロードします
   • または Docker を使用します：docker run -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j

2. Node.js（v18 以降）

   • MCP サーバーの実行に必要です
   • nodejs.org からダウンロードします

3. Claude Desktop（MCP 統合用）

   • claude.ai/download からダウンロードします

インストール

MCP Registry

Reverie は MCP Registry に ai.knowall/reverie として登録されています（KnowAll のドメイン名前空間で、knowall.ai の DNS TXT レコードによって検証済みです）（以前 modelcontextprotocol/servers の README に掲載されていた「Neo4j Agent Memory」の項目を引き継いでいます）。このリポジトリの server.json が登録情報です。リリースワークフローによって、タグの作成時に毎回再公開されます。

Smithery 経由でのインストール

Smithery を使って Reverie を Claude Desktop に自動的にインストールするには（現在は旧パッケージ名でインデックスされています）：

npx -y @smithery/cli install @knowall-ai/mcp-neo4j-agent-memory --client claude

開発環境向け

1. リポジトリをクローンします：

git clone https://github.com/knowall-ai/mcp-reverie.git
cd mcp-reverie

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

設定

環境変数

サーバーには、以下の環境変数が必要です：

• NEO4J_URI：Neo4j データベースの URI（必須。例：bolt://localhost:7687）
• NEO4J_USERNAME：Neo4j のユーザー名（必須）
• NEO4J_PASSWORD：Neo4j のパスワード（必須）
• NEO4J_DATABASE：Neo4j データベース名（任意）- 複数のデータベースを使用する Neo4j Enterprise 向け

エンベディング

REVERIE_EMBEDDINGS を設定して、ハイブリッド検索とセマンティック検索で使用するエンベディングプロバイダーを選択します。REVERIE_EMBEDDINGS または REVERIE_EMBEDDING_MODEL を変更すると、次回の検索時にノードが遅延再エンベディングされます。また、dream の実行時に即時再エンベディングされます。

REVERIE_EMBEDDINGS	デフォルトモデル	必須の環境変数
local（デフォルト）	Xenova/all-MiniLM-L6-v2	なし。REVERIE_MODEL_CACHE は任意
openai	text-embedding-3-small	OPENAI_API_KEY。OPENAI_BASE_URL は任意
azure	デプロイメントにより指定	AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY、AZURE_OPENAI_EMBEDDING_DEPLOYMENT。AZURE_OPENAI_API_VERSION は任意
ollama	nomic-embed-text	OLLAMA_HOST は任意
voyage	voyage-3-lite	VOYAGE_API_KEY
none	無効	なし

REVERIE_EMBEDDING_MODEL を使うと、任意のプロバイダーのモデル名を上書きできます。リモートプロバイダーはリクエストごとに最大 64 件のテキストをまとめて処理し、REVERIE_EMBED_TIMEOUT_MS（デフォルトは 30000、最大は 120000）を過ぎるとタイムアウトします。また、https 経由で接続できる必要があります。通常の http が許可されるのは localhost のみです。

local プロバイダーは、初回使用時に Hugging Face からモデル（約 23 MB）をダウンロードしてキャッシュします。ダウンロードに失敗した場合、またはプロバイダーでエラーが発生した場合、セマンティック検索はキーワードマッチングにフォールバックし、ハイブリッド検索はその呼び出しに限りキーワードマッチングとファジーマッチングを維持します。エラーは stderr に記録されます。エンベディングを完全に無効にするには、REVERIE_EMBEDDINGS=none を設定します。

各ノードには 2 つのベクトルが保存されます。embedding（ラベル、名前、およびすべてのテキストプロパティ）と name_embedding（ラベル、名前、およびエイリアスのみ）です。さらに、embedding_model と embedded_at も保存されます。セマンティックスコアには 2 つのベクトルのうち高い方が使われるため、Ben Weeks のような短いクエリでも、豊富な説明が付いた Benjamin Weeks に一致します。これらのフィールドがツールから返されることはありません。

環境変数の設定

開発環境向け

.env.example を .env にコピーし、認証情報を更新します：

cp .env.example .env
# Edit .env with your Neo4j credentials

Claude Desktop 向け

環境変数を Claude Desktop の設定に追加します（上記のクイックスタートを参照してください）。

使用例

何を保存し、記憶をどのようにつなげるかは、LLM がすべて判断します：

情報の保存

User: "Remember that John works at Google as a software engineer"

Assistant: I'll remember that John works at Google as a software engineer.

[Behind the scenes, the LLM does:
1. search_memories({"query": "John"}) - Check if John exists
2. search_memories({"query": "Google"}) - Check if Google exists
3. create_memory({"label": "Person", "properties": {"name": "John", "occupation": "software engineer"}})
4. create_memory({"label": "Organization", "properties": {"name": "Google"}})
5. create_connection({"fromMemoryId": 123, "toMemoryId": 456, "type": "WORKS_AT"})]

User: "Remember that Sarah is John's manager and she started in 2019"

Assistant: I'll add that information about Sarah.

[The LLM searches for John, creates Sarah, and connects them with a MANAGES relationship including the start date]

情報の取得

User: "Who works at Google?"

Assistant: Let me search for people who work at Google.

[LLM uses: search_memories({"query": "Google", "depth": 2})]

Based on my memory:
- John - Software Engineer at Google
- Sarah - Manager at Google (manages John, started 2019)

User: "What do you remember about John?"

Assistant: Here's what I know about John:

[LLM uses: search_memories({"query": "John", "depth": 2})]

- Works at Google as a Software Engineer
- Sarah is his manager
- [Any other connected memories found in the search]

関係の構築

User: "John and Sarah are working on Project Atlas together"

Assistant: I'll connect John and Sarah to Project Atlas.

[The LLM:
1. Searches for John and Sarah to get their IDs
2. Creates Project Atlas: create_memory({"label": "Project", "properties": {"name": "Project Atlas"}})
3. Connects them: create_connection({"fromMemoryId": johnId, "toMemoryId": projectId, "type": "WORKS_ON"})
4. create_connection({"fromMemoryId": sarahId, "toMemoryId": projectId, "type": "WORKS_ON"})]

特定のデータベースへの接続

複数のデータベースを使用する Neo4j Enterprise ユーザーは、接続先のデータベースを指定できます。

{
  "env": {
    "NEO4J_URI": "bolt://localhost:7687",
    "NEO4J_USERNAME": "neo4j",
    "NEO4J_PASSWORD": "your-password",
    "NEO4J_DATABASE": "myCustomDatabase"
  }
}

これにより、デフォルトの「neo4j」データベースではなく、「myCustomDatabase」に接続します。

より複雑な例

関連情報の検索

User: "Show me all employees in the Sales department"

Assistant: Let me search for employees in the Sales department.

[LLM uses: search_memories({"query": "Sales department", "depth": 2})]

I found these employees in the Sales department:
- John Smith (Sales Manager)
- Sarah Johnson (Sales Representative)  
- Mike Brown (Account Executive)

ドメイン固有の記憶の作成

User: "Create a product called 'Premium Coffee' with price $24.99"

Assistant: I'll create that product for you.

[LLM uses: create_memory({"label": "Product", "properties": {"name": "Premium Coffee", "price": 24.99}})]

Created Premium Coffee product with ID: 456

リレーションシップの管理

User: "The Premium Coffee uses beans from our Colombian Supplier"

Assistant: I'll connect Premium Coffee to the Colombian Supplier.

[LLM:
1. search_memories({"query": "Premium Coffee"})
2. search_memories({"query": "Colombian Supplier"})
3. create_connection({"fromMemoryId": 456, "toMemoryId": 789, "type": "SUPPLIED_BY"})]

Connected Premium Coffee to Colombian Supplier

高度なクエリ

LLM は検索ツールをインテリジェントに使用して、複雑なクエリに対応できます。

単語ベースの検索

User: "Find Ben Weeks"

Assistant: I'll search for memories containing "Ben" or "Weeks".

[LLM uses: search_memories({"query": "Ben Weeks"})]

I found several people matching your search:
- Ben Weeks - Software Engineer at TechCorp (exact match)
- Sarah Ben - Data Scientist at DataCo (contains "Ben")
- John Weeks - Project Manager (contains "Weeks")

The most likely match appears to be Ben Weeks, the Software Engineer.

キーワードマッチングでは、クエリに含まれる単語のいずれかに一致するものを検索し、一致した割合をスコアとして算出します。ハイブリッド検索では、意味的な一致や曖昧な名前の一致も考慮し、それぞれの結果を最も高いシグナルに基づいて順位付けします。

最近の記憶（過去 7 日間）

User: "What new people have I met in the last week?"

Assistant: I'll search for people added to your memory in the last 7 days.

[LLM calculates the date 7 days ago and uses: 
search_memories({
  "query": "", 
  "label": "person", 
  "since_date": "2024-01-20T00:00:00Z",
  "order_by": "created_at DESC"
})]

Here are the new people you've met in the last week:
- Sarah Chen - Met at tech conference on Monday
- Dr. Michael Roberts - New physician, first appointment Tuesday  
- Emma Wilson - Joined your project team on Wednesday
- James Park - Coffee meeting about potential collaboration Thursday

曖昧さの解消

User: "What does John do?"

Assistant: I found multiple people named John. Let me show you what I know:

[LLM uses: search_memories({"query": "John", "type": "Person", "depth": 1})]

1. John Doe - Software Engineer at Google
2. John Smith - Sales Manager in Sales Department
3. John Brown - Project Manager on Project Atlas

Which John were you asking about?

時間に関するクエリ

User: "What events did I attend last month?"

Assistant: I'll search for event memories and check their dates.

[LLM uses: search_memories({"query": "", "label": "event", "sort_by": "created_at", "sort_order": "desc"})]

[Filters results to last month based on created_at or date properties]

Here are the events you attended last month:
- Tech Innovation Summit (March 5-6) - Keynote speaker
- Team Building Workshop (March 12) - With engineering team
- Client Dinner Meeting (March 18) - Project kickoff with ABC Corp
- WebDev Conference (March 25-27) - Attended 5 sessions on React

柔軟な記憶の種類

このシステムでは厳密な種類を強制しません。適切な種類であれば、どのような記憶でも作成できます。

一般的な種類（先頭を大文字にした単数形が標準です。dream では小文字も受け付けられ、標準形に正規化されます）：person、place、organization、project、event、topic、object、animal、plant、food、activity、media、skill、document、meeting、task、habit、health、vehicle、tool、idea、goal

ただし、任意の種類を使用できます（任意のプレーンな識別子）：recipe、dream、memory、quote、book、movie、emotion、relationship、appointment、medication、exercise、symptom、payment、contract など。

LLM は一貫性を保つため、適切な場合には既存の種類をインテリジェントに再利用します。

つながりの力

この記憶システムの真の価値は、個々の記憶を保存することだけでなく、それらの間につながりを作ることにあります。リレーションシップを構築するほど、ナレッジグラフは飛躍的に役立つようになります。

つながりが重要な理由

• コンテキストの発見：つながりのある記憶は、孤立した事実では得られない豊かなコンテキストを提供します
• リレーションシップのパターン：リレーションシップを分析することで、隠れたパターンや洞察を明らかにします
• 時間的な理解：リレーションシップが時間とともにどのように変化するかを追跡します
• ネットワーク効果：新たなつながりが増えるたびに、既存の記憶の価値も高まります

つながりを構築するためのベストプラクティス

1. 新しい情報を保存する際は、常にリレーションシップを探します：

   Bad: Just store "John is a developer"
   Good: Store John AND connect him to his company, projects, skills, and colleagues
   

2. 意味を捉えるセマンティックなリレーションシップの種類を使用します：

   WORKS_AT, MANAGES, KNOWS, LIVES_IN, CREATED, USES, LEARNED_FROM
   

3. より豊かなコンテキストを得るため、リレーションシップのプロパティを追加します：

   create_connection({
     "fromMemoryId": 123,
     "toMemoryId": 456, 
     "type": "WORKS_ON",
     "properties": {"role": "Lead", "since": "2023-01", "hours_per_week": 20}
   })
   

4. グラフとして考えます：情報を呼び出す際は、深さを 1 より大きくしてネットワークを探索します：

   search_memories({"query": "John", "depth": 3})  // Explores connections up to 3 hops away
   

覚えておいてください。つながりのない記憶は、目録のない図書館にある本のようなものです。そこに存在はしていますが、活用の幅は限られます。記憶をつなげるほど、ナレッジグラフはより賢く、役立つものになります。

テスト

npm run build              # TypeScript → build/
npm run test:unit          # pure-module unit tests + server startup checks, no database needed
npm run test:integration   # drives the built server over stdio against a live Neo4j
npm run test:coverage      # everything under c8 with a coverage gate (70% lines and functions)

統合テストには APOC を備えた Neo4j 5 が必要で、接続先のデータベースを消去するため、使い捨てのデータベースを用意してください。

docker run -d --rm --name reverie-test-neo4j -p 17687:7687 \
  -e NEO4J_AUTH=neo4j/test-password -e NEO4J_PLUGINS='["apoc"]' neo4j:5-community
NEO4J_URI=bolt://127.0.0.1:17687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=test-password \
  REVERIE_TEST_DESTRUCTIVE=1 npm run test:coverage

REVERIE_TEST_DESTRUCTIVE=1 は明示的なオプトインです。これを指定しない場合、テストスイートは実行を拒否します。指定すると、NEO4J_URI が指すデータベースの内容がすべて消去されるため、使い捨てのデータベースを指定するときに限り設定してください。 テストスイートは、認証済み Bolt が利用可能になるまで最大 1 分間待ってから開始します。また、リモートの NEO4J_URI には、証明書が検証される bolt+s:// または neo4j+s:// を使用する必要があります（+ssc は拒否されます）。

CI では、すべてのプルリクエストで Neo4j サービスコンテナーに対して同じテストスイートを実行し、カバレッジが基準を下回るとビルドが失敗します。最初のセマンティック検索ではローカルの埋め込みモデル（約 23 MB）がダウンロードされます。CI ではこのモデルをキャッシュします。

MCP Inspector を使った対話型テスト

対話型のテストとデバッグには、MCP Inspector を使用します。

# Quick start with environment variables from .env
./run-inspector.sh

# Or manually with specific environment variables
NEO4J_URI=bolt://localhost:7687 \
NEO4J_USERNAME=neo4j \
NEO4J_PASSWORD=your-password \
npx @modelcontextprotocol/inspector build/index.js

Inspector では、次の操作ができる Web UI が提供されます。

• 利用可能なすべてのツールを対話形式でテストする
• リクエストとレスポンスのデータをリアルタイムで確認する
• Neo4j 接続を検証する
• ツールのパラメーターとレスポンスをデバッグする

HTTP モード（reverie serve）

reverie を単独で実行すると、stdio MCP サーバーが起動します。reverie serve は同じサーバーを Streamable HTTP 経由で実行し、KnowAll Agents Portal の Brain タブがグラフをリアルタイムで描画するために使用する、読み取り専用の Brain API を追加します。両方とも 1 つのベアラートークンで保護されます。ヘルスチェックのみ認証なしで利用できます。

REVERIE_SERVE_TOKEN=$(openssl rand -hex 24) NEO4J_PASSWORD=… reverie serve
# Reverie HTTP server listening on http://127.0.0.1:8643

変数	デフォルト	用途
REVERIE_SERVE_TOKEN	（必須）	クライアントが Authorization: Bearer … として送信する必要があるベアラートークン
REVERIE_HTTP_HOST / REVERIE_HTTP_PORT	127.0.0.1 / 8643	バインドアドレス。リバースプロキシの背後でループバックに設定してください
REVERIE_ALLOWED_ORIGINS	なし	API 呼び出しを許可するブラウザーのオリジンをカンマ区切りで指定します（該当するオリジンには CORS ヘッダーとプリフライト応答が返されます）。それ以外の Origin ヘッダーを含むリクエストには 403 が返されます。サーバー間クライアントは Origin を送信しないため、ここでの設定は不要です
REVERIE_EVENTS_PATH	~/.reverie/events.jsonl	アクティベーションログ（下記参照）。空文字列を指定すると無効になります
REVERIE_DREAMS_DIR	未設定	任意の夢日記フォルダー（*.md）。最新のファイル名が最後の夢を示します
REVERIE_USAGE_STATS_PATH / REVERIE_BOOST_STATE_PATH	~/call-transcripts/usage-stats.json / boost-state.json	state 経由で渡される Presence HUD ファイル（usage は 15 分以内に書き込まれた場合のみ）
REVERIE_GRAPH_POLL_SECONDS / REVERIE_STATE_SECONDS / REVERIE_EVENT_POLL_SECONDS	5 / 5 / 1	イベントストリームがグラフ、ホストの状態、アクティベーションログを再読み込みする頻度

NEO4J_* と REVERIE_EMBEDDINGS は stdio モードとまったく同じように動作します。

エンドポイント	認証	戻り値
GET /health（別名 /brain/health）	なし	{ ok, neo4j, ts }
POST /mcp	ベアラー	MCP Streamable HTTP（ステートレス、JSON 応答）。Streamable HTTP に対応する MCP クライアントであれば利用できます
GET /brain/graph?limit=400	ベアラー	最も接続数の多いノード、または最新のノード（limit ≤ 1500）、それらの間のリレーションシップ、ラベル別およびリレーションシップタイプ別の合計、state
GET /brain/state	ベアラー	dreaming、lastActivityAt、lastDreamAt、最近の読み取り／書き込み件数、ホストの CPU／負荷／メモリ、Presence の usage と boost
GET /brain/events?limit=400	ベアラー	Server-Sent Events：直近 30 件の activation イベントの後に state を送信します。その後、新しい activation が発生するたびに、グラフが変更された場合は graph 差分（nodesAdded、nodesUpdated、nodesRemoved、relsAdded、relsRemoved、stats）を、数秒ごとに state を、ポーリングに失敗した場合は error を送信します

Brain API のノード ID は、ツールが返す数値 ID と同じものを文字列として表します。そのため、アクティベーションイベントとスナップショットのノードが一致します。アーカイブされたメモリは表示されません。埋め込みベクトルがサーバー外に出ることはありません。

アクティベーションログ。 どちらのトランスポート経由で処理された場合も、すべての search_memories（recall）、create_memory / update_memory（remember）、create_connection / update_connection（connect）、delete_*（forget）、実際に実行された dream（dream.start / dream.end）は、REVERIE_EVENTS_PATH に JSON 行を 1 行追加します。記録されるのは ID、名前、検索語のみで、ユーザー専用（モード 0600）です。上限は 5 MB／5,000 行で、Brain ビューのアクティビティ表示に使われます。グラフ自体には、何が参照されたかは記録されません。

エージェントの VM 上で Caddy の背後に配置する場合：

agent.example.com {
    # … the agent's other routes …
    handle /reverie/* {
        uri strip_prefix /reverie
        reverse_proxy 127.0.0.1:8643
    }
}

サービスとして実行する場合：

[Unit]
Description=Reverie graph memory (HTTP mode)
After=network-online.target

[Service]
User=agent
EnvironmentFile=/home/agent/.config/reverie.env   # NEO4J_*, REVERIE_SERVE_TOKEN, REVERIE_EMBEDDINGS…
ExecStart=/usr/bin/reverie serve
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

ポータルのエージェントの brainUrl には https://<agent host>/reverie を、REVERIE_TOKEN には同じトークンを指定してください。

ライセンス

MIT