AI导哈

语义记忆服务

memory-mcp 是一个为AI代理提供持久、自组织语义记忆的MCP服务器，支持记忆的存储、检索和推理，适用于需要长期记忆管理的AI应用场景。

  • by isaacriehm
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 isaacriehm/memory-mcp

使用说明

存储器mcp

AI代理的持久、自组织语义记忆——充当MCP服务器。

这是什么？

内存mcp是一个 模型上下文协议 服务器，为人工智能代理提供持久、可搜索的内存，由PostgreSQL和 pgvector。将其放入任何兼容MCP的客户端（Claude Code、Cursor、Windsurf等），您的代理就可以跨会话记住、检索和推理信息，而无需管理任何模式或存储逻辑。

它自主地做什么：

  • 分块并嵌入传入文本
  • 将记忆分类为层次分类法(ltree 点路径）
  • 消除现有记忆的重复并解决冲突
  • 合成a 系统入门 --它所知道的一切的压缩的、始终最新的摘要，并在会话开始时显示出来
  • 通过TTL和验证老化事实的提示使陈旧记忆过期

为什么是记忆mcp？

内存mcp 简单向量DB LangChain/LlamaIdex内存
模式管理 自动 手动 手动
重复数据删除 语义+LLM 无 无
分类 自动分配ltree 无 无
会话引导 系统入门 手动RAG 手动
冲突解决 已评估LLM 无 无
短暂上下文 内置（TTL存储） 否 否
可自托管 是（Docker） 不同 否
MCP本机 是 否 否

建筑

AI Agent (Claude Code / Cursor / Windsurf)
        │  HTTP (MCP — Streamable HTTP)
        ▼
┌──────────────────────────────────────────┐
│              server.py                    │
│  ┌─────────────────┐ ┌─────────────────┐ │
│  │ Production MCP  │ │   Admin MCP     │ │
│  │   :8766/mcp     │ │   :8767/mcp     │ │
│  └────────┬────────┘ └────────┬────────┘ │
│           │  tools/           │           │
│  ┌────────▼──────────────────▼────────┐  │
│  │  ingestion · search · context      │  │
│  │  crud · admin_tools · context_store│  │
│  └────────────────┬───────────────────┘  │
│                   │                       │
│  ┌────────────────▼───────────────────┐  │
│  │         Background Workers          │  │
│  │  Ingestion Queue · TTL Daemon       │  │
│  │  System Primer Auto-Regeneration    │  │
│  └────────────────┬───────────────────┘  │
└───────────────────┼──────────────────────┘
                    │  asyncpg
                    ▼
         PostgreSQL + pgvector
         ┌─────────────────┐
         │ memories        │  chunks, embeddings, ltree paths
         │ memory_edges    │  sequence_next, relates_to, supersedes
         │ ingestion_staging│ async job queue
         │ context_store   │  ephemeral TTL store
         └─────────────────┘
                    │
         ┌──────────▼──────────┐
         │  Backup Service     │  pg_dump → private GitHub repo
         └─────────────────────┘

两台服务器，一个进程：

  • 生产 (:8766)--代理人可以自由调用的安全工具
  • 管理员 (:8767)--超集，包括破坏性工具（删除、修剪、批量移动）。让你的代理人去生产；使用admin进行维护。

快速入门（Docker）

先决条件： Docker+Docker Compose，一个OpenAI API密钥。

# 1. Clone
git clone https://github.com/isaacriehm/memory-mcp.git
cd memory-mcp

# 2. Configure
cp .env.example .env
$EDITOR .env   # set OPENAI_API_KEY and DB_PASSWORD at minimum

# 3. Start
docker compose up -d

# Production MCP endpoint: http://localhost:8766/mcp
# Admin MCP endpoint:      http://localhost:8767/mcp

要在代码更改后重建，请执行以下操作：

docker compose up -d --build memory-api

连接到MCP客户端

克劳德代码

添加到您的项目 .claude/settings.json 或 ~/.claude/settings.json:

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://localhost:8766/mcp"
    }
  }
}

或者通过CLI：

claude mcp add memory --transport http http://localhost:8766/mcp

然后将此说明添加到您的 CLAUDE.md 因此代理总是在会话开始时引导内存：

