概述

MCP Memory Service 是一个基于 MCP（Model Context Protocol）架构的语义记忆存储与检索服务。该项目为 AI 应用提供持久化记忆能力，支持语义搜索、时间范围查询、标签分类等高级功能。 资料来源：README.md:1-10

核心功能

记忆存储与管理

系统提供完整的记忆生命周期管理，包括存储、检索、删除和更新操作。每条记忆自动生成内容哈希和语义向量嵌入，便于精确匹配和相似性搜索。 资料来源：src/mcp_memory_service/web/app.py:20-50

语义搜索能力

基于向量嵌入的语义相似度搜索是本项目的核心特性。用户可以使用自然语言查询，系统自动计算查询向量与存储记忆的余弦相似度，返回最相关的结果。 资料来源：src/mcp_memory_service/api/__init__.py:10-25

实时事件流

通过 Server-Sent Events（SSE）技术，系统支持实时记忆事件推送。客户端可以订阅记忆创建、更新、删除等事件，实现与外部系统的实时集成。 资料来源：src/mcp_memory_service/web/app.py:55-70

技术架构

系统组件

graph TD
    A[Claude Code / MCP Client] --> B[MCP Memory Service]
    B --> C[API Layer]
    C --> D[Memory Service]
    D --> E[Storage Backend]
    E --> F[SQLite-vec]
    E --> G[Cloudflare D1]
    H[Hooks / Commands] --> B

存储后端

系统支持多种存储后端配置：

资料来源：src/mcp_memory_service/web/app.py:120-135

嵌入模型

系统默认使用 all-MiniLM-L6-v2 嵌入模型，该模型在性能和精度之间取得良好平衡：

• 向量维度：384
• 上下文窗口：256 tokens
• 平均延迟：5-10ms（后续调用）

资料来源：src/mcp_memory_service/web/app.py:140-145

API 接口

记忆管理接口

资料来源：src/mcp_memory_service/web/app.py:15-45

搜索接口

事件接口

CLI 命令集成

系统提供一系列 Claude Code CLI 命令，方便在终端环境中操作记忆：

可用命令

资料来源：claude_commands/README.md:15-50

安装方式

# 自动安装（推荐）
python scripts/installation/install.py

# 强制安装命令
python scripts/installation/install.py --install-claude-commands

Claude Hooks 集成

系统提供自动化记忆管理钩子，深度集成到 Claude Code 工作流中：

钩子类型

资料来源：claude-hooks/README.md:10-30

配置选项

{
  "memoryService": {
    "endpoint": "https://your-server:8443",
    "apiKey": "your-api-key"
  },
  "verbosity": {
    "verbose": true,
    "showMemoryDetails": false,
    "cleanMode": false
  }
}

性能指标

响应时间

成本估算

• 费用: $0.15/1M tokens
• 10用户部署年费: $16.43/年

资料来源：src/mcp_memory_service/api/__init__.py:5-15

维护工具

系统提供完整的维护脚本支持：

资料来源：scripts/maintenance/README.md:10-40

插件系统

系统支持插件扩展机制，允许开发者自定义钩子处理逻辑：

# 插件注册示例
def register(ctx):
    ctx.on("on_store", my_store_handler)
    ctx.on("on_retrieve", my_retrieve_handler)

插件通过 entry_points 机制自动加载：

[project.entry-points."mcp_memory_service.plugins"]
my_plugin = "my_package:register"

资料来源：examples/plugin-audit-log/README.md:20-35

快速开始

安装依赖

pip install mcp-memory-service

启动服务

mcp-memory-http

验证安装

curl https://localhost:8443/api/health

基础使用示例

from mcp_memory_service.api import search, store, health

# 存储记忆
hash_id = store("New memory", tags=["note", "important"])

# 语义搜索
results = search("architecture decisions", limit=5)
for m in results.memories:
    print(f"{m.hash}: {m.preview[:50]}...")

# 健康检查
info = health()
print(f"Backend: {info.backend}, Count: {info.count}")

资料来源：src/mcp_memory_service/api/__init__.py:20-40

技术栈

总结

MCP Memory Service 为 AI 应用提供了一个功能完整、高性能、可扩展的记忆存储解决方案。通过 MCP 协议与 Claude Code 的深度集成，以及丰富的 CLI 命令和 Hooks 机制，该服务能够无缝融入现有的 AI 开发工作流程，成为智能应用的"外部大脑"。

系统要求

资料来源：claude-hooks/README.md:44-49

安装方式

方式一：完整安装（推荐）

完整安装包含 HTTP 服务器、Claude Code 钩子和命令：

cd mcp-memory-service
python scripts/installation/install.py

安装脚本会依次安装：

1. HTTP 服务器及其依赖
2. Claude Code 钩子（自动记忆加载和存储）
3. Claude Code 命令（手动记忆操作）
4. 交互式 API 文档

资料来源：scripts/installation/install.py - 主安装脚本

方式二：分步安装

#### 步骤 1：安装 HTTP 服务器

pip install mcp-memory-service
mcp-memory-http  # 启动服务器

服务器默认在 https://localhost:8443 运行。

#### 步骤 2：安装 Claude Code 钩子

cd claude-hooks
python install_hooks.py  # 安装所有功能

或安装特定功能：

python install_hooks.py --basic             # 基础记忆钩子
python install_hooks.py --natural-triggers  # 自然记忆触发器

资料来源：claude-hooks/README.md:38-51

#### 步骤 3：安装 Claude 命令

cd claude_commands
claude /install-commands

或使用安装脚本：

python scripts/installation/install.py --install-claude-commands

资料来源：claude_commands/README.md:32-45

配置

Claude Desktop 配置

在 Claude Desktop 配置文件中添加 MCP 服务器：

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["mcp-memory-service"],
      "env": {
        "MCP_MEMORY_DB_PATH": "~/.local/share/mcp-memory/sqlite_vec.db"
      }
    }
  }
}

资料来源：examples/claude_desktop_config_template.json - Claude Desktop 配置模板

钩子配置

编辑 ~/.claude/hooks/config.json 配置记忆服务连接：

{
  "memoryService": {
    "endpoint": "https://your-server:8443",
    "apiKey": "your-api-key"
  },
  "verbosity": {
    "verbose": true,
    "showMemoryDetails": false,
    "cleanMode": false
  }
}

资料来源：claude-hooks/README.md:66-75

服务启动

启动 HTTP 服务器

# 使用默认配置
mcp-memory-http

# 或使用自定义配置
mcp-memory-http --host 0.0.0.0 --port 8080

验证安装

# 检查服务健康状态
curl -k https://localhost:8443/api/health

# 验证钩子安装
claude --debug hooks

资料来源：claude-hooks/README.md:53-56

API 快速使用

Python API

from mcp_memory_service.api import search, store, health

# 搜索记忆（20 tokens）
results = search("架构决策", limit=5)
for m in results.memories:
    print(f"{m.hash}: {m.preview[:50]}...")

# 存储记忆（15 tokens）
hash_id = store("新记忆", tags=["笔记", "重要"])
print(f"已存储: {hash_id}")

# 健康检查（5 tokens）
info = health()
print(f"后端: {info.backend}, 数量: {info.count}")

资料来源：src/mcp_memory_service/api/__init__.py:1-20

REST API 端点

资料来源：src/mcp_memory_service/web/app.py:1-50

Claude 命令速查

资料来源：claude_commands/README.md:1-30

插件系统

安装插件

创建包含入口点的 Python 包：

[project.entry-points."mcp_memory_service.plugins"]
my_plugin = "my_package:register"

