Memory Server Sigma

MCP内存服务器模板

用于构建和部署基于FastAPI的MCP（模型上下文协议）内存服务器到AWS ECS的生产就绪模板。此模板提供了完整的基础架构代码、CI/CD管道和构建内存管理服务的最佳实践。

此模板提供什么

核心应用程序

• 快速API 支持异步的web框架
• MCP服务器 内存操作的实现
• PostgreSQL 用于持久存储
• Qdrant 语义搜索的矢量数据库
• 蒸馏器 数据库迁移
• 具有JSON输出的自定义日志框架

基础设施

• AWS云形成 ECS部署模板
• 码头工人 多阶段构建的集装箱化
• 应用程序负载平衡器 使用SSL/TLS
• 路线53 DNS管理
• 秘密经理 整合
• 自动扩展ECS服务

CI/CD

• GitHub操作 工作流
• 自动化测试
• Docker镜像构建和向ECR推送
• 自动化堆栈部署到开发/暂存/生产

开发工具

• 使用Docker Compose进行本地开发
• 测试框架（pytest）
• 数据库迁移工具
• 部署脚本

入门指南

先决条件

• Python 3.12+
• Docker和Docker Compose
• AWS CLI已配置
• GitHub帐户（用于CI/CD）

初始设置

1. 克隆或分叉此模板

   git clone 
   cd mcp-memory-server-template

1. 配置AWS帐户

更新 .github/workflows/deploy-service.yaml:

   role-to-assume: arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/cicd-deployer

1. 设置参数文件

复制示例参数文件：

   cp aws/parameters.dev.yaml.example aws/parameters.dev.yaml
   cp aws/parameters.staging.yaml.example aws/parameters.staging.yaml
   cp aws/parameters.production.yaml.example aws/parameters.production.yaml

编辑每个文件并自定义：

- ServiceName：您的服务名称 - MemoryReservation 和 CpuReservation：资源分配

1. 配置环境变量

复制和自定义：

   cp .env.example .env
   cp src/openmemory/.env.example src/openmemory/.env

1. 再进行

   pip install -r src/requirements.txt
   pip install -r test/requirements.txt

地方发展

使用Docker Compose运行：

cd docker
docker compose up

该服务将在 http://localhost:8000

运行测试：

./run_tests.sh

数据库迁移：

cd src/openmemory
alembic upgrade head

部署到AWS

1. 创建ECR存储库

   aws cloudformation create-stack \
     --stack-name your-service-ecr \
     --template-file aws/ecr.yaml \
     --parameters file://aws/parameters.ecr.yaml

1. 部署到开发

推到 dev branch-GitHub操作将自动：

- 构建Docker镜像 - 推到ECR - 部署CloudFormation堆栈 - 更新ECS服务

1. 部署到暂存/生产

具有相应分支或手动触发器的类似过程

项目结构

mcp-memory-server-template/
├── .github/
│   └── workflows/          # CI/CD pipelines
├── aws/
│   ├── template.yaml       # CloudFormation template
│   ├── ecr.yaml           # ECR repository template
│   └── parameters.*.yaml   # Environment configurations
├── docker/
│   ├── Dockerfile         # Production container
│   ├── docker-compose.yaml # Local development
│   └── entrypoint.sh      # Container startup script
├── src/
│   ├── openmemory/        # Main application code
│   │   ├── app/          # FastAPI application
│   │   ├── alembic/      # Database migrations
│   │   └── main.py       # Application entry point
│   └── th_logging/        # Logging framework
├── test/                   # Test suite
├── pyproject.toml         # Python project config
├── .env.example           # Environment variables template
└── README.md              # This file

主要特点

通过MCP进行内存操作

• 添加回忆
• 搜索记忆（语义向量搜索）
• 列出回忆
• 删除记忆
• 访问控制和权限

矢量搜索

• 语义搜索的Qdrant集成
• OpenAI嵌入
• 高效的批量操作
• 从PostgreSQL自动同步

数据库管理

• PostgreSQL用于关系数据
• 用于模式更改的Alembic迁移
• 用户和应用程序管理
• 内存状态跟踪和历史记录

部署功能

• 零停机滚动更新
• 自动健康检查
• 用于故障部署的断路器
• CloudWatch日志记录
• 自动缩放支持

配置

所需AWS资源

• ECS集群
• VPC和子网
• 应用程序负载平衡器
• Route53托管区
• ACM证书
• 秘密管理器秘密

环境变量

看 .env.example 所需的环境变量包括：

• 数据库连接字符串
• API密钥（OpenAI、Anthropic等）
• Qdrant配置
• 日志记录设置

秘密管理

按照以下模式在AWS secrets Manager中存储机密：

${Environment}/${ServiceName}/*

例子：

• dev/my-service/database-url
• dev/my-service/openai-api-key

定制

添加新路线

添加路线 src/openmemory/app/routers/

数据库架构更改

cd src/openmemory
alembic revision --autogenerate -m "description"
alembic upgrade head

添加依赖关系

echo "package-name" >> src/requirements.in
./update_requirements_txt.sh

监控与调试

查看日志

CloudWatch日志会自动配置为7天保留期。

健康检查

• 健康终点： /health
• 负载平衡器执行自动健康检查
• ECS监控容器运行状况

部署状态

监控GitHub Actions的部署进度和状态。

体系结构决策

• EC2上的ECS：在持续工作负载方面比Fargate更具成本效益
• 桥接网络：启用动态端口映射
• 云层形成：无外部依赖的本地AWS IaC
• 滚动更新：零停机部署
• 结构化日志记录：JSON格式，便于解析

安全

• ECS任务的IAM角色
• 存储在AWS Secrets Manager中的秘密
• 通过ALB的HTTPS/TLS
• VPC隔离
• 网络访问控制的安全组

测试

# Run all tests
./run_tests.sh

# Run specific test
pytest test/test_specific.py

# Run with coverage
pytest --cov=src

贡献

自定义此模板时：

1. 使用您的配置更新参数文件
2. 根据需要修改CloudFormation模板
3. 在中自定义应用程序代码 src/openmemory/app/
4. 用您的具体细节更新此README

许可证

\[指定您的许可证\]

支持

\[添加您的支持信息\]