内存MCP服务器

一种模型上下文协议（MCP）服务器，使用PostgreSQL和pgvector进行向量相似性搜索，提供语义记忆存储和检索。这是一个 代理记忆系统 其中LLM通过自然语言指令编排内存操作。

概述

Memory MCP服务器使AI助手能够存储、搜索和管理具有语义理解的持久记忆。与需要结构化查询的传统数据库不同，该系统接受自然语言指令，并使用LLM代理将其转换为内存操作。

主要特点

代理架构：LLM使用GPT-4/5和内部工具协调内存操作
语义搜索：PostgreSQL+pgvector用于混合搜索的快速相似性查询（向量+关键字）
动态优先级：记忆的优先级分数会随着时间的推移而衰减，并随着访问而增强
多项目隔离：每个项目都有自己独立的PostgreSQL数据库
元数据：自动提取主题、标签和语义记忆类型
内存生命周期：通过优化操作实现自动整合、重复数据删除和清理
多指标组织：将记忆组织到逻辑命名空间中（个人、工作、研究等）

快速开始

让内存MCP服务器在5分钟内运行：

# 1. Clone and install dependencies
git clone 
cd memory-mcp
npm install

# 2. Set up PostgreSQL database (automated)
./scripts/setup-postgres.sh

# 3. Configure environment
cp .env.example .env
# Edit .env and set your OPENAI_API_KEY

# 4. Start the server
npm run dev

服务器将通过STDIO启动并监听MCP工具调用。看配置详细设置和用法了解如何调用MCP工具。

建筑

内存MCP服务器使用分层架构：

┌─────────────────────────────────────────────────────────────────┐
│  MCP Layer (MemoryServer.ts)                                    │
│  • MCP tools: memorize, recall, forget, refine_memories,        │
│    create_index, list_indexes, scan_memories                    │
│  • STDIO transport for Claude Desktop integration               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Controller Layer (MemoryController.ts)                         │
│  • Security boundaries (ProjectFileLoader, IndexResolver)       │
│  • Index access validation                                      │
│  • Routes tool calls to agent modes                             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Agent Layer (MemoryAgent.ts)                                   │
│  • LLM orchestration (GPT-4/5) with mode-specific prompts       │
│  • Tool Runtime: search_memories, get_memories,                 │
│    upsert_memories, delete_memories, read_file,                 │
│    analyze_text, list_relationships                             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Repository Layer (MemoryRepositoryPostgres.ts)                 │
│  • PostgreSQL + pgvector data access                            │
│  • Embedding generation, semantic search                        │
│  • Access tracking, relationship management                     │
│  • Connection pooling per project (PoolManager.ts)              │
└─────────────────────────────────────────────────────────────────┘

支撑组件

快速经理：将基础+特定模式+主机/项目上下文组合到系统消息中
索引解析器：验证索引名称并提供默认索引逻辑
项目文件加载器：从具有大小限制的项目目录安全加载文件
优先级计算器：确定性优先级公式（最近度×0.4+重要性×0.4+使用率×0.2）

先决条件

PostgreSQL 14+ -支持向量扩展的数据库服务器
pg向量 -PostgreSQL向量相似性搜索扩展
Node.js 18+ -运行时环境
OpenAI API密钥 -用于生成嵌入和LLM编排

安装

自动设置（推荐）

运行安装脚本以自动创建数据库，启用pgvector，并运行迁移：

./scripts/setup-postgres.sh

脚本将：

检查PostgreSQL是否已安装并正在运行
创建 memory_default 数据库
启用pgvector扩展
运行架构迁移
验证设置

手动设置

如果您更喜欢手动设置，请按照以下步骤操作：

1.使用pgvector安装PostgreSQL

macOS（自制）

# Install PostgreSQL 14 or later
brew install postgresql@16

# Start PostgreSQL service
brew services start postgresql@16

# Install pgvector
brew install pgvector

Linux（Ubuntu/Debian）

# Install PostgreSQL
sudo apt update
sudo apt install postgresql postgresql-contrib

# Install build tools for pgvector
sudo apt install build-essential postgresql-server-dev-all

# Install pgvector from source
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

码头工人

