代理搜索记忆模型（或机制）MCP
受Anthropic的Agent SDK内存管理方法的启发，我们开发了一个模型上下文协议（MCP）服务器，为AI代理提供持久化内存能力。该服务器使AI应用能够在不同对话和会话中存储、检索和管理上下文信息。
🧠 概述
这个MCP服务器实现了一个基于文件的内存系统，使得AI代理能够：
- 持久化上下文 跨越对话和会议
- 存储结构化信息 在组织化的内存文件中
- 检索历史数据 为了更好地理解上下文
- 高效管理内存 具有可配置的大小限制
该设计理念遵循了Anthropic的Agent SDK模式，即维护持久性内存，这种内存能在上下文窗口重置后仍然保留，从而实现更复杂且具有上下文感知能力的人工智能交互。
✨ 特点/功能
核心内存操作
- 📖 查看浏览内存目录树（全递归，使用1个空格缩进）并读取文件内容（支持分页）
- 📝 创建创建包含自定义内容的新内存文件（大文件时会发出警告，追踪共同访问情况）
- ✏️ 编辑替换现有内存文件中的文本（对大型结果发出警告，追踪共同访问）
- ➕ 插入在特定行位置添加内容（对于大量结果会发出警告，追踪共同访问）
- 🗑️ 删除删除内存文件或目录
- 📁 重命名移动或重命名内存文件和目录
- 🧹 清理（在安全确认后）重置所有内存
联想记忆
- 🧠 共访问追踪基于查看、创建和编辑模式，自动学习哪些文件是相关的
- 🔗 智能推荐在浏览内容时提供相关文件建议
- 📊 基于会话的学习在MCP会话中追踪文件关系（读和写操作）
- 🎯 非侵入式设计仅路径的推荐避免了测量停滞
- 🛡️ 强大的错误处理优雅地处理损坏的共同访问数据
安全与性能
- 🔒 路径遍历保护在内存边界内安全访问文件系统
- 📏 智能尺寸管理高限制（50,000个字符），带有警告和分页指南
- ⚡ 优化响应简洁的工具响应，以高效利用LLM上下文
- 🛡️ 输入验证强大的参数验证和错误处理
- ⚠️ 大文件警告在创建/编辑大文件（>10,000个字符）时主动发出警告
MCP集成
- 🔗 完全符合MCP（微软云平台）标准实现了完整的MCP规范
- 🏷️ 正确的注释全面的工具描述和元数据
- ⚡ 高效工具设计针对代理工作流程进行了优化
🚀 快速入门
安装
- 克隆仓库:
git clone
cd agentic-search-memory-mcp- 创建并激活虚拟环境：
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项：
pip install -r requirements.txt与光标一起使用
- 添加到Cursor的MCP配置中 (
~/.cursor/mcp.json):
{
"mcpServers": {
"agentic-search-memory-mcp": {
"command": "/path/to/your/venv/bin/python",
"args": [
"/path/to/agentic-search-memory-mcp/memory_server.py"
],
"env": {
"MEMORY_DIR": "/path/to/memories"
}
}
}
}- 将路径替换为您的实际路径:
- 更新 command 指向你虚拟环境中的Python可执行文件 - 更新 args[0] 指向你的 memory_server.py 文件 - 更新 MEMORY_DIR 指向您想要的内存目录
- 让代理使用记忆工具 在你的对话中：
- 试试像“记住我的名字是亚当”这样的句子 - 开启一个新话题，问“你还记得我的名字吗？”
- 在你的 AGENTS.md 文件中添加使用内存的说明
- 此项目中的AGENTS.md文件是一个良好的起点 - 根据需要添加更具体的说明
配置
使用环境变量配置内存系统：
# Memory directory location (default: ./memories)
export MEMORY_DIR="/path/to/your/memory/directory"
# Maximum characters to read from files (default: 20000)
export MEMORY_MAX_READ_CHARS=50000
# Maximum response size for tool outputs (default: 50000)
# High limit to prevent agents from losing access to large files
export MEMORY_MAX_RESPONSE_CHARS=50000
# Warning threshold for large files (default: 10000)
# Agents get warnings when creating/editing files above this size
export MEMORY_LARGE_FILE_THRESHOLD=10000
# Maximum number of related files to show (default: 3)
export MEMORY_COVIS_MAX_RECOMMENDATIONS=5🏗️ 建筑
MCP服务器结构
memory_server.py
├── Configuration & Setup
├── Co-visitation Index (Associative Memory)
│ ├── Session tracking
│ └── File relationship learning
├── Security Helpers
│ ├── Path normalization
│ └── Traversal protection
└── Core Tools (7 MCP tools)
├── view() - Read memory content
├── create() - Create memory files
├── str_replace() - Edit memory files
├── insert() - Add content at lines
├── delete() - Remove memory items
├── rename() - Move/rename items
└── clear_all_memory() - Reset memory🔧 开发
项目结构
agentic-search-memory-mcp/
├── memory_server.py # Main MCP server implementation
├── requirements.txt # Python dependencies
├── AGENTS.md # Development guidelines
└── README.md # This file关键依赖项
- FastMCP适用于Python的现代MCP服务器框架
- Pydantic数据验证与设置管理
- Pathlib现代文件系统路径处理
使用MCP Inspector进行测试
使用MCP Inspector来测试和调试服务器：
# Start the MCP Inspector
npx @modelcontextprotocol/inspector
# The inspector will start on http://localhost:6274
# Use the session token to authenticate or set DANGEROUSLY_OMIT_AUTH=true注如果你遇到端口冲突，请终止现有进程：
# Find and kill processes using the ports
lsof -ti:6274 | xargs kill
lsof -ti:6277 | xargs kill🎯 应用场景
AI代理记忆
- 对话历史存储重要对话上下文
- 项目知识维护项目特定信息
- 用户偏好设置记住用户设置和偏好
- 学习数据从互动中积累知识
开发工作流程
- 代码文档存储代码解释和模式
- 调试笔记跟踪问题及解决方案
- 研究日志保存研究结果和参考文献
- 会议纪要存储重要决策和行动项
内容管理
- 知识库构建结构化的信息库
- 参考材料存储频繁访问的信息
- 模板维护可重用的内容模板
- 档案整理历史信息
🔒 安全考虑事项
- 路径遍历防护所有文件操作均限制在内存目录中进行
- 输入验证对所有输入参数进行全面验证
- 错误处理优雅地处理错误，提供信息丰富的消息
- 资源限制可配置的限制可防止资源耗尽
📚 灵感
这个项目受到……的启发 Anthropic的智能体SDK（软件开发工具包） 内存管理方法，其强调：
- 持久上下文超越单次对话的记忆
- 结构化存储有组织、可搜索的信息库
- 模拟智能体被训练使用的工具在智能体中使用的大型语言模型（LLMs）是通过代理编码训练的，使用了诸如查看、创建、字符串替换和插入等工具。配备此mcp服务器的内存包含了智能体所需的工具集使用方法。
🔗 相关项目
- FastMCP - 现代MCP服务器框架
- 模型上下文协议 - 官方MCP规范
- 人类智能体软件开发工具包（Anthropic Agent SDK） - 记忆模式的灵感来源