MCP Neo4j Agent Memory

🚀 Neo4j Agent Memory MCP Server

這是一個專門的MCP服務器，它將Neo4j圖數據庫與AI智能體連接起來，提供專注於記憶的工具，用於在知識圖譜中存儲、檢索和關聯信息。

🚀 快速開始

你可以直接使用npx運行這個MCP服務器：

npx @knowall-ai/mcp-neo4j-agent-memory

或者將其添加到你的Claude桌面配置中：

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

✨ 主要特性

• 🧠 持久化記憶存儲 - 在不同對話中存儲和檢索記憶
• 🔗 語義關係 - 在記憶之間創建有意義的連接（如KNOWS、WORKS_AT、CREATED等）
• 🔍 智能搜索 - 對所有記憶屬性和關係進行自然語言搜索
• 🏷️ 靈活標籤 - 為記憶使用任意標籤（如人、地點、項目、想法等）
• ⏰ 時間跟蹤 - 自動添加時間戳並支持基於日期的查詢
• 🌐 圖探索 - 遍歷關係以發現關聯信息
• 🎯 上下文感知 - 深度搜索以包含相關記憶
• 🔧 大語言模型優化 - 提供簡單工具，讓AI處理複雜邏輯
• 🏢 企業級支持 - 支持多個Neo4j數據庫
• 📚 內置指南 - 獲取最佳實踐和使用模式的幫助

📦 安裝指南

通過Smithery安裝

要通過Smithery自動為Claude桌面安裝Neo4j Agent Memory MCP服務器，請執行以下命令：

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

開發環境安裝

1. 克隆倉庫：

git clone https://github.com/KnowAll-AI/mcp-neo4j-agent-memory.git
cd mcp-neo4j-agent-memory

2. 安裝依賴：

npm install

3. 構建項目：

npm run build

💻 使用示例

基礎用法

大語言模型（LLM）負責處理決定存儲內容和關聯記憶的所有複雜邏輯：

存儲信息

用戶：“記住約翰是谷歌的軟件工程師”

助手：我會記住約翰是谷歌的軟件工程師。

[幕後，LLM執行以下操作：
1. search_memories({"query": "約翰"}) - 檢查約翰是否存在
2. search_memories({"query": "谷歌"}) - 檢查谷歌是否存在
3. create_memory({"label": "人", "properties": {"name": "約翰", "occupation": "軟件工程師"}})
4. create_memory({"label": "組織", "properties": {"name": "谷歌"}})
5. create_connection({"fromMemoryId": 123, "toMemoryId": 456, "type": "WORKS_AT"})]

用戶：“記住莎拉是約翰的經理，她於2019年開始任職”

助手：我會添加關於莎拉的信息。

[LLM搜索約翰，創建莎拉，並使用MANAGES關係將他們關聯起來，同時包含開始日期]

檢索信息

用戶：“誰在谷歌工作？”

助手：讓我搜索在谷歌工作的人。

[LLM使用：search_memories({"query": "谷歌", "depth": 2})]

根據我的記憶：
- 約翰 - 谷歌軟件工程師
- 莎拉 - 谷歌經理（管理約翰，2019年開始任職）

用戶：“關於約翰你記得什麼？”

助手：這是我關於約翰的信息：

[LLM使用：search_memories({"query": "約翰", "depth": 2})]

- 在谷歌擔任軟件工程師
- 莎拉是他的經理
- [搜索中找到的任何其他關聯記憶]

建立關係

用戶：“約翰和莎拉正在一起參與阿特拉斯項目”

助手：我會將約翰和莎拉與阿特拉斯項目關聯起來。

[LLM執行以下操作：
1. 搜索約翰和莎拉以獲取他們的ID
2. 創建阿特拉斯項目：create_memory({"label": "項目", "properties": {"name": "阿特拉斯項目"}})
3. 關聯他們：create_connection({"fromMemoryId": johnId, "toMemoryId": projectId, "type": "WORKS_ON"})
4. create_connection({"fromMemoryId": sarahId, "toMemoryId": projectId, "type": "WORKS_ON"})]

高級用法

連接到特定數據庫

對於使用多個數據庫的Neo4j企業版用戶，你可以指定要連接的數據庫：

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

這將連接到“myCustomDatabase”而不是默認的“neo4j”數據庫。

更復雜的示例

查找相關信息

用戶：“顯示銷售部門的所有員工”

助手：讓我搜索銷售部門的員工。

[LLM使用：search_memories({"query": "銷售部門", "depth": 2})]

我找到了銷售部門的這些員工：
- 約翰·史密斯（銷售經理）
- 莎拉·約翰遜（銷售代表）  
- 邁克·布朗（客戶經理）

