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 持久的记忆，就是赋予它真正意识的基础。”