实现插件

def register(ctx):
    ctx.on("on_store", my_store_handler)
    ctx.on("on_retrieve", my_retrieve_handler)

可用钩子

资料来源：examples/plugin-audit-log/README.md:1-40

性能指标

资料来源：src/mcp_memory_service/api/__init__.py:10-16

故障排除

资料来源：claude-hooks/README.md:58-68

后续步骤

• 查看 维护脚本 了解数据库优化
• 配置 Litestream 实现自动备份
• 探索插件系统扩展功能

概述

MCP Memory Service 是一个基于 Model Context Protocol (MCP) 的语义记忆服务系统，旨在为 AI 助手和开发者提供持久化、可搜索的上下文记忆能力。该系统通过向量嵌入技术实现语义相似度搜索，支持跨机器同步，并提供多种访问接口包括 MCP 协议、REST API、CLI 命令和 Web 界面。

系统的核心设计理念是创建一个轻量级但功能强大的记忆服务，使得 AI 能够在多轮对话和跨会话场景中保持上下文连续性。通过自动嵌入生成、智能标签管理和关系图谱构建，系统能够高效地组织和检索记忆内容。

概述

存储后端是 MCP Memory Service 的核心组件，负责管理记忆数据的持久化存储和向量嵌入检索功能。该服务支持多种存储后端实现，允许用户根据性能需求、部署环境和成本考虑选择最适合的解决方案。

MCP Memory Service 采用模块化存储架构，通过统一的抽象接口支持不同后端实现的无缝切换，同时保证数据模型和操作语义的一致性。资料来源：src/mcp_memory_service/storage/__init__.py

架构设计

存储后端层次结构

graph TD
    A[MCP Memory Service] --> B[存储抽象层]
    B --> C[工厂模式选择器]
    C --> D[SQLite Vec 后端]
    C --> E[Cloudflare 后端]
    C --> F[Milvus 后端]
    C --> G[Hybrid 混合后端]
    C --> H[Milvus Graph 后端]

核心存储接口

所有存储后端必须实现统一的抽象接口，确保功能一致性和可替换性：

资料来源：src/mcp_memory_service/storage/factory.py

支持的存储后端

SQLite Vec 后端

SQLite Vec 是默认且推荐的本地存储后端，适用于单机部署场景。

核心特性：

• 完全本地化部署，数据隐私保护
• 使用 SQLite 存储结构化数据
• 使用 sqlite-vec 扩展处理向量嵌入
• 支持 ACID 事务保证数据一致性
• 首次调用约 50ms（含存储初始化）
• 后续调用约 5-10ms（连接复用）
• 内存开销小于 10MB
• 成本估算：每 10 用户部署约 $16.43/年（按 $0.15/1M tokens）

配置参数：

资料来源：src/mcp_memory_service/storage/sqlite_vec.py 资料来源：src/mcp_memory_service/api/__init__.py

Cloudflare 后端

Cloudflare 后端使用 Cloudflare Workers Vectorize 实现云端向量存储，适合无服务器部署场景。

核心特性：

• 完全托管的云端向量数据库
• 无需管理服务器基础设施
• 全球分布式低延迟访问
• 按使用量付费的成本模型
• 支持 HTTP/HTTPS 自动检测连接

配置要求：

适用场景：

• Serverless 架构部署
• 需要全球化访问的项目
• 不想维护本地基础设施的用户

资料来源：src/mcp_memory_service/storage/cloudflare.py 资料来源：docs/cloudflare-setup.md

Milvus 后端

Milvus 是高性能的分布式向量数据库，适合大规模数据场景。

核心特性：

• 支持十亿级向量规模
• 分布式水平扩展能力
• 多种索引类型支持（IVF、HNSW 等）
• 高并发查询处理
• 支持混合标量过滤

配置参数：

资料来源：src/mcp_memory_service/storage/milvus.py 资料来源：docs/milvus-backend.md

Milvus Graph 后端

Milvus Graph 是 Milvus 后端的增强版本，集成了图数据库能力，提供关系型记忆检索。

扩展功能：

• 记忆间关系图的存储和查询
• 支持复杂的多跳关系推理
• 关系类型推断引擎
• 路径查询支持

资料来源：src/mcp_memory_service/storage/milvus_graph.py

Hybrid 混合后端

Hybrid 后端支持同时使用多个存储后端，实现数据冗余和负载分发。

架构特点：

graph LR
    A[写入请求] --> B[主存储]
    A --> C[备份存储]
    B --> D[向量数据]
    C --> D
    E[读取请求] --> F[负载均衡]
    F --> B
    F --> C

优势：

• 数据冗余备份，提高可靠性
• 读写分离提升性能
• 支持渐进式迁移
• 故障自动切换

资料来源：src/mcp_memory_service/storage/hybrid.py

工厂模式与后端选择

存储工厂

存储工厂根据配置自动实例化相应的存储后端：

# 后端选择逻辑伪代码
def create_storage(backend_type: str, config: dict) -> BaseStorage:
    backends = {
        "sqlite_vec": SQLiteVecStorage,
        "cloudflare": CloudflareStorage,
        "milvus": MilvusStorage,
        "milvus_graph": MilvusGraphStorage,
        "hybrid": HybridStorage,
    }
    return backends.get(backend_type)(config)

资料来源：src/mcp_memory_service/storage/factory.py

环境变量配置

后端选择通过环境变量控制：

后端选择决策树

graph TD
    A[选择存储后端] --> B{部署环境?}
    B -->|本地/单机| C[SQLite Vec]
    B -->|Serverless| D[Cloudflare]
    B -->|大规模/分布式| E[Milvus]
    B -->|需要图关系| F[Milvus Graph]
    B -->|高可用需求| G[Hybrid]
    C --> H[默认推荐]
    D --> I[低成本起步]
    E --> J[高性能扩展]
    F --> K[关系推理]
    G --> L[容错备份]

数据模型

记忆数据结构

所有存储后端使用统一的数据模型：

记忆类型分类

系统支持标准化的 24 类记忆类型：

内容类型：note、reference、document、guide

活动类型：session、implementation、analysis

其他分类：fix、solution、decision 等

资料来源：scripts/maintenance/README.md

向量嵌入

嵌入模型

默认使用 BAAI/bge-m3 模型：

嵌入维度迁移

系统提供嵌入模型迁移脚本：

python maintenance/migrate_embeddings.py --url <backend_url> --model <new_model> --dry-run

功能特性：

• 支持维度变更
• 干运行模式预览
• 批量更新处理
• 回滚支持

资料来源：scripts/README.md

数据库迁移

Litestream 实时复制

支持使用 Litestream 进行数据库实时复制和灾难恢复：

支持的平台：

配置示例（macOS plist）：

<dict>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/litestream</string>
        <string>replicate</string>
        <string>-config</string>
        <string>{config_path}</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>

资料来源：src/mcp_memory_service/sync/litestream_config.py

维护工具

记忆类型规范化

consolidate_memory_types.py 脚本用于合并碎片化的记忆类型：

# 预览更改（只读）
python scripts/maintenance/consolidate_memory_types.py --dry-run

# 执行合并
python scripts/maintenance/consolidate_memory_types.py

# 使用自定义配置
python scripts/maintenance/consolidate_memory_types.py --config custom_mappings.json

性能指标：

• 1,000 条记忆更新约 5 秒
• 自动创建带时间戳的备份
• 事务安全（原子操作，失败回滚）

安全特性：

• 自动备份机制
• 干运行模式预览
• 数据库锁检测
• 磁盘空间验证
• 备份完整性检查

