MCP内存服务-独立的Docker部署

一个完整的、自包含的Docker部署工具，用于运行 doobidoo的MCP内存服务只需一个命令。设计用于与Claude Code轻松集成。

这个工具做什么

此工具提供了一种在Docker中运行MCP内存服务的零配置方式：

自动存储库克隆 -下载最新版本的mcp内存服务
版本跟踪 -生成清单以跟踪您正在运行的版本
可配置存储 -选择SQLite数据库的存储位置
预埋件 -嵌入构建过程中下载的模型（无运行时延迟）
ARM64优化 -为苹果Silicon和ARM64定制编译的sqlite-vec
仅HTTP模式 -基于HTTP的简单REST API和MCP协议
管理脚本 -用于构建、运行和管理服务的易于使用的脚本
Claude代码集成 -使用斜线命令和内存触发挂钩自动设置

快速开始

先决条件

基本设置：

Docker桌面 已安装并正在运行
Git 安装
Internet连接 （用于初始设置）
磁盘空间：~3GB（适用于图像+型号）

对于Claude代码集成（可选）：

Python 3.7+ （适用于挂钩安装人员）
Node.js 14+ （用于钩子执行）
克劳德代码 安装

安装

克隆此存储库:

   git clone https://github.com/AerionDyseti/mcp-memory-docker.git
   cd mcp-memory-docker

构建和配置:

   ./build.sh

脚本将：

- 检查Docker是否正在运行 - 克隆mcp内存服务存储库 - 提示您首选的数据库存储位置 - 构建Docker镜像（约3-5分钟） - 生成版本清单

启动服务:

   ./run.sh start

配置Claude代码 （选择一个）：

选项A：自动（推荐）

   ./install-claude-code.sh

选项B：手动 增添 ~/.claude/settings.json:

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

就是这样！您的内存服务现在正在运行并连接到Claude Code。

Claude代码集成（推荐）

对于Claude Code用户，我们提供了一个自动设置脚本，该脚本：

在Claude Code设置中注册MCP服务器
为内存操作创建7个有用的斜线命令
安装内存触发器挂钩 （核心+自然语言触发器）
支持用户范围和项目本地安装

先决条件

对于包括钩子在内的完全集成：

Python 3.7+ （适用于挂钩安装人员）
Node.js 14+ （用于钩子执行）
克劳德代码 安装

该脚本将检查先决条件，并指导您完成任何缺失的要求。

快速设置

./install-claude-code.sh

脚本将：

检查是否安装了Claude Code
验证内存服务是否正在运行
询问您是要用户范围安装还是项目本地安装
注册MCP服务器配置
为内存操作创建斜线命令
安装具有自然语言检测功能的内存触发器挂钩

创建了Slash命令

安装后，您将在Claude Code中获得以下命令：

命令	描述
`/memory-status`	检查服务状态和统计数据
`/memory-save`	将信息保存到内存中
`/memory-search`	按查询搜索记忆
`/memory-recall`	回忆起某个话题的记忆
`/memory-stats`	显示详细的内存统计信息
`/memory-export`	将记忆导出到文件
`/memory-clear`	清除记忆（带确认）

示例用法

# In Claude Code:
/memory-status
/memory-save Remember that the API key is stored in .env file
/memory-search API key
/memory-recall authentication setup

内存触发器挂钩

安装程序从doobidoo的存储库中设置智能内存感知挂钩：

核心挂钩：

session-start.js -启动Claude Code时自动加载相关项目内存
session-end.js -存储会话见解和决策以供将来参考
memory-retrieval.js -在会话期间启用按需内存访问
topic-change.js -检测上下文转换并加载相关记忆

自然语言触发器（v7.1.3）：

mid-conversation.js -活动对话期间的实时内存注入
自适应模式检测，触发精度超过85%
多层性能（50ms瞬间→ 150ms快→ 500ms密集型）
Git感知上下文集成

它们是如何工作的：

会话开始：根据以下内容自动加载相关内存：

- 项目上下文和git存储库 - 最近的对话历史 - 与当前工作的语义相似性 - 时间衰减和相关性评分

交谈中：智能检测何时注入记忆：

- 主题变化和上下文转换 - 涉及过去工作的问题 - 需要历史背景的决策

会话结束：自动捕获：

- 作出的重要决定 - 新的见解和学习 - 项目状态和背景