## Memory
At the start of every session, call `initialize_context` before anything else.
This returns your System Primer — your identity, current knowledge taxonomy, and retrieval guide.
Always consult it before answering questions about prior context.

光标/风帆

添加到MCP设置(.cursor/mcp.json 或同等）：

{
  "mcpServers": {
    "memory": {
      "url": "http://localhost:8766/mcp"
    }
  }
}

MCP工具

生产工具(:8766)

工具 说明
initialize_context 每次会议先打电话。 返回老化记忆的System Primer+验证提示。
memorize_context 摄取原始文本。自动分块、嵌入、分类和消除重复。支持 ttl_days 可选 metadata 提示（包括 tier 以（权力）否决
check_ingestion_status 按以下方式轮询异步摄取作业 job_id.退货 pending, processing, complete，或 failed.
search_memory 基于互易秩融合的混合向量+BM25搜索。支持在终止开关后进行可选的有界反馈重新排序。筛选依据 category_path；可选 task_type 范围反馈影响。不包括 reference.system.primer，仅由以下人员返回 initialize_context.
report_retrieval_outcome 记录检索反馈(+1 有用的， -1 没有帮助）。被取代的ID会自动解析到最新的活动内存。可选的 category_path/task_type 范围反馈影响。
list_categories 返回所有占用的分类路径和内存计数。
explore_taxonomy 钻入坍塌的地方 [+N more] 分支从 list_categories.
fetch_document 按照以下步骤重建完整文档 sequence_next 从内存ID中提取边缘
semantic_diff_memory 比较两个内存ID并返回语义 added/removed/changed 这意味着与风险注释存在差异。
trace_history 检查整个替代链（最旧的→ 最新的）以供记忆。
decision_timeline 按时间顺序返回决策事件(memory_created, memory_updated, memory_superseded, conflict_resolved)带有可选的类别/时间过滤器。
create_handoff_pack 在以下位置构建并存储确定性执行切换 handoff.<label> 并返回一个准备粘贴的简历提示。
contradiction_audit 使用可选的类别、解决方案和时间过滤器检查最近的冲突解决事件。
confirm_memory_validity 确认老化记忆仍然准确。推进其 verify_after 日期。
update_memory 在适当的位置重写内存的内容（保留身份、边缘、历史）。
set_context 使用TTL将键/值对写入临时上下文存储。
get_context 按键检索临时上下文条目。
list_context_keys 列出活动（未过期）上下文键，可选择按范围筛选。
delete_context 在TTL到期之前显式删除上下文条目。
extend_context_ttl 将上下文条目的过期时间向前推N小时。

仅限管理员的工具(:8767)

工具 说明
delete_memory 按ID硬删除内存（级联边）。
prune_history 批量删除超过N天的已取代内存。
export_memories 将所有活动内存导出为JSON。
recategorize_memory 将单个内存移动到新的分类路径。
bulk_move_category 移动整个分类分支（例如。 old.prefix → new.prefix).
update_memory_metadata 将内存的元数据JSONB修补到位。
run_diagnostics 关于池健康状况、内存计数、摄入队列深度的报告。
get_ingestion_stats 摄入作业状态细分。
flush_staging 立即清除所有已完成/失败的暂存作业。

反馈重新排名推出

有意保护反馈重新评级：

  • 基本检索（语义+关键字+RRF）始终保持为主。
  • 反馈是一种有界的二次调整(FEEDBACK_MAX_DELTA，默认值 0.05).
  • 多层地板可以保护顶级K的多样性(CANONICAL_MIN_IN_TOPK, HISTORICAL_MIN_IN_TOPK).
  • 历史记忆在重新排序之前会得到一个温和的基础分数乘数(HISTORICAL_BASE_SCORE_MULTIPLIER，默认值 0.85).
  • 重新存储关闭时，收藏可以继续。

立即回滚：

FEEDBACK_RERANK_ENABLED=false

分类学

使用PostgreSQL将内存组织成点路径层次结构 ltree系统在摄取过程中自动分配路径。您可以用以下命令覆盖 recategorize_memory 或 bulk_move_category.

项目分类 projects.* 在摄入过程中，从活跃的分类根中动态地导出。已知的根是首选；如果没有已知的根拟合和内容强烈预示着一个新的项目 projects.<slug> 根可以自动被接纳。

示例路径：

profile.identity.core
profile.health.medical
projects.myapp.architecture
projects.myapp.decisions
organizations.acme.business
concepts.ai.behavior
reference.system.primer     ← auto-generated System Primer lives here

搜索是子树感知的——传递 category_path: "projects.myapp" 返回该分支下的所有内容。

系统入门

initialize_context 返回存储在以下位置的合成摘要 reference.system.primer它包括：

  • 压缩的用户/代理配置文件
  • 包含内存计数的完整分类树
  • 检索指导

当摄入≥10个新记忆或之前的引物超过1小时时，引物会在后台自动再生。您可以通过管理工具强制再生 synthesize_system_primer.

环境变量

复制 .env.example 到 .env 并填写你的价值观。

必需的

变量 描述
DATABASE_URL PostgreSQL连接字符串（例如。 postgresql://user:pass@localhost:5432/memory)
OPENAI_API_KEY 用于嵌入和LLM调用的OpenAI API密钥
DB_PASSWORD PostgreSQL密码（Docker Compose使用）

可选--模型和嵌入

变量 默认值 描述
EMBEDDING_MODEL text-embedding-3-small OpenAI嵌入模型
EXTRACT_MODEL gpt-5-mini LLM用于语义段提取和分类
CONFLICT_MODEL gpt-5-nano 冲突/消除评估法学硕士
EMBED_DIM 1536 嵌入向量维度（必须与模型匹配）

可选--搜索和限制

变量 默认值 描述
DEFAULT_SEARCH_LIMIT 10 的默认结果计数 search_memory
DEFAULT_LIST_LIMIT 50 的默认结果计数 list_categories
DUP_THRESHOLD 0.95 重复数据删除的余弦相似性阈值
CONFLICT_THRESHOLD 0.55 冲突检测的相似性阈值
RELATES_TO_THRESHOLD 0.65 相似性阈值 relates_to 边缘创建
MIN_SECTION_LENGTH 100 要存储的块的最小字符长度
MAX_TAXONOMY_PATHS 40 每次摄入分配的最大分类路径

可选--反馈重新排序（受保护）

变量 默认值 描述
FEEDBACK_RERANK_ENABLED false 用于应用反馈重新分级的终止开关 search_memory.
FEEDBACK_MAX_DELTA 0.05 根据反馈调整的最大绝对分数（以基本分数为界）。
FEEDBACK_HALF_LIFE_DAYS 30 较旧反馈事件的指数衰减半衰期。
CANONICAL_MIN_IN_TOPK 2 当可用时，将最小规范内存保存在前K中。
HISTORICAL_MIN_IN_TOPK 1 在可用的情况下，将最低历史记忆保存在前K中。
FEEDBACK_EXPLORATION_SLOTS 0 为未充分探索的候选人保留的前K个名额的可选数量。
HISTORICAL_BASE_SCORE_MULTIPLIER 0.85 在反馈重新排序之前，将乘数应用于历史层基础检索分数。

可选--层推断

变量 默认值 描述
TIER_LLM_INFERENCE_ENABLED true 在摄取时启用LLM建议的内存层（显式/手动层仍然获胜）。

可选--OpenAI和并发

变量 默认值 描述
OPENAI_TIMEOUT_S 60 每请求OpenAI超时（秒）
OPENAI_MAX_RETRIES 5 指数回退重试限制
MAX_CONCURRENT_API_CALLS 5 并行OpenAI请求的信号量
EXTRACT_REASONING low 提取LLM的推理工作
CONFLICT_REASONING minimal 冲突推理LLM

可选--数据库

变量 默认值 描述
PG_POOL_MIN 1 asyncpg最小池连接数
PG_POOL_MAX 10 asyncpg最大池连接数
STAGING_RETENTION_DAYS 7 保留已完成/失败的暂存作业的天数

可选--身份验证

变量 默认值 描述
API_KEY （未设置） 生产服务器的静态承载令牌。也用作最小连接器桥中的OAuth客户端密钥。
OAUTH_CLIENT_ID api-key 连接器OAuth设置中应有OAuth网桥客户端id。
OAUTH_CLIENT_SECRET API_KEY OAuth网桥客户端机密应位于 /token （基本或POST正文）。
OAUTH_ALLOWED_REDIRECT_URIS https://claude.ai/api/mcp/auth_callback OAuth网桥重定向URI的可选逗号分隔列表
OAUTH_ISSUER （从请求URL自动） 在反向代理/CDN后面时，可选的显式发行者URL。

可选--服务器

变量 默认值 描述
PRODUCTION_PORT 8766 生产MCP服务器端口
ADMIN_PORT 8767 管理MCP服务器端口
MCP_TRANSPORT streamable-http FastMCP传输模式
FASTMCP_JSON_RESPONSE -- 设置为 1 强制JSON响应
LOG_LEVEL INFO DEBUG / INFO / WARNING

可选——系统底漆

变量 默认值 描述
PRIMER_UPDATE_MAX_AGE_S 3600 自动底漆再生前的最长秒数

可选--上下文存储

变量 默认值 描述
CONTEXT_DEFAULT_TTL_HOURS 24 上下文存储条目的默认TTL
CONTEXT_MAX_VALUE_LENGTH 50000 上下文值的最大字符长度
CONTEXT_MAX_KEY_LENGTH 200 上下文键的最大字符长度

可选--备份服务

变量 描述
GITHUB_PAT GitHub个人访问令牌 repo 范围
GITHUB_BACKUP_REPO 目标回购 owner/repo 格式
BACKUP_INTERVAL_SECONDS 备份间隔秒数（默认值： 21600 =6小时）

外部提供者身份验证

此服务器使用静态承载令牌身份验证(API_KEY)作为主要的安全模型。

设置API密钥：

API_KEY=your-generated-token

提供商端秘密映射：

  • 密钥id: api-key
  • 机密值：您的服务器 API_KEY 价值

然后，对生产服务器的每个请求都需要 Authorization: Bearer <token>.

支持秘密插值的客户端的标头模板：

Authorization: Bearer {{secrets.api-key}}

Claude Connect的最小OAuth桥

为了与Claude连接器兼容，服务器还公开了最小的OAuth路由：

  • GET /authorize
  • POST /token
  • /.well-known/oauth-authorization-server
  • /.well-known/oauth-protected-resource

桥梁行为故意最小化：

  1. OAuth client_id 必须匹配 OAUTH_CLIENT_ID （默认值 api-key).
  2. OAuth client_secret 必须匹配 OAUTH_CLIENT_SECRET （默认为 API_KEY).
  3. 成功的代币交换将返回不记名代币 API_KEY 用于MCP呼叫。