资料来源：scripts/maintenance/README.md

修复和维护脚本

资料来源：scripts/README.md

性能比较

资料来源：src/mcp_memory_service/api/__init__.py

配置示例

SQLite Vec 配置

{
  "backend": "sqlite_vec",
  "db_path": "~/.local/share/mcp-memory/",
  "embedding_model": "BAAI/bge-m3",
  "embedding_dim": 1024
}

Cloudflare 配置

{
  "backend": "cloudflare",
  "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
  "CLOUDFLARE_API_TOKEN": "your-api-token",
  "vectorize_index_name": "memories-index",
  "embedding_model": "BAAI/bge-m3"
}

Milvus 配置

{
  "backend": "milvus",
  "MILVUS_HOST": "localhost",
  "MILVUS_PORT": 19530,
  "MILVUS_USER": "username",
  "MILVUS_PASSWORD": "password",
  "COLLECTION_NAME": "memories",
  "INDEX_TYPE": "HNSW"
}

扩展阅读

• 存储后端完整指南
• Milvus 后端配置
• Cloudflare 设置指南
• 数据库维护脚本

概述

MCP Memory Service 的知识图谱模块是系统的核心组件之一，负责管理和维护记忆之间的语义关系。与传统的关系型存储不同，知识图谱通过节点（记忆）和边（关联）的方式组织数据，使得复杂的关联查询和推理成为可能。

知识图谱系统的主要目标包括：

• 语义关联：自动发现并建立记忆之间的语义关联
• 关系推理：基于现有关系推断新的潜在关联
• 图查询：支持基于图结构的复杂查询操作
• 上下文增强：为 AI 推理提供丰富的上下文关系网络

架构设计

核心组件

知识图谱系统由以下几个核心模块组成：

架构层次

graph TB
    subgraph "表现层"
        A[Graph API Handlers]
    end
    
    subgraph "服务层"
        B[Relationship Inference Engine]
        C[Entity Recognition Module]
        D[Inference Processor]
    end
    
    subgraph "存储层"
        E[Graph Storage]
        F[Association Models]
    end
    
    A --> B
    A --> C
    B --> D
    C --> D
    D --> E
    F --> E
    
    G[(Vector Embeddings)] --> B
    G --> C

关联模型

数据结构

关联模型 (Association) 是知识图谱的边，连接两个记忆节点：

class Association:
    source_hash: str      # 源记忆哈希
    target_hash: str      # 目标记忆哈希
    relation_type: str    # 关系类型
    confidence: float    # 置信度 0.0-1.0
    metadata: Dict        # 额外元数据

非对称关系

系统支持非对称关系的建模，这是知识图谱的核心特性之一。资料来源：docs/migrations/010-asymmetric-relationships.md

graph LR
    A[记忆 A] -->|"基于"| B[记忆 B]
    B -->|"衍生自"| A

非对称关系意味着：

• 关系方向有实际意义
• A→B 与 B→A 表示不同的语义
• 支持更精确的因果和依赖建模

关系类型

实体识别

实体识别模块 (entities.py) 负责从记忆内容中提取有意义的实体：

提取流程

graph TD
    A[记忆内容] --> B[文本预处理]
    B --> C[命名实体识别]
    C --> D[实体消歧]
    D --> E[实体标准化]
    E --> F[实体图谱]

实体类型

识别并支持的实体类型包括：

资料来源：src/mcp_memory_service/reasoning/entities.py

推理引擎

推理引擎是知识图谱的智能核心，基于现有关联推断新的潜在关系。

推理方法

置信度计算

graph LR
    A[关系证据] --> B{证据强度}
    B -->|强| C[高置信度 0.8-1.0]
    B -->|中| D[中置信度 0.5-0.8]
    B -->|弱| E[低置信度 0.2-0.5]

置信度计算考虑因素：

1. 共现频率：两个记忆在同一上下文中出现的次数
2. 语义相似度：基于向量的余弦相似度
3. 关系传递路径：推理路径的长度
4. 来源可靠性：记忆来源的可信度评分

资料来源：src/mcp_memory_service/reasoning/inference.py

图存储

存储架构

图存储模块 (graph.py) 负责将图数据持久化：

graph TB
    subgraph "存储层"
        A[(SQLite Vec)]
        B[(向量索引)]
        C[(关系统引)]
    end
    
    subgraph "索引"
        D[哈希索引]
        E[关系类型索引]
        F[时间索引]
    end
    
    A --> D
    A --> E
    A --> F
    B --> D
    C --> E

存储优化

• 批量写入：支持批量关联写入以提高性能
• 增量更新：仅更新变化的关联
• 索引维护：自动维护关系类型和哈希索引

资料来源：src/mcp_memory_service/storage/graph.py

API 接口

图查询端点

系统通过 REST API 提供图查询能力：

请求示例

# 获取记忆的所有关联
curl -X GET "http://localhost:8443/api/graph/related/abc12345"

# 执行推理查询
curl -X POST "http://localhost:8443/api/graph/infer" \
  -H "Content-Type: application/json" \
  -d '{"source_hash": "abc123", "depth": 2}'

资料来源：src/mcp_memory_service/server/handlers/graph.py

关联推断系统

批量推断流程

关联推断模块 (relationship_inference.py) 提供批量关联优化功能：

graph TD
    A[加载现有关联] --> B[分析关联质量]
    B --> C{质量评估}
    C -->|低| D[标记待优化]
    C -->|高| E[保留]
    D --> F[执行推断]
    F --> G[验证推断结果]
    G --> H[更新关联数据]
    H --> I[生成报告]

优化策略

执行命令

# 预览优化效果（不执行）
python scripts/maintenance/update_graph_relationship_types.py --dry-run

# 执行优化
python scripts/maintenance/update_graph_relationship_types.py

资料来源：src/mcp_memory_service/consolidation/relationship_inference.py

关联管理

关联生命周期

graph LR
    A[创建] --> B[验证]
    B --> C[索引]
    C --> D[使用]
    D --> E{评估}
    E -->|需要更新| F[更新]
    E -->|不再有效| G[归档/删除]
    F --> D

关联类型管理

关联类型标准化通过 associations.py 模块实现：

{
  "关系映射": {
    "bug-fix": "fix",
    "technical-solution": "solution",
    "implementation": "implement"
  }
}

资料来源：src/mcp_memory_service/consolidation/associations.py

与向量存储的集成

知识图谱与向量存储紧密集成，形成混合检索系统：

双索引架构

graph TB
    subgraph "输入层"
        A[记忆内容]
    end
    
    subgraph "处理"
        A --> B[生成向量]
        A --> C[提取实体]
        C --> D[识别关系]
    end
    
    subgraph "存储"
        B --> E[(向量索引)]
        D --> F[(图索引)]
    end
    
    subgraph "查询"
        G[语义查询] --> E
        H[关系查询] --> F
    end

协同检索

性能特性

性能指标

扩展性

• 支持 sqlite-vec 作为本地向量存储后端
• 支持 Cloudflare D1 + Vectorize 作为云端后端
• 支持 混合模式 部署

维护工具

可用脚本

维护建议

1. 定期运行推断优化：每月执行一次关联质量检查
2. 监控孤立节点：清理无关联的记忆以保持图质量
3. 验证索引一致性：确保向量索引与图索引同步

最佳实践

记忆组织

1. 使用标准类型：选择预定义的关系类型而非自定义
2. 保持原子性：每条记忆聚焦单一主题，便于关系建立
3. 添加上下文标签：使用标签辅助关系推断

查询优化

