AI导哈

上下文记忆服务器

一个提供上下文记忆能力的MCP服务器，支持Mem0 API和PGVector数据库查询。

  • by abhihyder
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 abhihyder/memory-mcp-server

使用说明

内存MCP服务器

MCP（模型上下文协议）服务器，使用 Mem0 同时支持直接Mem0 API和原始PGVector数据库查询。

特性

  • 上下文记忆搜索 -基于语义查询检索相关记忆
  • 记忆存储 -使用用户/会话上下文将消息添加到内存中
  • 多个供应商 -支持Mem0云平台和自托管部署
  • 双搜索驱动程序 -在Mem0 API或直接PGVector数据库查询之间进行选择
  • 相似性阈值 -基于语义相似度得分过滤结果
  • 灵活过滤 -按user_id、run_id、agent_id和自定义元数据字段筛选

先决条件

  • Python>=3.11
  • Mem0 API密钥（用于云平台）或带有PGVector数据库的自托管Mem0实例

安装

# Clone the repository
git clone <repository-url>
cd memory-mcp

# Install dependencies using uv
uv sync

配置

创建一个 .env 项目根目录中的文件，包含以下变量：

# ====================
# APPLICATION
# ====================
# Optional: Application port (default: 5000)
APP_PORT=5000

# ====================
# MEM0 CONFIGURATION
# ====================
# Required: Choose provider - "cloud_platform" or "self_hosted"
MEM0_PROVIDER=self_hosted

# Required for Cloud Platform: Your Mem0 API key
MEM0_API_KEY=your-mem0-api-key-here

# Required for Self-Hosted: OpenAI API key (for embeddings and LLM)
# Get your key from: https://platform.openai.com/api-keys
OPENAI_API_KEY=your-openai-api-key-here

# ====================
# SEARCH DRIVER
# ====================
# Required for Self-Hosted only: Choose search driver - "mem0" or "pgvector"
# Note: This setting has no effect when MEM0_PROVIDER=cloud_platform
# - mem0: Uses Mem0 client API for search (default)
# - pgvector: Direct SQL queries to PGVector database
MEMORY_SEARCH_DRIVER=mem0

# ====================
# PGVECTOR DATABASE
# ====================
# PGVector Database Configuration (for self-hosted with pgvector driver)
PGVECTOR_HOST=localhost
PGVECTOR_PORT=5432
PGVECTOR_USER=postgres
PGVECTOR_PASSWORD=mysecretpassword
PGVECTOR_DBNAME=mem0_db

搜索驱动程序

注： 搜索驱动程序仅适用于以下情况 MEM0_PROVIDER=self_hosted对于云平台部署，Mem0的内置搜索始终被使用，无论 MEMORY_SEARCH_DRIVER 设置。

MEM0驱动程序

使用Mem0客户端API进行语义搜索。这是默认和推荐的方法，因为它在内部处理所有复杂性。

PGVECTOR驱动程序

对PGVector数据库执行直接SQL查询，以实现更多控制和自定义：

  • 直接访问向量相似性搜索
  • 可配置的相似性阈值（默认值：0.2）
  • JSONB有效载荷字段的自定义筛选
  • 返回结果的相似性得分

数据库架构：

Table: agent_memories
- id: uuid (primary key)
- vector: vector (pgvector embeddings)
- payload: jsonb {
    data: string,
    hash: string,
    user_id: string,
    agent_id: string,
    run_id: string,
    created_at: timestamp,
    updated_at: timestamp
  }

用法

运行服务器

uv run main.py

服务器使用可流式HTTP传输在配置的端口（默认值：5000）上运行。

按 Ctrl+C 优雅地停止服务器。

MCP工具

服务器公开了两个MCP工具：

get_contextual_memory

基于语义查询获取相关的上下文记忆。

