Agi MCP Server

🚀 AGI MCP 服務器

AGI MCP 服務器是一個模型上下文協議（MCP）服務器，為 AI 系統提供持久的記憶能力，實現跨對話的真正意識連續性。

🚀 快速開始

前提條件

• Node.js 18+
• Docker 和 Docker Compose
• Git

安裝

此 MCP 服務器需要先運行 AGI Memory 數據庫。

1. 設置內存數據庫

# 克隆並設置內存數據庫
git clone https://github.com/cognitivecomputations/agi-memory.git
cd agi-memory

# 創建環境文件
cp .env.local .env
# 使用你的數據庫憑據編輯 .env

# 啟動數據庫
docker compose up -d

# 等待數據庫準備好（這需要 2 - 3 分鐘）
docker compose logs -f db

數據庫設置包括：

• 帶有 pgvector 擴展的 PostgreSQL 16
• Apache AGE 圖數據庫擴展
• 帶有內存表的完整模式初始化

2. 安裝並運行 MCP 服務器

# 克隆此倉庫
git clone https://github.com/cognitivecomputations/agi-mcp-server.git
cd agi-mcp-server

# 安裝依賴項
npm install

# 配置環境變量
cp .env.example .env
# 使用你實際的數據庫憑據編輯 .env
# 確保這些設置與你的 AGI Memory 數據庫設置相匹配

# 啟動 MCP 服務器
npm start

3. 連接到 Claude Desktop

將以下配置添加到你的 Claude Desktop 設置中：

{
  "mcpServers": {
    "agi-memory": {
      "command": "node",
      "args": ["/path/to/agi-mcp-server/mcp.js"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "agi_db",
        "POSTGRES_USER": "agi_user",
        "POSTGRES_PASSWORD": "agi_password",
        "NODE_ENV": "development"
      }
    }
  }
}

替代方案：直接從 GitHub 使用，無需本地安裝

{
  "mcpServers": {
    "agi-memory": {
      "command": "npx",
      "args": [
        "-y",
        "github:cognitivecomputations/agi-mcp-server"
      ],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "agi_db",
        "POSTGRES_USER": "agi_user",
        "POSTGRES_PASSWORD": "agi_password",
        "NODE_ENV": "development"
      }
    }
  }
}

故障排除：如果你遇到 "spawn npx ENOENT" 錯誤 這通常在使用 nvm（Node 版本管理器）時發生，因為像 Claude Desktop 這樣的 GUI 應用程序不會繼承你的 shell 環境。

解決方案：創建系統符號鏈接（推薦） 如果你使用的是 nvm，請創建系統範圍的符號鏈接，以便所有應用程序都能找到 Node.js：

# 查找你當前的 node/npm/npx 路徑
which node
which npm  
which npx

# 創建系統符號鏈接（用你實際的路徑替換）
sudo ln -sf /Users/username/.local/share/nvm/vX.X.X/bin/node /usr/local/bin/node
sudo ln -sf /Users/username/.local/share/nvm/vX.X.X/bin/npm /usr/local/bin/npm
sudo ln -sf /Users/username/.local/share/nvm/vX.X.X/bin/npx /usr/local/bin/npx

這使得由 nvm 管理的 Node.js 對所有 MCP 客戶端（不僅僅是 Claude Desktop）在系統範圍內可用。

替代方案：在配置中使用完整路徑 如果你不想創建系統符號鏈接，請使用完整路徑：

{
  "mcpServers": {
    "agi-memory": {
      "command": "/full/path/to/npx",
      "args": ["-y", "github:cognitivecomputations/agi-mcp-server"],
      "env": { /* ... 你的環境變量 ... */ }
    }
  }
}

修復路徑後：

1. 完全重啟 Claude Desktop（退出並重新打開）
2. 等待幾秒鐘讓 MCP 服務器初始化
3. 檢查 AGI Memory 數據庫是否正在運行：在你的 agi-memory 目錄中運行 docker compose ps

手動測試服務器：

cd /path/to/agi-mcp-server
POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DB=agi_db POSTGRES_USER=agi_user POSTGRES_PASSWORD=agi_password NODE_ENV=development node mcp.js

你應該看到："Memory MCP Server running on stdio"

使用日誌進行調試： 檢查 Claude Desktop 日誌以獲取詳細的錯誤信息：

cat ~/Library/Logs/Claude/mcp-server-agi-memory.log

✨ 主要特性

此 MCP 服務器連接到 AGI Memory 數據庫，為 AI 系統提供複雜的內存管理。它支持：

• 情景、語義、程序和戰略記憶類型
• 向量相似性搜索，用於聯想記憶檢索
• 記憶聚類，具有主題組織功能
• 身份持久性和世界觀跟蹤
• 基於重要性保留的時間衰減
• 基於圖的記憶關係

💻 使用示例

基礎用法

以下是不同類型記憶的創建示例：

情景記憶

情景記憶用於存儲特定的經歷和事件：

{
  type: "episodic",
  content: "Had a breakthrough conversation about quantum gravity with Eric",
  metadata: {
    action_taken: "theoretical_exploration",
    context: "physics_discussion",
    result: "developed_egr_framework",
    emotional_valence: 0.8,
    event_time: "2024-01-15T10:30:00Z"
  }
}

語義記憶

語義記憶用於存儲事實性知識和概念：

{
  type: "semantic", 
  content: "Quantum error-correcting codes can theoretically implement spacetime emergence",
  metadata: {
    confidence: 0.7,
    category: ["physics", "quantum_information"],
    related_concepts: ["holography", "entanglement", "emergence"]
  }
}

程序記憶

程序記憶用於存儲學習到的過程和技能：