1. 指定深度限制：避免过深的图遍历
2. 使用类型过滤：按关系类型筛选以提高性能
3. 缓存常用查询：对于频繁访问的图结构使用缓存

总结

MCP Memory Service 的知识图谱模块通过实体识别、关系推理和图存储的协同工作，为系统提供了强大的语义关联能力。它不仅支持传统的向量相似度检索，还能通过图结构发现更深层次的关联关系，为 AI 助手提供更丰富的上下文理解能力。

通过持续优化的关联推断系统和维护工具，系统能够自动保持图谱的质量和相关性，确保长期使用的有效性。

概述

记忆整合系统（Memory Consolidation System）是 MCP Memory Service 的核心组件之一，负责对存储的语义记忆进行周期性优化、压缩和遗忘处理。该系统通过自动化调度机制，在不影响服务正常运行的情况下，对数据库中的记忆进行智能管理和维护。

记忆整合系统的设计目标包括：

• 记忆压缩：将相似或冗余的记忆内容进行合并，减少存储空间
• 记忆衰减：根据时间因素和访问频率调整记忆的重要性评分
• 选择性遗忘：自动移除不再需要的低价值记忆，保持数据库健康
• 洞察生成：从记忆数据中提取有价值的分析信息
• 集群管理：对记忆进行语义聚类，优化检索效率

资料来源：src/mcp_memory_service/consolidation/consolidator.py:1-50

系统架构

记忆整合系统采用模块化设计，各子模块协同工作完成不同的整合任务。

graph TD
    subgraph 记忆整合系统
        A[触发器/调度器] --> B[整合器]
        B --> C[压缩模块]
        B --> D[衰减模块]
        B --> E[遗忘模块]
        B --> F[健康检查模块]
        B --> G[洞察生成模块]
        B --> H[聚类模块]
    end
    
    I[SQLite数据库] <--> B
    J[MCP服务器] --> A
    K[HTTP API] --> A

核心组件

资料来源：src/mcp_memory_service/consolidation/scheduler.py:1-30

时间视野策略

系统支持三种不同时间粒度的整合策略，适用于不同类型的记忆管理需求。

每种时间视野对应不同的压缩率和遗忘阈值，确保短期记忆保留完整性的同时，长期记忆不会被无限积累。

资料来源：src/mcp_memory_service/consolidation/consolidator.py:50-100

整合执行流程

graph LR
    A[开始整合] --> B{健康检查}
    B -->|通过| C[执行压缩]
    B -->|失败| Z[终止整合]
    C --> D[执行衰减]
    D --> E[执行遗忘]
    E --> F[更新聚类]
    F --> G[生成洞察]
    G --> H[记录统计]
    H --> I[完成整合]

各阶段详细说明

#### 1. 健康检查阶段

在执行任何修改操作前，系统首先进行数据库健康状态检查，包括：

• 数据库连接可用性验证
• 磁盘空间检查（需要至少 2 倍数据库大小的空间）
• 现有任务冲突检测
• 数据库锁状态确认

资料来源：src/mcp_memory_service/consolidation/health.py:1-50

#### 2. 压缩阶段

压缩模块负责识别和合并语义相似的记忆内容：

• 计算记忆间的相似度评分
• 对超过相似度阈值的记忆进行合并
• 保留最早的创建时间戳
• 合并标签集和元数据

资料来源：src/mcp_memory_service/consolidation/compression.py:1-60

#### 3. 衰减阶段

衰减模块根据时间因素调整记忆的重要性评分：

• 基础衰减率按时间视野配置
• 访问频率作为衰减调整因子
• 重要性评分影响后续遗忘决策

# 衰减计算公式示例
衰减因子 = base_decay_rate × (1 - access_frequency_weight)
新评分 = 原始评分 × 衰减因子

资料来源：src/mcp_memory_service/consolidation/decay.py:1-45

#### 4. 遗忘阶段

遗忘模块根据评分阈值决定应删除的记忆：

• 低于遗忘阈值的记忆被标记为待删除
• 保护期内的记忆不会被删除
• 系统记忆和重要标记的记忆受特殊保护

资料来源：src/mcp_memory_service/consolidation/forgetting.py:1-50

#### 5. 聚类更新阶段

聚类模块对现有记忆进行语义分组：

• 基于嵌入向量的相似性计算
• 更新记忆的聚类标签
• 优化向量检索效率

资料来源：src/mcp_memory_service/consolidation/clustering.py:1-40

#### 6. 洞察生成阶段

洞察模块从整合过程中提取分析数据：

• 整合统计（处理记忆数、压缩数、遗忘数）
• 记忆类型分布分析
• 时间趋势报告
• 健康状态摘要

资料来源：src/mcp_memory_service/consolidation/insights.py:1-50

API 接口

系统提供 HTTP API 接口用于触发和管理整合操作。

触发整合

POST /api/consolidate

响应示例：

{
  "status": "completed",
  "time_horizon": "weekly",
  "processed": 2418,
  "compressed": 156,
  "forgotten": 43,
  "duration_seconds": 18.5
}

资料来源：src/mcp_memory_service/server/handlers/consolidation.py:1-80

查询调度器状态

GET /api/consolidate/status

响应示例：

{
  "running": true,
  "next_daily": "2025-01-08T03:00:00Z",
  "next_weekly": "2025-01-12T03:00:00Z",
  "next_monthly": "2025-02-01T03:00:00Z",
  "jobs_executed": 156,
  "jobs_failed": 2
}

资料来源：src/mcp_memory_service/api/operations.py:100-150

Python API

除 HTTP API 外，系统还提供 Python API 供直接调用。

异步接口

from mcp_memory_service.api import consolidate

# 执行周整合
result = await consolidate('weekly')
print(f"压缩: {result.compressed}, 遗忘: {result.forgotten}")

同步接口

from mcp_memory_service.api import consolidate

# 同步调用
result = consolidate('monthly')
print(f"状态: {result.status}")

性能指标：

• 典型执行时长：10-30 秒（取决于记忆数量）
• 线性扩展：约 10ms/记忆
• 后台执行，非阻塞操作

资料来源：src/mcp_memory_service/api/__init__.py:1-60

调度配置

调度器初始化参数

自定义调度

调度器使用 APScheduler 作为底层调度引擎，支持：

• Cron 表达式配置
• 间隔执行模式
• 一次性任务

资料来源：src/mcp_memory_service/consolidation/scheduler.py:60-120

配置示例

基本配置

{
  "consolidation": {
    "enabled": true,
    "time_horizon": "weekly",
    "compression_threshold": 0.85,
    "forgetting_threshold": 0.3,
    "decay_rate": 0.95
  }
}

激进配置（更多遗忘）

{
  "consolidation": {
    "enabled": true,
    "time_horizon": "monthly",
    "compression_threshold": 0.75,
    "forgetting_threshold": 0.5,
    "decay_rate": 0.9
  }
}

保守配置（更多保留）

{
  "consolidation": {
    "enabled": true,
    "time_horizon": "daily",
    "compression_threshold": 0.95,
    "forgetting_threshold": 0.1,
    "decay_rate": 0.99
  }
}

资料来源：docs/guides/memory-consolidation-guide.md:1-80

维护脚本

系统提供命令行维护脚本用于手动执行整合操作。

使用方法

# 预览整合效果（安全，不实际执行）
python scripts/maintenance/consolidate_memories.py --dry-run

# 执行周整合
python scripts/maintenance/consolidate_memories.py

# 执行月整合并指定时间视野
python scripts/maintenance/consolidate_memories.py --time-horizon monthly