性能模式：

配置为 memory-mode-controller.js:

以速度为中心 -延迟最小，仅限基本触发器
平衡的 -性能良好，智能触发（默认）
记忆软件 -最大限度的背景，深入分析

验证：

安装后，测试挂钩：

# Check hook detection
claude --debug hooks

# Run integration tests (if available)
node ~/.claude/hooks/tests/integration-test.js

手动配置

如果您更喜欢手动配置，请将其添加到 ~/.claude/settings.json:

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

对于斜线命令，请在以下位置创建文件 ~/.claude/commands/ （参见 install-claude-code.sh 例如）。

目录结构

构建后，您的目录将如下所示：

memory-docker/
├── mcp-memory-service/      # Auto-cloned repository
├── Dockerfile               # ARM64-optimized image definition
├── docker-compose.yml       # Service orchestration
├── docker-entrypoint.sh     # Container startup script
├── build.sh                 # Build script (with auto-clone)
├── run.sh                   # Management script
├── install-claude-code.sh   # Claude Code integration installer
├── config.sh                # Auto-generated configuration
├── manifest.json            # Version tracking file
├── .gitignore              # Excludes generated files
└── data/                    # Database storage (configurable location)
    ├── sqlite_vec.db        # Vector database
    └── backups/             # Database backups

用法

构建脚本(`build.sh`)

构建Docker镜像并配置服务。

./build.sh                  # Normal build with prompts
./build.sh --no-cache       # Fresh build (ignores Docker cache)
./build.sh --verbose        # Detailed build output
./build.sh --help           # Show all options

它做什么:

检查Docker是否正在运行
克隆/更新mcp内存服务存储库
生成版本清单
数据库存储位置提示
构建Docker镜像
显示构建统计信息和后续步骤

构建时间：3-5分钟（首次构建），~1分钟（后续构建） 图像大小：约1.5-2GB（仅包括PyTorch CPU+嵌入式型号）

管理脚本(`run.sh`)

管理正在运行的服务。

./run.sh start              # Start the service
./run.sh stop               # Stop the service
./run.sh restart            # Restart the service
./run.sh status             # Show detailed status
./run.sh logs               # View logs (follow mode)
./run.sh logs-tail          # View last 100 lines
./run.sh health             # Check health endpoint
./run.sh shell              # Open shell in container
./run.sh ps                 # Show container processes
./run.sh stats              # Show resource usage (live)
./run.sh version            # Show repository version and manifest
./run.sh cleanup            # Remove container and volumes (DELETES DATA!)
./run.sh help               # Show all commands

配置

数据库存储位置

在首次构建时，系统会提示您选择存储SQLite数据库的位置：

Where would you like to store the SQLite database?
This directory will contain:
  - sqlite_vec.db (the vector database)
  - backups/ (database backups)

Default: ./data
Enter path (or press Enter for default):

您可以指定：

相对路径: ./data 或 ../shared-data
绝对路径: /Users/yourname/mcp-data
主目录: ~/Documents/mcp-memory

路径保存在 config.sh 并由构建和运行脚本使用。

存储库更新

当你奔跑时 ./build.sh 在后续版本中：

📂 Source directory exists: ./mcp-memory-service
Update repository to latest version? (y/n)

按 y 从GitHub中提取最新更改
按 n 使用现有版本

版本跟踪

每次构建都会生成一个 manifest.json 文件：

{
  "repository": {
    "url": "https://github.com/doobidoo/mcp-memory-service",
    "commit": "abc123def456...",
    "commit_short": "abc123d",
    "branch": "main",
    "commit_date": "2025-01-19 10:30:00 -0800",
    "commit_message": "Fix memory leak in vector storage"
  },
  "build": {
    "date": "2025-01-19T18:45:23Z",
    "script_version": "1.0"
  }
}

查看清单：

./run.sh version

这有助于您跟踪您正在运行的上游存储库的哪个版本，从而轻松识别破坏性更改。

服务端点

运行后，该服务提供：

Web仪表板: http://localhost:8000/
MCP端点: http://localhost:8000/mcp（适用于克劳德代码）
API 文档: http://localhost:8000/api/docs
健康检查: http://localhost:8000/api/health

建筑细部

仅HTTP模式

该服务仅在HTTP模式下运行，具有：

