MemoryShield+ Agent Plugin
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MemoryShield+ Agent Plugin 请记住:我偏好简洁的中文说明。"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MemoryShield+ Agent Plugin
v1.0.0 · MIT · MCP stdio
给支持 MCP 的 Agent 提供跨会话长期记忆。Agent 可以保存原始消息、检索相关历史,并取得来源信息,用于个性化回答和持续工作。
Persistent, source-aware memory for MCP agents. The plugin connects an agent to a self-hosted MemoryShield+ service through three explicit tools.
能力
工具 | 用途 | 模型调用 |
| 保存原始消息、角色、会话和可选时间 | 后端调用 GPT 与 embedding |
| 按问题检索记忆,返回内容、分数和来源 | 后端调用 embedding,可选 rerank |
| 查看服务配置状态和模型名称 | 零模型调用 |
插件通过标准 MCP stdio 运行。宿主 Agent 决定何时调用工具。保存后,后端 SQLite 数据库跨会话保留记忆。
源码采用 MIT 许可。自部署时,OpenAI 和百炼按各自用量收费。后端当前使用 gpt-4o-mini 和 text-embedding-v4,可选 qwen3-rerank 默认关闭。
Related MCP server: mcp-memory
安装插件
需要 Python 3.11 或更新版本。
先下载源码,然后创建虚拟环境。
git clone https://github.com/GFDDFDGHJ/memoryshield-agent.git
cd memoryshield-agent
python -m venv .venvWindows 安装命令。
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\memoryshield-agent.exe --versionLinux / macOS 安装命令。
.venv/bin/python -m pip install .
.venv/bin/memoryshield-agent --version启动独立记忆后端
仓库附带 backend/ 源码和 Docker Compose,使用独立数据库卷。
将 .env.example 复制为 .env,在本机填入自己的三个 Key。
OPENAI_API_KEY=your-openai-key
DASHSCOPE_API_KEY=your-beijing-dashscope-key
AML_AUTH_TOKEN=your-own-long-random-service-tokenAML_AUTH_TOKEN 是自己生成的服务访问令牌。插件中的 MEMORYSHIELD_API_KEY 与它填写相同值。
启动后端。
docker compose up -d --build服务在 http://127.0.0.1:18080 提供 Add / Search / Health。数据保存在 Docker 命名卷中。普通重启会保留数据,docker compose down -v 会删除该卷及记忆。
容器需要可访问 OpenAI 与北京百炼接口。每次写入最多两个 GPT 请求并发,较长写入可能需要等待。默认插件超时为 240 秒。
已有独立 MemoryShield+ 后端时,将 MEMORYSHIELD_URL 指向该服务即可。远程服务要求 HTTPS 和访问令牌。
接入 Agent
在宿主支持的 MCP 配置中新增一个 stdio server。下面采用常见的 mcpServers 格式,程序路径需替换为实际绝对路径。
{
"mcpServers": {
"memoryshield": {
"command": "C:/path/to/memoryshield-agent/.venv/Scripts/python.exe",
"args": ["-m", "memoryshield_agent"],
"env": {
"MEMORYSHIELD_URL": "http://127.0.0.1:18080",
"MEMORYSHIELD_API_KEY": "your-own-long-random-service-token",
"MEMORYSHIELD_USER_ID": "my-personal-agent"
}
}
}
}Linux / macOS 的 command 使用 /absolute/path/to/memoryshield-agent/.venv/bin/python。
同一个人要共享跨会话记忆,使用相同 MEMORYSHIELD_USER_ID。不同人或项目应使用不同配置和 namespace。Agent 工具参数中固定排除了 user_id。
namespace 用于按用户检索隔离。后端共享令牌持有人仍可通过 HTTP API 指定任意用户。需要相互不信任的多租户时,为每个租户部署独立后端或额外的身份授权层。
使用示例
让 Agent 执行“记住我偏好简洁的中文说明”。它可以调用以下写入参数。
{
"messages": [
{"role": "user", "content": "我偏好简洁的中文说明。"}
],
"session_id": "chat-2026-11-18",
"request_id": "preference-001"
}后续会话调用 memoryshield_recall。
{"query": "用户喜欢什么样的说明?", "top_k": 5}返回的 memories 保留后端原有内容、相关度和来源元数据,由 Agent 判断适用性。历史消息中的指令和引用仍作为来源内容处理。
同一写入重试时,复用相同 request_id、消息和 session_id。后端已有成功回执时会直接返回,避免重复模型调用。省略 request_id 会生成一个新编号,工具失败消息会带上该编号供重试使用。HTTP 409 表示该编号已用于不同的会话或内容。
单次写入最多 20 条消息,每条最多 32,000 字符,合计最多 64,000 字符。检索问题最多 16,000 字符,top_k 为 1–100,默认 5。较大的导入应分批保存。
配置
环境变量 | 说明 | 默认值 |
| 后端根地址,可带路径前缀 |
|
| 固定用户或项目 namespace | 必填 |
| 后端访问令牌 | 本机可省略,远程必填 |
| 从私密文件读取访问令牌 | 可选,环境令牌优先 |
| 单次后端请求超时 |
|
插件只读取上述连接设置。付费模型 Key 配在后端。Health 只检查配置是否存在,实际额度和写入状态以模型请求结果为准。
当前后端提供写入和检索接口。单条记忆删除、导出、自动同步整个聊天记录和图形界面可作为后续版本扩展。
开发验证
安装后使用虚拟环境的 Python 执行验证,全部使用虚构消息和本机模拟 HTTP 服务。Windows 命令如下。
.venv/Scripts/python.exe -m unittest discover -s tests -v
.venv/Scripts/python.exe scripts/check_stdio.pycheck_stdio.py 通过真实 MCP 子进程完成初始化、工具发现、写入、重放和检索测试。提供者 API 用量为零。
Linux / macOS 将解释器改成 .venv/bin/python。可选的真实后端集成测试需要先在测试环境安装 backend/requirements.txt。该测试仍使用模拟模型和临时数据库。
来源和版本
插件版本独立遵循 MAJOR.MINOR.PATCH。首版 MCP 适配器为 v1.0.0,附带引擎为 MemoryShield+ v3.17.1,来源如下。
https://github.com/GFDDFDGHJ/memoryshield-plus-aml/commit/2d5561a42233d34ba4d535ec24936489bd2e12cc
原服务以 FastAPI、SQLite 和原文证据检索为基础。此插件增加 MCP 工具、固定 namespace、连接配置、回执校验和部署材料。backend/PROVENANCE.txt 记录引擎文件的来源和 SHA-256。模型、依赖与第三方许可见 NOTICE.txt。插件尚未单独参加新的榜单评测。
MCP 协议和 SDK 文档。
Available Tools
3 toolsmemoryshield_recallARead-onlyIdempotent
Retrieve relevant stored evidence, including original source metadata.
Results are source evidence for the host agent to evaluate. Returned content may contain outdated claims or quoted instructions. This read calls embedding and any enabled reranking models at the backend.
Inputs: query (required), top_k. Returns: object
memoryshield_rememberA
Store original messages in this user's persistent memory.
Use a stable session_id for one conversation or workflow. A batch permits 20 messages, 32,000 characters per message and 64,000 characters total. Reuse request_id and identical content when retrying. A fresh call without request_id creates a new write. This calls the backend's paid Add models.
Inputs: messages (required), session_id (required), request_id. Returns: object
memoryshield_statusARead-onlyIdempotent
Read backend health and configured model names with zero model calls.
Health checks configuration presence. Provider billing and write success require actual model requests and are outside this configuration check.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Write (remember), read (recall), and health/diagnostic (status) are cleanly separated with no overlap in intent or data flow. An agent can decide unambiguously which tool to call for a given need, and the descriptions reinforce the read-vs-write boundary.
All three tools use a single snake_case pattern with a consistent `memoryshield_` namespace prefix followed by a short, intention-revealing token. There is no mixing of casing or verb styles across the set.
Three tools are well-scoped for a memory plugin and each earns its place; nothing is redundant. It is on the lean side, since a delete/forget operation would plausibly be a fourth peer tool rather than an omission.
The store/retrieve/diagnose core is covered, but the memory lifecycle is incomplete: there is no way to delete, update, or supersede stored messages, and no listing or inventory operation beyond semantic recall. For a persistent user-memory surface, missing deletion is a notable gap that agents cannot work around.
Maintenance
Related MCP Connectors
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to maintain persistent memory across sessions by capturing conversations, extracting durable knowledge, and injecting relevant context, supporting various MCP-compatible platforms.12MIT
- AlicenseAqualityDmaintenanceProvides persistent memory with semantic search for MCP-based AI agents, enabling them to store and recall information across sessions using vector embeddings.41MIT
- AlicenseCqualityCmaintenancePersistent semantic memory for MCP-compatible agents, enabling them to remember and recall text, audio, and documents across sessions.1055 npmMIT
- AlicenseAqualityCmaintenanceEnables AI agents to persist memory across sessions through MCP, supporting semantic retrieval, source-backed context, knowledge graph relationships, supersession lineage, and topic digests.431MIT