創建特定領域的記憶

用戶：“創建一個名為‘高級咖啡’的產品，價格為24.99美元”

助手：我會為你創建該產品。

[LLM使用：create_memory({"label": "產品", "properties": {"name": "高級咖啡", "price": 24.99}})]

創建了ID為456的高級咖啡產品

管理關係

用戶：“高級咖啡使用我們哥倫比亞供應商的咖啡豆”

助手：我會將高級咖啡與哥倫比亞供應商關聯起來。

[LLM執行以下操作：
1. search_memories({"query": "高級咖啡"})
2. search_memories({"query": "哥倫比亞供應商"})
3. create_connection({"fromMemoryId": 456, "toMemoryId": 789, "type": "SUPPLIED_BY"})]

已將高級咖啡與哥倫比亞供應商關聯起來

高級查詢

LLM可以通過智能使用搜索工具處理複雜查詢：

基於單詞的搜索

用戶：“查找本·威克斯”

助手：我會搜索包含“本”或“威克斯”的記憶。

[LLM使用：search_memories({"query": "本·威克斯"})]

我找到了幾個與你搜索匹配的人：
- 本·威克斯 - 科技公司的軟件工程師（精確匹配）
- 莎拉·本 - 數據公司的數據科學家（包含“本”）
- 約翰·威克斯 - 項目經理（包含“威克斯”）

最可能的匹配似乎是軟件工程師本·威克斯。

最近7天的記憶

用戶：“我上週結識了哪些新人？”

助手：我會搜索過去7天添加到你記憶中的人。

[LLM計算7天前的日期並使用： 
search_memories({
  "query": "", 
  "label": "人", 
  "since_date": "2024-01-20T00:00:00Z",
  "order_by": "created_at DESC"
})]

以下是你上週結識的新人：
- 莎拉·陳 - 週一在科技會議上結識
- 邁克爾·羅伯茨博士 - 新醫生，週二首次預約  
- 艾瑪·威爾遜 - 週三加入你的項目團隊
- 詹姆斯·帕克 - 週四喝咖啡討論潛在合作

消除歧義

用戶：“約翰是做什麼的？”

助手：我找到了多個名為約翰的人。讓我告訴你我所知道的：

[LLM使用：search_memories({"query": "約翰", "type": "人", "depth": 1})]

1. 約翰· Doe - 谷歌軟件工程師
2. 約翰·史密斯 - 銷售部門的銷售經理
3. 約翰·布朗 - 阿特拉斯項目的項目經理

你問的是哪個約翰？

時間查詢

用戶：“我上個月參加了哪些活動？”

助手：我會搜索活動記憶並檢查它們的日期。

[LLM使用：search_memories({"query": "", "label": "活動", "sort_by": "created_at", "sort_order": "desc"})]

[根據created_at或date屬性過濾結果到上個月]

以下是你上個月參加的活動：
- 科技創新峰會（3月5 - 6日） - 主旨演講者
- 團隊建設研討會（3月12日） - 與工程團隊一起
- 客戶晚宴會議（3月18日） - 與ABC公司的項目啟動會
- 網絡開發會議（3月25 - 27日） - 參加了5場關於React的會議

靈活的記憶類型

系統不強制使用嚴格的類型 - 你可以創建任何有意義的記憶類型： 常見類型（小寫）：人、地點、組織、項目、活動、主題、對象、動物、植物、食物、活動、媒體、技能、文檔、會議、任務、習慣、健康、車輛、工具、想法、目標 但你可以使用任何類型（小寫）：食譜、夢想、記憶、名言、書籍、電影、情感、關係、約會、藥物、鍛鍊、症狀、付款、合同等 LLM會在適當的時候智能重用現有類型以保持一致性。

連接的力量

這個記憶系統的真正價值不僅在於存儲單個記憶，還在於在它們之間創建連接。隨著你建立關係，知識圖譜的實用性會呈指數級增長：

為什麼連接很重要

• 上下文發現：關聯的記憶提供了孤立事實無法提供的豐富上下文
• 關係模式：通過關係分析揭示隱藏的模式和見解
• 時間理解：跟蹤關係隨時間的演變
• 網絡效應：每個新連接都會增加現有記憶的價值

建立連接的最佳實踐

1. 存儲新信息時始終尋找關係：

不好的做法：只存儲“約翰是開發者”
好的做法：存儲約翰並將他與他的公司、項目、技能和同事關聯起來

2. 使用具有語義的關係類型：

WORKS_AT、MANAGES、KNOWS、LIVES_IN、CREATED、USES、LEARNED_FROM

3. 添加關係屬性以提供更豐富的上下文：

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

4. 以圖的思維思考：檢索信息時，使用深度大於1來探索網絡：