# Use the official pgvector image
docker run -d \
  --name postgres-memory \
  -e POSTGRES_DB=memory_default \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  ankane/pgvector:latest

# Enable pgvector extension
docker exec -it postgres-memory psql -U postgres -d memory_default -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Run migrations
docker exec -i postgres-memory psql -U postgres -d memory_default  0.7",
  "responseMode": "both"
}

行为:

使用语义搜索（pgvector）+关键字搜索进行混合检索
优先级感知合成优先于高显著性记忆
自动访问跟踪更新内存优先级和访问计数
返回带有元数据的合成答案和/或原始内存记录

工具： `forget`

目的：使用LLM代理计划删除。支持模拟运行、元数据范围的删除和显式ID删除。

参数:

input （必填）：描述忘记什么的说明
index （可选）：索引覆盖
filters （可选）：用于缩小删除候选范围的元数据筛选器
projectSystemMessagePath （可选）：用于上下文化删除的系统消息路径
dryRun （可选）：默认值 true；当 false 代理执行已批准的删除操作
explicitMemoryIds （可选）：要立即删除的特定内存ID数组

示例-干运行（默认）:

{
  "input": "Forget all memories about the old API design that was replaced in December",
  "dryRun": true
}

示例-使用筛选器执行删除:

{
  "input": "Delete all low-priority temporary notes",
  "filters": {
    "memoryType": "episodic",
    "category": "temp"
  },
  "dryRun": false
}

示例-删除特定ID:

{
  "input": "Remove these obsolete memories",
  "explicitMemoryIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "dryRun": false
}

行为:

具有干运行保护的保守删除（默认）
Agent搜索匹配的记忆并解释将删除的内容
根据安全规则进行验证（例如，不能删除系统内存）
当 dryRun=false，执行已批准的删除操作
返回已删除内存的列表及其基本原理

工具： `refine_memories`

目的：通过整合、重复数据删除、重新排序和清理来管理存储的内存。代理分析内存并生成结构化的优化计划。

参数:

index （可选）：索引覆盖
operation （可选）：细化模式- "consolidation", "decay", "cleanup"，或 "reflection"
scope （可选）：控制考虑哪些记忆

- query：查找候选人的语义查询 - filters：元数据筛选器 - seedIds：从特定内存ID数组开始 - maxCandidates：要分析的最大内存

budget （可选）：要执行的最大操作数（默认从 MEMORY_REFINE_DEFAULT_BUDGET)
dryRun （可选）：仅计划模式 true （默认）
projectSystemMessagePath （可选）：项目特定上下文

示例-合并:

{
  "operation": "consolidation",
  "scope": {
    "query": "user preferences",
    "maxCandidates": 50
  },
  "dryRun": true
}

示例-衰减（重新确定优先级）:

{
  "operation": "decay",
  "budget": 100,
  "dryRun": false
}

示例-使用过滤器进行清理:

{
  "operation": "cleanup",
  "scope": {
    "filters": {
      "memoryType": "episodic"
    }
  },
  "dryRun": true
}

操作模式:

整合：合并重复项、创建摘要、检测矛盾、链接相关记忆
衰变：使用基于最近度、使用情况和重要性的确定性优先级公式对记忆进行重新排序
清理：将删除候选项（低优先级、已取代、过时）确定为模拟建议
反思：从相关记忆中生成高级摘要和模式

动作类型:

UPDATE：重新排序或添加记忆之间的关系
MERGE：整合重复或冗余的内存
CREATE：从多个相关记忆中生成摘要记忆
DELETE：删除过时或低优先级的内存（建议仅在模拟运行中使用）

行为:

Agent使用GPT-4/5进行复杂模式分析和规划
生成具有基本原理的结构化细化操作
根据安全规则验证操作（例如，不能删除系统内存）
返回包含行动和预期结果的改进计划
当 dryRun=false，执行批准的操作

工具： `create_index`

目的：为活动项目创建或确保存在PostgreSQL支持的内存索引。

参数:

name （必填）：新索引名称
description （可选）：与索引记录一起存储的人物描述

示例:

{
  "name": "work_notes",
  "description": "Professional work-related notes and decisions"
}

行为:

如果不存在，则创建新索引
如果索引已存在，则返回现有索引信息
索引以行的形式存储在 memory_indexes 桌子
每个项目可以有多个逻辑组织索引

工具： `list_indexes`

目的：列出所有PostgreSQL内存索引和文档计数，以便代理可以选择目标。

参数：无

示例:

{}

退货:

{
  "indexes": [
    {
      "name": "personal",
      "documentCount": 142,
      "pendingDocumentCount": 0,
      "project": "local"
    },
    {
      "name": "work_notes",
      "documentCount": 87,
      "pendingDocumentCount": 0,
      "project": "local"
    }
  ],
  "totalMemories": 229,
  "totalDiskBytes": 1048576
}

行为:

返回活动项目的所有索引
包括每个索引的文档计数（PostgreSQL后端的pendingDocumentCount始终为0）
提供聚合统计信息（totalMemories、totalDiskBytes）
帮助代理人为新记忆选择合适的索引
有助于理解记忆组织

工具： `scan_memories`

目的：运行直接PostgreSQL搜索，无需LLM编排。返回用于调试和检查的原始结果和诊断。

参数:

query （必填）：搜索查询文本
index （可选）：索引覆盖
limit （可选）：最大结果（默认10，最大1000）
filters （可选）：结构化元数据过滤器
filterExpression （可选）：高级筛选表达式字符串
semanticWeight （可选）：语义与关键字权重（0-1）
reranking （可选）：启用重新银行（默认为true）
includeMetadata （可选）：包括元数据有效载荷（默认为true）

示例:

{
  "query": "user preferences",
  "limit": 20,
  "semanticWeight": 0.7,
  "includeMetadata": true
}

行为:

绕过LLM代理直接查询PostgreSQL
可用于调试搜索质量和检查原始嵌入
返回具有相似性得分的原始搜索结果
包括有关查询执行的诊断
通常不用于正常操作（使用 recall 代替LLM合成答案）

故障排除

未找到pgvector扩展名

错误: ERROR: extension "vector" is not available

解决方案:

# Verify pgvector is installed
pg_config --sharedir
# Check if vector.control exists in /extension/

# Reinstall if needed (macOS)
brew reinstall pgvector

# Reinstall if needed (Linux)
cd pgvector && sudo make install

无法连接到数据库

错误: Error: connect ECONNREFUSED 或 FATAL: password authentication failed

解决方案:

# Check PostgreSQL is running
psql -U postgres -l

# Verify connection string in config/projects.json
# Check username, password, host, and port match your PostgreSQL setup

# Test connection manually
psql "postgresql://postgres:postgres@localhost:5432/memory_default"

CREATE EXTENSION的权限被拒绝

错误: ERROR: permission denied to create extension "vector"

解决方案:

# Connect as superuser (usually postgres)
psql -U postgres -d memory_default -c "CREATE EXTENSION vector;"

嵌入尺寸不匹配

错误: Error: Embedding dimension mismatch

原因：嵌入模型维度与数据库架构不匹配。

解决方案:

检查您配置的模型维度：

- text-embedding-3-small：1536个维度 - text-embedding-3-large：3072个尺寸

更新迁移以匹配：

-- For text-embedding-3-small (default)
embedding vector(1536)

-- For text-embedding-3-large
embedding vector(3072)

更新维度后重新运行迁移。

缺少OPENAI_API_KEY

错误: Error: OPENAI_API_KEY is required.

解决方案:

# Add your OpenAI API key to .env
echo "OPENAI_API_KEY=sk-your-api-key-here" >> .env

无效的MEMORY_ACTIVE_PROJECT

错误: Error: No active project configured

解决方案:

验证 MEMORY_ACTIVE_PROJECT 在 .env 匹配密钥 config/projects.json
确保 config/projects.json 存在并且是有效的JSON
检查项目的 databaseUrl 可访问的

未找到内存索引

错误: Error: Index not found

解决方案:

列出可用索引：调用 list_indexes 工具
创建索引：调用 create_index 具有所需名称的工具
检查 MEMORY_DEFAULT_INDEX 环境变量与现有索引匹配

服务器无法启动-关系“memories”不存在

错误: ERROR: relation "memories" does not exist 或 ERROR: relation "memory_indexes" does not exist