安全特性

• 自动备份：执行前自动创建带时间戳的数据库备份
• 干运行模式：--dry-run 模式仅预览不修改
• 事务安全：原子操作，错误时自动回滚
• 并发检测：检测数据库锁防止并发访问冲突
• 磁盘空间检查：验证是否有足够空间进行操作
• 备份验证：操作后验证备份文件完整性

恢复流程

如果整合操作出现问题，可从自动备份恢复：

# 停止服务
systemctl --user stop mcp-memory-http.service

# 断开所有 MCP 客户端连接

# 从备份恢复
cp ~/.local/share/mcp-memory/sqlite_vec.db.backup-TIMESTAMP \
   ~/.local/share/mcp-memory/sqlite_vec.db

# 验证恢复
sqlite3 ~/.local/share/mcp-memory/sqlite_vec.db \
  "SELECT COUNT(*), COUNT(DISTINCT memory_type) FROM memories;"

资料来源：scripts/maintenance/README.md:1-60

最佳实践

执行时机建议

1. 服务空闲时执行：建议在凌晨或低峰时段运行
2. 停止 HTTP 服务：执行前停止 HTTP 服务器避免并发冲突
3. 断开 MCP 客户端：确保没有活跃的 Claude Code 会话
4. 监控磁盘空间：确保有足够的存储空间进行备份和操作

维护周期

监控指标

建议监控以下整合指标：

• processed：处理的记忆总数
• compressed：被压缩的记忆数
• forgotten：被遗忘的记忆数
• duration_seconds：执行耗时
• jobs_failed：失败的任务数

资料来源：src/mcp_memory_service/consolidation/insights.py:50-100

相关模块文档

• 压缩模块详解
• 遗忘算法详解
• 调度器配置
• API 参考

概述

质量评分系统是 MCP Memory Service 的核心组件之一，负责对存储的语义记忆进行多维度质量评估。该系统通过静态评分、机器学习排序和隐式信号分析等多种机制，综合判断记忆内容的价值和质量等级，从而优化搜索结果的相关性排序。

在 Claude Code 的会话管理中，增强的记忆过滤功能会自动移除"implementation..."等通用摘要内容，确保只保留高价值的洞察信息。系统支持多种配置选项，包括详细程度控制和质量评分权重调整。

质量评分系统的主要目标是提高记忆检索的准确性，确保最相关和最有价值的记忆能够优先呈现给用户。系统采用分层评分架构，结合 ONNX 运行时加速和异步处理能力，在保证性能的同时提供精确的质量评估。

系统架构

质量评分系统采用模块化设计，各组件之间通过清晰的接口进行通信。核心架构包含评分引擎、ONNX 排序器、AI 评估器、异步评分器和隐式信号分析器等多个模块。

组件关系图

graph TD
    A[记忆存储] --> B[质量评分系统]
    B --> C[评分引擎 scorer.py]
    B --> D[ONNX 排序器 onnx_ranker.py]
    B --> E[AI 评估器 ai_evaluator.py]
    B --> F[异步评分器 async_scorer.py]
    B --> G[隐式信号 implicit_signals.py]
    C --> H[配置模块 config.py]
    D --> I[ONNX 运行时]
    E --> J[LLM API]
    G --> K[用户行为数据]
    H --> L[评分策略配置]
    F --> M[异步任务队列]
    M --> N[结果缓存]
    N --> O[搜索结果排序]

核心模块说明

评分策略配置

质量评分系统通过 config.py 模块提供灵活的配置选项。配置参数控制评分算法的行为、权重分配和性能调优。

配置参数表

配置示例：

from mcp_memory_service.quality.config import QualityConfig

config = QualityConfig(
    contentQuality=0.35,
    relevanceWeight=0.35,
    recencyWeight=0.15,
    usageWeight=0.15,
    minQualityThreshold=0.6
)

ONNX 加速排序

系统使用 ONNX Runtime 加速机器学习排序模型的推理过程。相比纯 Python 实现，ONNX 排序器能够显著提升批量评分的吞吐量。

ONNX 排序器工作流程

sequenceDiagram
    participant Client as 客户端
    participant Scorer as 评分引擎
    participant ONNX as ONNX排序器
    participant Cache as 结果缓存
    
    Client->>Scorer: 提交评分请求
    Scorer->>ONNX: 请求批量排序
    ONNX->>ONNX: 模型推理
    ONNX-->>Scorer: 排序分数
    Scorer->>Cache: 缓存结果
    Scorer-->>Client: 返回评分结果

ONNX 嵌入模块负责将文本内容转换为高维向量表示，用于后续的语义相似度计算和质量评估。嵌入向量结合了语义信息和上下文关系，为评分引擎提供丰富的特征输入。

异步评分机制

对于批量评分任务，系统采用异步处理架构以避免阻塞主线程。异步评分器支持任务队列管理、并发控制和结果回调。

异步评分特性

异步评分器提供以下核心功能：

1. 任务批量处理：将多个评分请求合并为单一批处理任务，减少模型调用开销
2. 优先级队列：支持按优先级排序的评分任务调度
3. 结果回调：评分完成后自动触发预设的回调函数
4. 错误重试：网络或服务异常时自动重试失败任务

from mcp_memory_service.quality.async_scorer import AsyncScorer

async_scorer = AsyncScorer(max_concurrent=4)

# 提交异步评分任务
task_id = await async_scorer.submit_batch(
    memory_ids=["hash1", "hash2", "hash3"],
    callback=on_score_complete
)

隐式信号分析

隐式信号分析器从用户行为数据中提取质量相关的反馈信号，无需显式评分即可评估记忆的价值。

信号类型表

隐式信号分析器持续监控用户与记忆的交互模式，通过机器学习算法识别高价值内容。系统会根据累积的信号数据动态调整评分模型的参数。

AI 评估器

AI 评估器利用大语言模型的能力对记忆内容进行深度质量分析。该模块能够理解语义上下文，评估内容的完整性、清晰度和实用价值。

评估维度

AI 评估器支持流式输出模式，能够在评估过程中逐步返回中间结果，便于实时显示评估进度。

关联质量提升

质量评分系统与关联记忆机制紧密集成。通过分析记忆之间的语义关联，系统能够识别和提升高价值内容的显示优先级。

关联质量提升特性包括：

• 语义聚类：将相关内容自动分组
• 关联强度评分：计算记忆间的关联紧密度
• 质量传播：高评分记忆的关联项获得适度加分
• 去重推荐：避免重复或高度相似的内容重复出现

该机制确保搜索结果不仅在语义上相关，而且在质量和独特性上也能满足用户需求。系统在处理关联查询时会综合考虑直接匹配度和关联记忆的质量表现。

集成指南

基础集成

在应用中使用质量评分系统：

from mcp_memory_service.quality.scorer import QualityScorer
from mcp_memory_service.quality.config import QualityConfig

# 初始化配置和评分器
config = QualityConfig()
scorer = QualityScorer(config)

# 对单条记忆评分
memory_id = "abc12345"
score = await scorer.score_memory(memory_id)
print(f"记忆质量分数: {score.overall:.2f}")

批量评分集成

from mcp_memory_service.quality.async_scorer import AsyncScorer

async_scorer = AsyncScorer(max_concurrent=10)

# 定义回调函数
def on_complete(task_id, results):
    print(f"任务 {task_id} 完成，共评分 {len(results)} 条记忆")

# 提交批量任务
results = await async_scorer.submit_batch(
    memory_ids=[...],  # 记忆 ID 列表
    callback=on_complete
)

配置示例

详细模式配置