这使API-key身份验证保持为唯一的凭据，同时满足连接器OAuth路由期望。

MCP客户端配置（外部，带身份验证）：

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "https://your-public-url/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}

WireGuard/可信网络（无身份验证）：

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://10.x.x.x:8766/mcp"
    }
  }
}

同一服务器处理直接承载使用和映射到的连接器OAuth握手 API_KEY.

本地运营（开发）

要求：Python 3.11+，PostgreSQL pgvector.

# Create and activate virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure
cp .env.example .env
$EDITOR .env

# Start the server
python -m server
# Production: http://0.0.0.0:8766
# Admin:      http://0.0.0.0:8767

备份服务

这 backup/ 目录包含一个容器化的PostgreSQL备份作业，该作业：

  1. 跑 pg_dump 在配置的时间间隔上（默认值：每6小时一次）
  2. 将转储提交到私有GitHub存储库

备份服务会自动启动 docker compose up.Set GITHUB_PAT 和 GITHUB_BACKUP_REPO 在你的 .env 如果未设置这些变量，服务将在启动时出错--删除 memory-backup 服务从 docker-compose.yml 如果你不需要备份。

CLI脚本

独立脚本 scripts/ （要求 DATABASE_URL 在环境中）：

# Export all memories to a timestamped JSON file
python scripts/export_memories.py

# Generate an interactive graph visualization
python scripts/visualize_memories.py
open memory_map.html

贡献

看 贡献.md.

许可证

麻省理工学院

相关 MCP