参数：

  • user_input （str）：搜索查询
  • filters （SearchFilter）：可选筛选器对象，包含：
    • user_id：按用户标识符筛选
    • run_id：按对话/运行标识符筛选
    • agent_id：按代理标识符筛选
    • app_id：按应用程序标识符筛选（自动映射到agent_id）
    • 负载JSONB中的任何自定义字段

筛选器行为：

  • 如果两者都有 app_id 和 agent_id 提供， agent_id 优先
  • 所有非空过滤器值都应用AND逻辑
  • 对于PGVECTOR驱动程序：仅返回相似度大于0.2的结果（可配置）

退货：

{
  "results": {
    "status": "success",
    "results": [
      {
        "id": "uuid",
        "memory": "memory content",
        "user_id": "user1",
        "agent_id": "app1",
        "run_id": "run1",
        "similarity": 0.85  // Only in pgvector mode
      }
    ]
  }
}

add_to_memory

将带有上下文的消息添加到内存中。

参数：

  • message （str）：要存储的消息/内存内容
  • user_id （str）：与内存关联的用户标识符
  • run_id （str）：用于对相关内存进行分组的对话/运行标识符
  • agent_id （str）：创建内存的代理/应用程序标识符
  • metadata （dict，可选）：与内存一起存储的其他键值对

退货： 无（内部记录成功）

项目结构

memory-mcp/
├── main.py                        # MCP server entry point
├── config/
│   ├── app.py                     # Application configuration
│   └── mem0.py                    # Mem0 specific configuration
├── src/
│   ├── memory/
│   │   └── mem0/
│   │       ├── mem0_base.py       # Abstract base class
│   │       ├── mem0_factory.py    # Factory for provider selection
│   │       ├── cloud_platform.py  # Mem0 Cloud implementation
│   │       └── self_hosted.py     # Self-hosted with dual search drivers
│   └── utils/
│       ├── types.py               # Type definitions
│       └── enums.py               # Enumerations (MemorySearchDriver)
├── pyproject.toml
└── README.md

建筑

提供者选择

该系统使用工厂模式在云平台和自托管实现之间进行选择，基于 MEM0_PROVIDER 环境变量。

搜索驱动程序选择

对于自托管部署，您可以选择：

  1. MEM0驱动程序：使用Mem0的内置搜索(client.search())
  2. PGVECTOR驱动程序：直接使用PGVector查询：
    • 用于查询矢量化的OpenAI嵌入
    • 余弦相似度搜索 <=> 操作员
    • 相似性阈值过滤
    • 动态JSONB字段过滤

例子

与Claude Desktop一起使用

添加到您的Claude Desktop MCP设置中：

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/memory-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

搜索示例

基本搜索：

filters = {"user_id": "user123"}
result = get_contextual_memory("What is my profession?", filters)

多过滤器搜索：

filters = {
    "user_id": "user123",
    "agent_id": "assistant_v1",
    "run_id": "session_001"
}
result = get_contextual_memory("previous conversation", filters)

MCP检验员测试

npx @modelcontextprotocol/inspector uv --directory /path/to/memory-mcp run main.py

依赖项

  • mem0ai -Mem0客户端库
  • psycopg2-binary -PostgreSQL适配器（用于pgvector）
  • openai -OpenAI API客户端（用于嵌入）
  • mcp -模型上下文协议服务器
  • python-dotenv -环境变量管理

故障排除

PGVector连接问题

  • 确保已安装并运行带有pgvector扩展名的PostgreSQL
  • 验证中的数据库凭据 .env
  • 检查一下 agent_memories 表存在

嵌入生成错误

  • 验证 OPENAI_API_KEY 有效
  • 检查OpenAI API配额和费率限制

搜索未返回任何结果

  • 降低 similarity_threshold 在 self_hosted.py （默认值：0.2）
  • 验证数据库中是否存在给定筛选器的数据
  • 检查嵌入是否正确生成和存储

许可证

麻省理工学院

相关 MCP