config = QualityConfig(
    contentQuality=0.4,
    relevanceWeight=0.3,
    recencyWeight=0.15,
    usageWeight=0.15,
    minQualityThreshold=0.5,
    enable_ai_evaluator=True,
    enable_implicit_signals=True,
    async_batch_size=50
)

简洁模式配置

config = QualityConfig(
    contentQuality=0.2,
    relevanceWeight=0.5,
    recencyWeight=0.2,
    usageWeight=0.1,
    minQualityThreshold=0.6,
    enable_ai_evaluator=False,
    enable_implicit_signals=True,
    async_batch_size=20
)

性能指标

根据实际部署测试，系统在标准配置下的性能表现如下：

性能数据来源于项目的基准测试套件，实际表现会因硬件配置和数据规模而有所不同。

相关文档

• 记忆质量指南 - 详细的使用指南和最佳实践
• 关联质量提升 - 关联机制的技术说明
• API 参考 - 评分系统的 API 接口文档

MCP 协议概述

Model Context Protocol (MCP) 是一种标准化协议，用于在 AI 助手与外部数据源、工具之间建立通信桥梁。MCP Memory Service 通过该协议暴露记忆管理功能，使 AI 助手能够：

• 持久化存储对话上下文和重要信息
• 基于语义相似性检索记忆
• 通过标签和类型组织记忆
• 实时获取记忆更新事件

资料来源：src/mcp_memory_service/mcp_server.py

架构设计

整体架构图

graph TB
    subgraph "MCP 客户端层"
        Claude[Claude Code]
        OpenCode[OpenCode]
        Custom[自定义 MCP 客户端]
    end
    
    subgraph "MCP Memory Service 核心"
        MCPServer[MCP Server]
        Handlers[Handler 路由层]
        MemoryService[Memory Service]
        EmbeddingEngine[Embedding 引擎]
    end
    
    subgraph "存储层"
        SQLiteVec[(SQLite Vec<br/>向量存储)]
        GraphDB[(图数据库<br/>关系存储)]
    end
    
    subgraph "发现服务"
        MDNS[mDNS Service<br/>服务发现]
    end
    
    Claude --> MCPServer
    OpenCode --> MCPServer
    Custom --> MCPServer
    
    MCPServer --> Handlers
    Handlers --> MemoryService
    MemoryService --> EmbeddingEngine
    MemoryService --> SQLiteVec
    MemoryService --> GraphDB
    MCPServer --> MDNS

核心组件职责

资料来源：src/mcp_memory_service/server/handlers/__init__.py

Handler 路由层设计

路由分发流程

sequenceDiagram
    participant Client as MCP 客户端
    participant Server as MCP Server
    participant Router as Handler Router
    participant Handler as 具体 Handler
    
    Client->>Server: MCP JSON-RPC 请求
    Server->>Router: 解析 method 名称
    Router->>Handler: 路由到对应 Handler
    Handler->>Handler: 执行业务逻辑
    Handler->>Router: 返回处理结果
    Router->>Server: 封装响应
    Server->>Client: 返回 JSON-RPC 响应

Handler 模块结构

# handlers/__init__.py 导出结构
from .memory import MemoryHandler    # 记忆操作处理器
from .utility import UtilityHandler   # 工具类处理器

每个 Handler 负责特定的 MCP 工具调用，遵循统一的接口规范：

资料来源：src/mcp_memory_service/server/handlers/__init__.py

Memory Handler 详解

Memory Handler 是 MCP 协议集成的核心，负责处理所有与记忆相关的操作。

资料来源：src/mcp_memory_service/server/handlers/memory.py

支持的工具调用

请求参数模型

graph LR
    A[store_memory] --> B{content}
    A --> C{tags?}
    A --> D{memory_type?}
    A --> E{metadata?}
    
    F[search_memories] --> G{query}
    F --> H{limit?}
    F --> I{similarity_threshold?}
    F --> J{tags_filter?}

响应格式

{
  "content": [
    {
      "type": "text",
      "text": "Memory content here..."
    }
  ],
  "isError": false
}

错误响应示例：

{
  "content": [
    {
      "type": "text", 
      "text": "Error: Memory not found"
    }
  ],
  "isError": true
}

Utility Handler 详解

Utility Handler 提供系统级的辅助功能接口。

资料来源：src/mcp_memory_service/server/handlers/utility.py

健康检查接口

健康检查响应示例

{
  "status": "healthy",
  "backend": "sqlite_vec",
  "memory_count": 1247,
  "version": "9.3.0",
  "uptime_seconds": 3600
}

服务发现机制

MCP Memory Service 支持通过 mDNS (Multicast DNS) 进行局域网服务自动发现，使客户端能够无需手动配置即可找到服务。

资料来源：src/mcp_memory_service/discovery/mdns_service.py

服务公告流程

graph LR
    A[服务启动] --> B[注册 mDNS]
    B --> C[公告 _mcp-memory._tcp]
    C --> D[客户端发现服务]
    D --> E[获取 host:port]
    E --> F[建立 MCP 连接]

服务配置参数

MCP 工具调用示例

Python SDK 使用方式

from mcp_memory_service.api import search, store, health

# 健康检查（约 5 tokens）
>>> info = health()
>>> print(f"Backend: {info.backend}, Count: {info.count}")
Backend: sqlite_vec, Count: 1247

# 存储记忆（约 15 tokens）
>>> hash = store("New memory content", tags=["note", "important"])
>>> print(f"Stored: {hash}")
Stored: abc12345

# 语义搜索（约 20 tokens）
>>> results = search("architecture decisions", limit=5)
>>> for m in results.memories:
...     print(f"{m.hash}: {m.preview[:50]}...")
abc12345: Implemented OAuth 2.1 authentication for...
def67890: Refactored storage backend to support...

资料来源：src/mcp_memory_service/api/__init__.py

Claude Code 命令行调用

资料来源：claude_commands/README.md

远程 MCP 配置

对于需要远程连接 MCP Memory Service 的场景，需要进行专门的配置。

资料来源：docs/remote-mcp-setup.md

远程配置架构

graph LR
    subgraph "远程服务器"
        Server[MCP Memory Service]
        DB[(SQLite Vec)]
        Server --> DB
    end
    
    subgraph "本地客户端"
        Claude[Claude Code]
        Config[MCP Config]
    end
    
    Config -->|HTTPS + API Key| Server

配置步骤

1. 服务端配置：确保服务监听在可访问的网络接口
2. API Key 设置：配置 MCP_API_KEY 环境变量
3. 客户端配置：在 ~/.claude/settings.json 中添加远程服务器信息

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "url": "https://your-server:8443/mcp"
    }
  }
}

MCP 增强功能

MCP Memory Service 在标准 MCP 协议基础上实现了多项增强功能。

资料来源：docs/guides/mcp-enhancements.md

功能增强列表

响应大小限制配置

# src/mcp_memory_service/server/utils/response_limiter.py
import os

# 默认值：0 = 无限制（向后兼容）
DEFAULT_MAX_CHARS = int(os.environ.get("MCP_MAX_RESPONSE_CHARS", 0))

配置方式：

# 限制单次响应最大 100,000 字符
export MCP_MAX_RESPONSE_CHARS=100000

性能特性

资料来源：src/mcp_memory_service/api/__init__.py

与 Claude Code 的集成

Claude Code 通过 MCP 协议与 Memory Service 深度集成，支持自动化的记忆感知功能。