✅ HTTP上的MCP协议(/mcp 端点）
✅ REST API(/api/* 端点）
✅ Web仪表板(/)
✅ 服务器发送的事件(/api/events)

嵌入模型和缓存

该服务支持多个具有高效缓存的嵌入式后端：

ONNX量化嵌入（默认）:

✅ 轻量级量化ONNX模型（约14MB vs 87MB PyTorch）
✅ 通过ONNX运行时进行PyTorch自由推理
✅ 缓存在主机上 ~/.cache/mcp_memory/
✅ 快速启动，内存占用最小

PyTorch嵌入（替代方案）:

✅ 全精度全MiniLM-L6-v2型号
✅ 缓存在主机上 ~/.cache/huggingface/
✅ 使用以下方式管理模型 huggingface-cli 在主机上
✅ 绑定已挂载，便于更新

缓存管理:

两个缓存都是从主机系统绑定挂载的
在主机上下载模型，立即在容器中可用
在容器重新创建之间保持不变
首次下载后无需网络访问

内容分块:

✅ 长文本（>1000个字符）的自动分块
✅ 1000个字符块，重叠200个字符
✅ 跨块边界保留语义意义
✅ 长表单内容无数据丢失

ARM64优化

Dockerfile包含自定义编译 sqlite-vec 对于ARM64：

在映像构建过程中从源代码构建
针对Apple Silicon和ARM64处理器进行了优化
避免损坏PyPI车轮
与矢量运算完全兼容

SQLite矢量后端

数据存储：

数据库：主机上的持久SQLite文件
默认位置: ~/.config/memory-mcp-server/memory.db
替代：通过配置 docker-compose.yml 卷装载
备份：自动备份到 backups/ 子目录
演出：~5ms读/写操作
WAL模式：提前写入日志以提高并发性

环境变量

该服务是通过中的环境变量配置的 docker-compose.yml:

environment:
  # Storage backend
  - MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
  - MCP_MEMORY_SQLITE_PATH=/app/data/memory.db
  - MCP_MEMORY_BACKUPS_PATH=/app/data/backups

  # HTTP server
  - MCP_HTTP_ENABLED=true
  - MCP_HTTP_PORT=8000
  - MCP_HTTP_HOST=0.0.0.0

  # Embedding model
  - MCP_EMBEDDING_MODEL=all-MiniLM-L6-v2
  - MCP_MEMORY_USE_ONNX=true  # Use quantized ONNX (default: true)

  # Logging
  - LOG_LEVEL=INFO

  # Optional features (disabled for simplicity)
  - MCP_CONSOLIDATION_ENABLED=false
  - MCP_MDNS_ENABLED=false
  - MCP_OAUTH_ENABLED=false

  # SQLite optimizations
  - MCP_MEMORY_SQLITE_PRAGMAS=busy_timeout=15000,journal_mode=WAL

资源限制

默认资源限制（可在中配置 docker-compose.yml):

deploy:
  resources:
    limits:
      cpus: '2.0'          # Max 2 CPU cores
      memory: 2G           # Max 2GB RAM
    reservations:
      cpus: '0.5'          # Reserved 0.5 cores
      memory: 512M         # Reserved 512MB RAM

故障排除

容器无法启动

./run.sh logs               # Check logs for errors
docker ps -a                # Check container status
./build.sh --no-cache       # Rebuild from scratch

健康检查失败

curl http://localhost:8000/api/health    # Test directly
./run.sh status                          # Check detailed status
./run.sh logs                            # View error logs

端口已在使用中

lsof -i :8000              # Find what's using port 8000
# Edit docker-compose.yml to use different port:
# ports: - "8001:8000"

数据库问题

./run.sh shell
# Inside container:
sqlite3 /app/data/sqlite_vec.db "PRAGMA integrity_check;"

重置所有内容

./run.sh cleanup           # Removes container and volumes
rm -rf mcp-memory-service  # Remove cloned repo
rm config.sh manifest.json # Remove configuration
./build.sh                 # Start fresh

更新中

更新到最新存储库版本

./build.sh
# Answer 'y' when prompted to update repository
# Then restart:
./run.sh restart

更新Docker脚本

git pull                   # Pull latest script changes
./build.sh --no-cache      # Rebuild with new Dockerfile
./run.sh restart           # Restart service

高级用法

交换机嵌入后端

该服务支持两个嵌入后端：

ONNX（默认）-建议大多数用户使用:

environment:
  - MCP_MEMORY_USE_ONNX=true

轻量级量化模型（~14MB）
PyTorch自由推理
缓存在 ~/.cache/mcp_memory/

PyTorch-实现最大兼容性:

environment:
  - MCP_MEMORY_USE_ONNX=false

全精度型号（~87MB）
在以下位置使用HuggingFace缓存 ~/.cache/huggingface/
使用以下方式管理模型 huggingface-cli

更改后，重新启动容器：

docker-compose restart

管理主机上的嵌入模型

使用绑定挂载的缓存，您可以直接在主机上管理模型：

# List cached models
ls -lh ~/.cache/huggingface/hub/

# Download a different model (PyTorch mode)
huggingface-cli download sentence-transformers/all-mpnet-base-v2

# Check ONNX cache
ls -lh ~/.cache/mcp_memory/onnx_models/

容器将自动看到新模型，而无需重新构建！

更改端口

编辑 docker-compose.yml:

ports:
  - "3000:8000"  # Use port 3000 on host

自定义数据位置

数据目录在构建过程中设置。要更改它：

rm config.sh               # Remove existing config
./build.sh                 # Re-run build to set new location

查看构建信息

./run.sh version           # Show manifest
cat manifest.json          # View full version details

运行多个实例

# Copy and modify docker-compose.yml
cp docker-compose.yml docker-compose-2.yml

# Edit docker-compose-2.yml:
# - Change container_name to mcp-memory-service-2
# - Change ports to "8001:8000"
# - Change data volume if needed

# Start second instance
docker-compose -f docker-compose-2.yml up -d

性能指标

现代硬件的预期性能：

度量	值
容器启动	2-3秒
内存使用率（空闲）	300-500MB
内存使用率（活动）	500MB-1GB
API响应时间	\<100ms
语义搜索（10个结果）	~50ms
数据库操作	~5ms

生成的文件

该工具会自动生成以下文件：

config.sh -数据库路径配置（gitignored）
manifest.json -版本跟踪（gitignored）
mcp-memory-service/ -克隆存储库（gitignored）
data/ -数据库存储（gitignored）

这些从git中排除，并在每次构建时重新生成。

安全说明

这是一个 开发设置 针对易用性进行了优化：

⚠️ 默认情况下不进行身份验证
⚠️ 仅HTTP（无TLS）
⚠️ 容器以root身份运行
⚠️ 主机上可访问的数据库文件

生产：

启用OAuth： MCP_OAUTH_ENABLED=true
使用带有有效证书的HTTPS
设置API密钥身份验证
以非root用户身份运行容器
使用适当的文件权限

贡献

发现问题或想改进部署脚本？

检查是否存在问题上游版本库
对于Docker/部署问题，请在此存储库中创建一个问题
包括您的清单版本： ./run.sh version

许可证

此部署工具按原样提供。mcp内存服务有自己的许可证（请参阅上游版本库).

支持

构建问题：运行 ./build.sh --verbose 详细输出
运行时问题：检查 ./run.sh logs 用于错误消息
版本检查：使用 ./run.sh version 看看你在跑什么
健康检查：参观http://localhost:8000/api/health
API文件：参观http://localhost:8000/api/docs

致谢

doobidoo/mcp内存服务 -上游存储服务
模型上下文协议 -MCP规范
克劳德代码 -AI编码助手

MCP Memory Docker

快速接入

详细介绍

MCP内存服务-独立的Docker部署

这个工具做什么

快速开始

先决条件

安装

Claude代码集成（推荐）

先决条件

快速设置

创建了Slash命令

示例用法

内存触发器挂钩

手动配置

目录结构

用法

构建脚本(build.sh)

管理脚本(run.sh)

配置

数据库存储位置

存储库更新

版本跟踪

服务端点

建筑细部

仅HTTP模式

嵌入模型和缓存

ARM64优化

SQLite矢量后端

环境变量

资源限制

故障排除

容器无法启动

健康检查失败

端口已在使用中

数据库问题

重置所有内容

更新中

更新到最新存储库版本

更新Docker脚本

高级用法

交换机嵌入后端

管理主机上的嵌入模型

更改端口

自定义数据位置

查看构建信息

运行多个实例

性能指标

生成的文件

安全说明

贡献

许可证

支持

致谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

构建脚本(`build.sh`)

管理脚本(`run.sh`)