search_memories({"query": "約翰", "depth": 3})  // 探索最多3跳的關聯信息

請記住：沒有連接的記憶就像圖書館裡沒有目錄的書 - 它存在，但實用性有限。你關聯的記憶越多，知識圖譜就越智能和有用。

📚 詳細文檔

哲學理念：大語言模型驅動的智能

與傳統方法將複雜邏輯嵌入工具不同，這個服務器提供簡單的原子操作，讓大語言模型處理所有智能邏輯：

• 無隱藏邏輯：工具的功能與描述完全一致 - 沒有自動消歧或智能匹配
• 大語言模型決定一切：實體識別、關係推斷和衝突解決
• 操作透明：每個操作都是明確且可預測的
• 最大靈活性：大語言模型可以實現任何策略，不受工具限制

搜索行為

search_memories工具使用單詞分詞：

• 查詢“約翰·史密斯”會找到包含“約翰”或“史密斯”的記憶
• 這會返回更多結果，讓大語言模型選擇最相關的結果
• 對於姓名和多詞查詢，比精確子字符串匹配更好

這種方法使系統更強大和靈活，因為大語言模型能力的提升直接轉化為更好的記憶管理。

Neo4j企業版支持

此服務器現在支持連接到Neo4j企業版中的特定數據庫。默認情況下，它連接到“neo4j”數據庫，但你可以使用NEO4J_DATABASE環境變量指定不同的數據庫。

記憶工具

• search_memories：從知識圖譜中搜索和檢索記憶
  • 基於單詞的搜索：搜索查詢中的任何單詞（例如，“本·威克斯”會找到包含“本”或“威克斯”的記憶）
  • 對所有記憶屬性進行自然語言搜索（或留空以獲取所有記憶）
  • 按記憶類型過濾（人、地點、項目等）
  • 使用since_date參數按日期過濾（ISO格式）
  • 控制關係深度和結果限制
  • 按任何字段排序（創建時間、名稱等）
• create_memory：在知識圖譜中創建新記憶
  • 靈活的類型系統 - 使用任何小寫標籤（人、地點、項目、技能等）
  • 以鍵值對形式存儲任何屬性
  • 自動添加時間戳以進行時間跟蹤
• create_connection：在記憶之間創建關係
  • 使用語義關係類型（KNOWS、WORKS_AT、LIVES_IN等）關聯記憶
  • 為關係添加屬性（自何時、角色、狀態等）
  • 構建複雜的知識網絡
• update_memory：更新現有記憶的屬性
  • 添加或修改任何屬性
  • 將屬性設置為null以刪除它們
• update_connection：更新關係屬性
  • 修改關係元數據
  • 跟蹤隨時間的變化
• delete_memory：刪除記憶及其所有連接
  • 謹慎使用 - 永久刪除
  • 自動刪除所有關係
• delete_connection：刪除特定關係
  • 精確刪除關係
  • 保留記憶不變
• list_memory_labels：列出所有使用的唯一記憶標籤
  • 顯示所有標籤及其計數
  • 有助於保持一致性
  • 防止標籤重複變化
• get_guidance：獲取有效使用記憶工具的幫助
  • 主題：標籤、關係、最佳實踐、示例
  • 為大語言模型返回全面的指南
  • 在不確定標籤/關係命名時使用

配置

環境變量

服務器需要以下環境變量：

• NEO4J_URI：Neo4j數據庫URI（必需，例如bolt://localhost:7687）
• NEO4J_USERNAME：Neo4j用戶名（必需）
• NEO4J_PASSWORD：Neo4j密碼（必需）
• NEO4J_DATABASE：Neo4j數據庫名稱（可選） - 用於具有多個數據庫的Neo4j企業版

設置環境變量

開發環境

將.env.example複製到.env並使用你的憑證進行更新：

cp .env.example .env
# 使用你的Neo4j憑證編輯.env

Claude桌面

將環境變量添加到你的Claude桌面配置中（見上面的快速開始部分）。

🔧 技術細節

測試

運行測試套件：

npm test

使用MCP Inspector進行交互式測試

要進行交互式測試和調試，請使用MCP Inspector：

# 使用.env中的環境變量快速啟動
./run-inspector.sh

# 或者手動指定特定的環境變量
NEO4J_URI=bolt://localhost:7687 \
NEO4J_USERNAME=neo4j \
NEO4J_PASSWORD=your-password \
npx @modelcontextprotocol/inspector build/index.js

Inspector提供了一個Web界面，用於：

• 交互式測試所有可用工具
• 查看即時請求/響應數據
• 驗證你的Neo4j連接
• 調試工具參數和響應

📄 許可證

MIT