graph TB
    subgraph "Claude Code 生命周期"
        Start[Session Start]
        Compact[Compacting]
        End[Session End]
    end
    
    Start --> |自动加载| LoadMem[Load Relevant Memories]
    Compact --> |可选注入| InjectMem[Inject Context]
    End --> |自动保存| SaveMem[Save Session Insights]
    
    LoadMem --> MCPServer[MCP Server]
    MCPServer --> MemService[Memory Service]

钩子脚本列表

资料来源：claude-hooks/README.md

错误处理与调试

常见错误码

调试模式启用

# CLI 启用调试
memory server --debug

# Claude Code 调试钩子
claude --debug hooks

总结

MCP Memory Service 通过标准化的 MCP 协议，为 AI 助手提供了强大的语义记忆能力。其核心优势包括：

• 标准化接口：遵循 MCP 协议规范，支持多种 MCP 客户端
• 语义搜索：基于向量嵌入的相似度检索
• 实时事件：通过 SSE 推送实现即时记忆同步
• 自动发现：mDNS 支持简化服务配置
• 高效性能：毫秒级响应速度，低资源占用

通过 MCP 协议集成，MCP Memory Service 能够无缝融入 Claude Code 等 AI 开发工具的工作流，为开发者提供持久化的上下文记忆能力。

概述

MCP Memory Service 通过提供标准化的 API 接口和专门设计的客户端模块，实现与主流 AI 代理框架的无缝集成。这些集成使得代理（Agent）能够利用持久化记忆服务，实现跨会话的上下文感知和长期知识积累。代理框架集成是 MCP Memory Service 的核心能力之一，它将记忆服务从简单的存储层提升为智能代理的外部记忆系统。 资料来源：docs/guides/AGENTS.md

集成架构

整体架构图

graph TB
    subgraph "代理框架层"
        LG[LangGraph]
        CR[CrewAI]
        AG[AutoGen]
        CUSTOM[自定义代理]
    end
    
    subgraph "MCP Memory Service API"
        API[REST API]
        SSE[Server-Sent Events]
        TOOLS[MCP Tools]
    end
    
    subgraph "客户端层"
        CLIENT[Python Client]
        HOOKS[Claude Hooks]
    end
    
    subgraph "存储后端"
        SQLiteVec[(SQLite-Vec)]
        Cloudflare[(Cloudflare D1)]
    end
    
    LG --> CLIENT
    CR --> CLIENT
    AG --> CLIENT
    CUSTOM --> API
    HOOKS --> API
    CLIENT --> API
    API --> SSE
    API --> TOOLS
    API --> SQLiteVec
    API --> Cloudflare

核心组件关系

Python 客户端集成

客户端初始化

MCP Memory Service 提供了专门的 Python 客户端，用于代理框架集成。客户端支持连接配置和认证管理。

from mcp_memory_service.api import search, store, health

# 搜索记忆 (20 tokens)
results = search("architecture decisions", limit=5)
for m in results.memories:
    print(f"{m.hash}: {m.preview[:50]}...")

# 存储记忆 (15 tokens)
hash = store("New memory", tags=["note", "important"])
print(f"Stored: {hash}")

# 健康检查 (5 tokens)
info = health()
print(f"Backend: {info.backend}, Count: {info.count}")

资料来源：src/mcp_memory_service/api/__init__.py

核心操作接口

性能指标

根据基准测试数据，在 10 用户部署场景下的成本和性能表现如下：

• 成本: $0.15/1M tokens，每年约 $16.43
• 首次调用延迟: 约 50ms（包含存储初始化）
• 后续调用延迟: 5-10ms（连接复用）
• 内存开销: <10MB

资料来源：src/mcp_memory_service/api/__init__.py

Claude Hooks 集成

钩子类型概述

Claude Hooks 提供了一种轻量级的代理记忆集成方式，支持会话生命周期的自动记忆管理。

graph LR
    A[会话开始] --> B[Session-Start Hook]
    B --> C[加载相关记忆]
    C --> D[代理执行任务]
    D --> E[会话结束]
    E --> F[Session-End Hook]
    F --> G[存储会话洞察]
    
    H[自动捕获] --> I[Auto-Capture Hook]
    I --> D

会话结束收割机制

session-end-harvest.js 负责在会话结束时自动提取和存储关键信息：

资料来源：claude-hooks/core/session-end-harvest.js

自动捕获钩子

auto-capture-hook.js 提供了实时记忆捕获能力，无需用户显式操作即可记录重要信息：

// 自动捕获配置示例
{
  "captureTriggers": ["#remember", "#important"],
  "excludePatterns": ["password", "api-key"],
  "maxContentLength": 10000
}

资料来源：claude-hooks/core/auto-capture-hook.js

配置选项

资料来源：claude-hooks/README.md

LangGraph 集成

集成方式

MCP Memory Service 可以作为 LangGraph 代理的外部记忆存储，实现状态感知的长期记忆管理。

from langgraph.prebuilt import create_react_agent
from mcp_memory_service.api import search, store

# 创建带记忆的代理
def memory_node(state):
    query = state.get("query", "")
    results = search(query, limit=3)
    return {"memories": results.memories}

agent = create_react_agent(
    model=llm,
    tools=[memory_node],
    state_modifier="你有一个外部记忆系统可以使用。"
)

状态流设计

graph TB
    START[用户输入] --> MEMORY_QUERY[查询记忆]
    MEMORY_QUERY --> MEMORY_RESULTS[返回相关记忆]
    MEMORY_RESULTS --> CONTEXT_BUILD[构建上下文]
    CONTEXT_BUILD --> LLM_REASON[LLM 推理]
    LLM_REASON --> DECISION{需要新记忆?}
    DECISION -->|是| STORE[存储记忆]
    DECISION -->|否| RESPONSE[返回响应]
    STORE --> RESPONSE

资料来源：docs/agents/langgraph.md

CrewAI 集成

代理角色配置

CrewAI 中的代理可以配置使用 MCP Memory Service 作为共享知识库：

from crewai import Agent
from mcp_memory_service.api import search

researcher = Agent(
    role="研究员",
    goal="基于现有知识库进行深入研究",
    backstory="你是一个研究专家，可以访问公司的知识库。",
    tools=[search]
)

记忆感知工作流

资料来源：docs/agents/crewai.md

AutoGen 集成

会话管理器集成

AutoGen 的群组会话管理器可以与 MCP Memory Service 深度集成：

import autogen
from mcp_memory_service.api import store, search

# 创建记忆感知的群组管理员
class MemoryGroupChat(autogen.GroupChat):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.memory_service = True
    
    def select_speaker(self):
        # 基于相关记忆选择下一个发言者
        context = search(self.messages_summary)
        return super().select_speaker()

多代理记忆同步

graph TB
    subgraph "AutoGen 群组"
        AGENT1[代理 A]
        AGENT2[代理 B]
        AGENT3[代理 C]
    end
    
    subgraph "记忆服务"
        MEMSTORE[(记忆存储)]
    end
    
    AGENT1 -->|写入洞察| MEMSTORE
    AGENT2 -->|写入发现| MEMSTORE
    AGENT3 -->|写入结论| MEMSTORE
    AGENT1 -->|读取| MEMSTORE
    AGENT2 -->|读取| MEMSTORE
    AGENT3 -->|读取| MEMSTORE

资料来源：docs/agents/autogen.md

配置管理

环境变量配置

客户端配置示例

from mcp_memory_service.api.client import MemoryServiceClient

client = MemoryServiceClient(
    endpoint="https://your-server:8443",
    api_key="your-api-key",
    timeout=30,
    max_retries=3
)

资料来源：src/mcp_memory_service/api/client.py