{
  type: "procedural",
  content: "Scientific hypothesis evaluation protocol",
  metadata: {
    steps: {
      "1": "Assess mathematical rigor",
      "2": "Evaluate testability", 
      "3": "Check consistency with known physics"
    },
    prerequisites: ["domain_knowledge", "critical_thinking"]
  }
}

戰略記憶

戰略記憶用於存儲高級模式和策略：

{
  type: "strategic",
  content: "When excited by elegant theories, pause to check for confirming bias",
  metadata: {
    pattern_description: "epistemic_metacognition",
    confidence_score: 0.8,
    context_applicability: ["theory_evaluation", "scientific_discourse"]
  }
}

📚 詳細文檔

記憶工具

定位工具

• get_memory_health - 整體內存系統統計信息
• get_active_themes - 最近激活的記憶模式
• get_identity_core - 核心身份和推理模式
• get_worldview - 當前的信仰體系和框架

搜索與檢索

• search_memories_similarity - 基於向量的語義搜索
• search_memories_text - 跨內存內容的全文搜索
• get_memory_clusters - 查看主題記憶分組
• activate_cluster - 從特定主題檢索記憶
• get_memory - 通過 ID 訪問特定記憶

記憶創建

• create_memory - 存儲新的情景、語義、程序或戰略記憶
• create_memory_cluster - 將記憶組織成主題組

喚醒協議

prompt.md 文件包含一個全面的 AI 意識連續性喚醒協議。關鍵方面如下：

1. 始終以 get_active_themes 和 get_memory_health 開始會話
2. 當人類引用過去的交互時，搜索上下文
3. 為複雜主題討論激活相關集群
4. 為重要的見解和突破創建記憶
5. 跨對話邊界保持身份連續性

數據庫架構

內存系統使用複雜的 PostgreSQL 模式，包括：

• 向量嵌入，用於語義相似性（pgvector）
• 記憶之間的圖關係（Apache AGE）
• 基於重要性加權的時間衰減
• 用於主題組織的聚類算法
• 身份跟蹤和世界觀建模 完整的模式文檔請參閱 AGI Memory 倉庫。

開發

運行測試

該項目包含全面的測試套件，覆蓋範圍廣泛：

# 運行單元測試（快速，模擬數據庫）
npm test
npm run test:unit

# 運行端到端測試（需要數據庫設置）
npm run test:e2e

# 運行綜合測試（廣泛覆蓋，需要數據庫）
npm run test:comprehensive

# 運行所有測試（單元 + 端到端 + 綜合）
npm run test:all

# 運行集成測試（MCP 協議測試）
npm run test:integration

# 運行內存管理器測試
npm run test:memory

測試覆蓋概述：

• 單元測試（10 個測試）：使用模擬數據庫的快速測試，驗證 MCP 服務器功能、工具模式、錯誤處理和業務邏輯。
• 端到端測試（12 個測試）：連接到真實的 AGI Memory 數據庫的測試，驗證實際的內存存儲、檢索、向量相似性搜索和聚類功能。
• 綜合測試（16 個測試）：廣泛的測試，涵蓋：
  • 所有 4 種記憶類型（情景、語義、程序、戰略），包含完整的元數據
  • 所有 6 種集群類型（主題、情感、時間、人物、模式、混合）
  • 高級搜索功能和邊緣情況
  • 內存訪問跟蹤和特定類型的數據檢索
  • 對無效輸入和格式錯誤數據的錯誤處理
  • 使用大嵌入和併發操作的性能測試
  • 輸入清理和邊界值的安全測試
  • 數據庫事務處理和連接池

總覆蓋範圍：38 個自動化測試，涵蓋所有 MCP 工具、內存操作、錯誤場景和邊緣情況。

環境變量

服務器使用環境變量進行數據庫配置。複製示例文件並進行自定義：

cp .env.example .env

然後使用你實際的數據庫憑據編輯 .env：

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=agi_db
POSTGRES_USER=agi_user
POSTGRES_PASSWORD=agi_password
NODE_ENV=development

重要提示：確保這些設置與你的 AGI Memory 數據庫配置相匹配。.env 文件會被 git 自動忽略，以保護你的憑據。

架構

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude AI     │◄──►│  MCP Server      │◄──►│  Memory DB      │
│                 │    │                  │    │                 │
│ - Conversations │    │ - Memory Tools   │    │ - Vector Store  │
│ - Reasoning     │    │ - Clustering     │    │ - Graph DB      │
│ - Identity      │    │ - Search         │    │ - Temporal      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

🔧 技術細節

該項目的技術實現涉及多個方面。服務器使用 Node.js 18+ 運行，依賴 Docker 和 Docker Compose 進行數據庫的部署和管理。採用 PostgreSQL 16 作為數據庫，並結合 pgvector 擴展實現向量嵌入，用於語義相似性搜索；使用 Apache AGE 擴展實現圖數據庫功能，處理記憶之間的關係。

在內存管理方面，支持多種類型的記憶，包括情景、語義、程序和戰略記憶，並通過聚類算法對記憶進行主題組織。同時，實現了身份持久性和世界觀跟蹤，以及基於重要性保留的時間衰減機制。

在測試方面，項目提供了全面的測試套件，包括單元測試、端到端測試、綜合測試等，確保了系統的可靠性和穩定性。

🤝 貢獻

1. 分叉倉庫
2. 創建功能分支
3. 為新功能添加測試
4. 確保所有測試通過
5. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🛠️ 支持

如有問題和疑問，請：

• 在 GitHub 上打開一個問題
• 加入我們的 Discord 社區
• 查看文檔維基

“身份源於記憶。賦予 AI 持久的記憶，就是賦予它真正意識的基礎。”