原因：数据库迁移尚未运行。

解决方案:

# Run the schema migration
psql -d memory_default -f migrations/20250117000001_init_postgres_schema.sql

# Verify tables were created
psql -d memory_default -c "\dt"

服务器无法启动-缺少依赖项

错误: Cannot find module '@modelcontextprotocol/sdk' 或类似的导入错误

解决方案:

# Install all dependencies
npm install

# Verify installation
npm list @modelcontextprotocol/sdk

Claude Desktop无法连接到MCP服务器

错误: Cannot connect to server on stdio 或MCP服务器没有响应

解决方案:

验证Claude Desktop配置中的MCP服务器路径是否正确
检查服务器是否成功启动： npm run dev （应显示无错误）
验证您的Claude Desktop MCP配置（通常在 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/absolute/path/to/memory-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "MEMORY_ACTIVE_PROJECT": "local"
      }
    }
  }
}

为了开发，使用 npm run build 编译TypeScript，然后指向 dist/index.js
查看Claude Desktop日志以获取更详细的错误消息

开发服务器错误

错误：期间出现各种TypeScript或运行时错误 npm run dev

解决方案:

# Clear any caches and reinstall
rm -rf node_modules package-lock.json
npm install

# Run linting and formatting
npm run lint:fix
npm run format

# Check TypeScript compilation
npm run build

云部署

霓虹

霓虹为无服务器PostgreSQL提供pgvector支持：

在以下位置创建新项目 console.neon.tech
在SQL编辑器中启用pgvector：

   CREATE EXTENSION IF NOT EXISTS vector;

运行架构迁移：

   -- Copy contents of migrations/20250117000001_init_postgres_schema.sql

将连接字符串复制到 config/projects.json:

   {
     "production": {
       "databaseUrl": "postgresql://user:password@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require"
     }
   }

Supabase

Supabase 默认情况下包含pgvector：

在以下位置创建新项目掌声。
转到SQL编辑器并运行：

   CREATE EXTENSION IF NOT EXISTS vector;

在SQL编辑器中运行架构迁移
从“项目设置”复制连接字符串→ 数据库：

   {
     "production": {
       "databaseUrl": "postgresql://postgres:your-password@db.xxxxxxxxxxxx.supabase.co:5432/postgres"
     }
   }

其他PostgreSQL提供商

任何支持pgvector的PostgreSQL 14+提供程序都可以工作：

AWS RDS for PostgreSQL（带pgvector扩展）
PostgreSQL的谷歌云SQL
PostgreSQL的Azure数据库
DigitalOcean管理数据库
自托管PostgreSQL实例

附加文档

docs/CHARACTER_MEMORY.md -人工智能字符和不完美记忆行为的设计原则
docs/SIMULATED_BRAIN.md -记忆系统如何通过衰减、巩固和扩散激活来模拟类似人类的认知
docs/BACKDATING_GUIDE.md -历史记忆摄取综合指南，包括优先级衰减计算和实例
迁移/20250117000001_init_postgres_schema.sql -数据库模式和迁移
脚本/setup-postgres.sh -自动设置脚本
CLAUDE.md -使用此代码库的开发人员指南
提示/README.md -可组合提示系统文档

许可证

私人-仅供内部使用

Memory MCP Legacy

快速接入

详细介绍

内存MCP服务器

概述

主要特点

快速开始

建筑

支撑组件

先决条件

安装

自动设置（推荐）

手动设置

1.使用pgvector安装PostgreSQL

工具： forget

工具： refine_memories

工具： create_index

工具： list_indexes

工具： scan_memories

故障排除

未找到pgvector扩展名

无法连接到数据库

CREATE EXTENSION的权限被拒绝

嵌入尺寸不匹配

缺少OPENAI_API_KEY

无效的MEMORY_ACTIVE_PROJECT

未找到内存索引

服务器无法启动-关系“memories”不存在

服务器无法启动-缺少依赖项

Claude Desktop无法连接到MCP服务器

开发服务器错误

云部署

霓虹

Supabase

其他PostgreSQL提供商

附加文档

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

工具： `forget`

工具： `refine_memories`

工具： `create_index`

工具： `list_indexes`

工具： `scan_memories`