错误处理与容错

重试策略

Python 客户端内置自动重试机制：

降级处理

当记忆服务不可用时，代理框架可以配置降级策略：

1. 静默降级: 继续执行任务，记录警告
2. 缓存降级: 使用本地缓存的记忆
3. 失败降级: 返回错误，要求用户干预

资料来源：src/mcp_memory_service/api/operations.py

最佳实践

记忆质量控制

性能优化建议

1. 批量操作: 使用批量 API 减少网络往返
2. 连接复用: 保持长连接以降低延迟
3. 异步处理: 非关键路径使用异步调用
4. 缓存策略: 实现本地缓存减少重复查询

安全注意事项

• API 密钥应存储在环境变量或密钥管理服务中
• 敏感记忆内容应在存储前进行脱敏处理
• 定期轮换 API 访问凭证

版本兼容性

故障排查

常见问题

诊断命令

# 检查服务健康状态
curl http://localhost:8000/api/health

# 检查 SSE 连接统计
curl http://localhost:8000/api/events/stats

# 验证 Python 客户端连接
python -c "from mcp_memory_service.api import health; print(health())"

概述

MCP Memory Service 的插件系统是一个事件驱动的扩展框架，允许开发者通过订阅特定的钩子（Hook）来拦截和响应内存操作的生命周期事件。该系统采用基于 entry_points 的自动发现机制，插件无需修改核心代码即可扩展服务功能。

架构设计

核心组件

插件系统由以下核心组件构成：

事件驱动模型

插件系统基于发布-订阅模式实现，核心服务在特定操作发生时触发相应的事件钩子：

graph TD
    A[核心服务] -->|触发事件| B[事件总线]
    B --> C[插件A - on_store处理器]
    B --> D[插件B - on_store处理器]
    B --> E[插件C - on_retrieve处理器]
    
    C -->|处理| F[执行自定义逻辑]
    D -->|处理| G[记录审计日志]
    E -->|处理| H[缓存管理]

可用钩子

系统提供四个主要的事件钩子，覆盖内存数据的完整生命周期：

开发指南

创建插件

#### 步骤一：创建插件包结构

my-memory-plugin/
├── my_memory_plugin/
│   └── __init__.py
├── pyproject.toml
└── README.md

#### 步骤二：配置 entry_points

在 pyproject.toml 中声明插件入口点：

[project]
name = "my-memory-plugin"
version = "0.1.0"

[project.entry-points."mcp_memory_service.plugins"]
my_plugin = "my_memory_plugin:register"

#### 步骤三：实现插件逻辑

# my_memory_plugin/__init__.py

def register(ctx):
    """
    注册插件处理器
    
    参数:
        ctx: PluginContext 实例，提供事件订阅和系统交互能力
    """
    ctx.on("on_store", handle_store)
    ctx.on("on_delete", handle_delete)
    ctx.on("on_retrieve", handle_retrieve)
    ctx.on("on_consolidate", handle_consolidate)

def handle_store(event):
    """处理记忆存储事件"""
    print(f"新记忆已存储: {event.hash}")
    print(f"类型: {event.memory_type}, 标签: {event.tags}")

def handle_delete(event):
    """处理记忆删除事件"""
    print(f"记忆已删除: {event.hash}")

def handle_retrieve(event):
    """处理记忆检索事件"""
    print(f"查询: {event.query}, 返回结果: {event.count} 条")
    return event  # 返回事件对象，确保后续处理器正常执行

def handle_consolidate(event):
    """处理记忆类型合并事件"""
    print(f"合并操作: {event.old_type} -> {event.new_type}")
    print(f"影响记忆数: {event.affected_count}")

安装和使用

1. 以开发模式安装插件：

cd my-memory-plugin
pip install -e .

1. 重启 MCP Memory Service：

systemctl --user restart mcp-memory-http.service

1. 验证插件加载状态：

curl -k https://localhost:8443/api/health

插件示例：审计日志

examples/plugin-audit-log 提供了一个完整的参考实现：

# 事件处理函数示例

def on_store_handler(event):
    """记录存储操作"""
    log_entry = {
        "action": "store",
        "hash": event.hash,
        "memory_type": event.memory_type,
        "tags": event.tags,
        "content_length": len(event.content)
    }
    audit_logger.info(log_entry)

def on_delete_handler(event):
    """记录删除操作"""
    log_entry = {
        "action": "delete",
        "hash": event.hash
    }
    audit_logger.info(log_entry)

def on_retrieve_handler(event):
    """记录检索操作"""
    log_entry = {
        "action": "retrieve",
        "query": event.query,
        "result_count": len(event.results)
    }
    audit_logger.info(log_entry)
    return event  # 返回事件确保后续处理链不被中断

插件上下文 API

PluginContext 对象提供以下核心能力：

最佳实践

事件处理器返回值

处理检索相关事件时，必须返回原始事件对象以确保事件链正常传递：

def on_retrieve_handler(event):
    # 执行自定义逻辑
    process_results(event.results)
    # 必须返回事件对象
    return event

错误处理

插件应实现健壮的错误处理机制，避免因单点故障影响系统稳定性：

def handle_store(event):
    try:
        # 插件逻辑
        do_something(event)
    except Exception as e:
        logger.error(f"插件处理失败: {e}")
        # 不抛出异常，保持系统正常运行

异步处理

对于耗时操作，建议使用异步机制：

import asyncio

async def handle_store_async(event):
    await long_running_task(event)

def handle_store(event):
    asyncio.create_task(handle_store_async(event))

部署注意事项

Pitfall Log / 踩坑日志

项目：doobidoo/mcp-memory-service

摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps。

1. 安装坑 · 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fdb895dcb5694a15937c208c89c79c98 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.0 | 来源类型 github_release 暴露的待验证使用条件。

3. 安装坑 · 来源证据：v10.51.1 — Milvus consolidation fix

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.1 — Milvus consolidation fix
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c344fbad309a43aa81482c5e4b429a53 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.1 | 来源类型 github_release 暴露的待验证使用条件。

4. 安装坑 · 来源证据：v10.51.3 — Versioned memory update flag + transitive graph inference

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.3 — Versioned memory update flag + transitive graph inference
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e282c4b45ed04c8eb58759d1b32722bc | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：v10.54.0 — AND/OR tag filtering for memory_search

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。

7. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude

8. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | README/documentation is current enough for a first validation pass.

9. 维护坑 · 来源证据：v10.55.1 — Entity Link Storage Fix

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | last_activity_observed missing

11. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium

12. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | No sandbox install has been executed yet; downstream must verify before user use.

13. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium

14. 安全/权限坑 · 来源证据：feat: cascading search fallback when semantic results are sparse

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: cascading search fallback when semantic results are sparse
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_274fcdb5c1ed4290ac86171131d9db90 | https://github.com/doobidoo/mcp-memory-service/issues/873 | 来源类型 github_issue 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：v10.50.0 — Plugin Hook Scaffolding

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.50.0 — Plugin Hook Scaffolding
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_af91db1e780a4ee5b0c16b8ea3238bf2 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.50.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d648b9854ac1432b8a86297ab220ba34 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.2 | 来源类型 github_release 暴露的待验证使用条件。

17. 安全/权限坑 · 来源证据：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_60ded0d65a2c417e9ce3c9ed7501cbad | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0 | 来源类型 github_release 暴露的待验证使用条件。

18. 安全/权限坑 · 来源证据：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_42c0d95dd5b247d79790b6f92024a048 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

19. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | issue_or_pr_quality=unknown

20. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | release_recency=unknown