Mnemosyne 零云AI内存系统部署教程

Mnemosyne 是一个通用型、本地优先的AI记忆层，为任何AI智能体（Agent）提供持久的、SQLite支撑的记忆能力。它遵循“赫尔墨斯优先”（Hermes-first）的设计理念，以一个纯Python依赖和一个SQLite文件为核心，实现了零外部服务依赖的AI记忆。

本教程将指导您在不同场景下部署和使用Mnemosyne。

1. 项目概览与核心优势

Mnemosyne 并非一个独立的应用程序，而是一个记忆后端系统，旨在为各类AI智能体（如Cursor、Claude Code、OpenWebUI等）提供长期记忆能力。

核心特性

  • 本地优先 (Local-First)：数据默认存储在本地SQLite文件中，完全由您掌控，无需云服务。
  • 零依赖 (Zero Deps)：核心安装仅需 pip install mnemosyne-memory，极度轻量。
  • 通用兼容 (Works With Everything)：通过MCP（模型上下文协议）、Python SDK、插件等方式，支持与几乎所有主流AI智能体集成。
  • 先进的记忆架构 (BEAM)：采用“工作记忆 + 情景记忆 + 三元组知识图谱”的三层架构，提供高效的混合搜索（向量+全文+重要性）。
  • 高性能与低存储：通过信息论二值化（MIB）将向量压缩32倍，在10M规模记忆下仍保持毫秒级延迟和MB级存储。
  • 可选安全同步：支持自建同步服务器，并提供端到端加密选项，确保同步过程中数据私密性。

2. 环境准备

2.1 基础要求

  • 操作系统：Windows、macOS 或 Linux。
  • Python 版本：Python 3.10 或更高版本。
  • 包管理工具：pip。

2.2 （可选）准备LLM API密钥

Mnemosyne 核心功能不依赖外部LLM API，但其LLM驱动的“事实提取”（extract=True）和部分高级功能可能需要调用模型。如果计划使用这些功能，请准备以下至少一个API密钥：

  • OpenAI API 密钥 (OPENAI_API_KEY)
  • OpenRouter API 密钥 (OPENROUTER_API_KEY) - 推荐，可接入多种模型

3. 安装与基础部署

根据您的需求和硬件资源，选择不同的安装配置文件（Profile）：

安装配置文件 适用场景 内存占用 关键说明
核心版 (Core) 低资源设备（树莓派、1GB VPS），或使用远程嵌入API ~50 MB 无本地嵌入模型，需配置外部嵌入端点
pip install mnemosyne-memory
嵌入版 [embeddings] 中端系统，需要本地生成向量 ~800 MB 包含 fastembed 库，用于本地向量化
pip install "mnemosyne-memory[embeddings]"
完整版 [all] 功能全开，本地嵌入 + 本地LLM整理（Consolidation） ~1.5 GB 包含 sentence-transformers 和 ctransformers，能力最强
pip install "mnemosyne-memory[all]"
Hermes插件版 专为 Hermes Agent 用户准备 同基础版 提供Hermes插件入口和工具集

推荐：对于初次尝试，如果硬件允许（内存 > 2GB），建议安装[embeddings]版以获得最佳开箱即用体验：

1
pip install "mnemosyne-memory[embeddings]"

验证安装：
安装完成后，在终端运行以下命令，查看帮助信息以确认安装成功：

1
mnemosyne --help

4. 核心部署：集成到您的AI智能体

根据您使用的智能体客户端，选择对应的集成方式：

4.1 方式一：MCP集成（推荐，兼容性最广）

适用于 Cursor、Claude Code、Codex、Windsurf 等支持MCP协议的编辑器或工具。

步骤：

  1. 在您的智能体配置目录下（如 ~/.cursor/、~/.codex/）找到或创建 mcp.json 文件。

  2. 添加以下配置块：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    {
      "mcpServers": {
        "mnemosyne": {
          "command": "mnemosyne",
          "args": ["mcp"],
          "env": {}
        }
      }
    }

  3. 重启智能体客户端，它就能通过MCP协议调用Mnemosyne的记忆功能了。

4.2 方式二：Python SDK集成（最灵活，适合自定义智能体）

在您的Python代码中直接引入Mnemosyne核心API。

示例：创建一个名为 memory_demo.py 的文件：

1
2
3
4
5
6
7
8
9
10
11
12
from mnemosyne import remember, recall

# 存储一条记忆（可指定重要性和作用域）
remember("用户偏好深色界面主题", importance=0.9)
remember("用户邮箱是 user@example.com", scope="global")

# 搜索记忆
results = recall("用户界面偏好")
print("搜索结果:", results)

# 存储并提取实体（需要LLM API）
remember("与Abdias讨论v2版本发布事宜", extract_entities=True)

运行脚本：python memory_demo.py。

4.3 方式三：集成到特定平台

  • OpenWebUI：将项目提供的单文件桥接器（bridge file）放入其 data/tools/ 目录即可。
  • Pi：使用 pi install npm:@mnemosyne-oss/pi-mnemosyne 安装扩展。
  • OpenClaw：在配置中添加 provider: mnemosyne.integrations.openclaw:create_provider。

详细指南：针对每种平台的具体集成步骤，请查阅项目 docs/integrations/ 目录下的完整文档。

5. 高级部署：命令行（CLI）与自托管同步服务

5.1 命令行直接操作

Mnemosyne提供了丰富的CLI命令，适合脚本化管理和调试：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 直接存储和检索
mnemosyne store "重要的会议记录"
mnemosyne recall "会议"

# 查看数据库统计信息
mnemosyne stats

# 导出/导入全部记忆数据
mnemosyne export backup.json
mnemosyne import backup.json

# 运行记忆整理（将工作记忆固化为长期情景记忆）
mnemosyne sleep

5.2 部署自托管同步服务器（Mnemosyne Sync）

此功能允许您在多个设备（如桌面端和VPS）之间安全同步记忆。

在服务器端（如VPS）：

  1. 在服务器上安装Mnemosyne（核心版即可）。

  2. 启动同步服务（监听8765端口，并设置API密钥）：

    1
    mnemosyne sync-serve --port 8765 --api-key "请设置一个强密码"

在客户端（如您的笔记本）：

  1. 执行双向同步：

    1
    mnemosyne sync --remote https://您的服务器IP:8765

  2. （可选）启用端到端加密：

    1
    2
    3
    4
    # 生成一个加密密钥
    export MNEMOSYNE_SYNC_KEY=$(mnemosyne sync-generate-key)
    # 执行加密同步
    mnemosyne sync --remote https://您的服务器IP:8765 --encrypt

    注意：启用加密后，同步服务器只能看到元数据（时间戳、操作类型等），无法读取实际的记忆内容。

6. 配置与调优

通过环境变量可以灵活配置Mnemosyne的行为：

环境变量 默认值 描述
MNEMOSYNE_DATA_DIR ~/.hermes/mnemosyne/data 数据库存储目录
MNEMOSYNE_EMBEDDING_MODEL BAAI/bge-small-en-v1.5 向量嵌入模型。非英语场景可换为 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
MNEMOSYNE_VEC_TYPE int8 向量压缩类型（float32, int8, bit）
MNEMOSYNE_WM_MAX_ITEMS 10000 工作记忆最大条目数

示例：修改数据库路径和嵌入模型

1
2
export MNEMOSYNE_DATA_DIR="/path/to/my/data"
export MNEMOSYNE_EMBEDDING_MODEL="BAAI/bge-small-zh-v1.5" # 使用中文优化模型

7. 针对Hermes Agent的专项部署

如果您是 Hermes Agent 用户，安装和配置稍有不同：

  1. 安装：

    1
    2
    3
    # 确保在Hermes的虚拟环境中
    source ~/.hermes/hermes-agent/venv/bin/activate
    pip install mnemosyne-hermes

  2. 激活插件：

    1
    2
    3
    mkdir -p ~/.hermes/plugins/mnemosyne
    # 创建插件符号链接
    ln -sfn "$(~/.hermes/hermes-agent/venv/bin/python -c 'import pathlib, mnemosyne_hermes; print(pathlib.Path(mnemosyne_hermes.__file__).resolve().parent)')"/* ~/.hermes/plugins/mnemosyne/

  3. 配置Hermes使用Mnemosyne作为记忆提供者：

    1
    2
    hermes config set memory.provider mnemosyne
    hermes memory status  # 验证状态

  4. 重启Hermes网关：hermes gateway restart

8. 常见问题与排查

问题 可能原因与解决方案
安装 [embeddings] 或 [all] 失败 Python版本过低或网络问题。请确保Python >= 3.10，并尝试使用国内PyPI镜像源。
命令行找不到 mnemosyne Python的Scripts目录未加入系统PATH。尝试 python -m mnemosyne.cli 运行。
集成后智能体无法调用记忆 检查MCP配置文件路径和JSON格式是否正确。确认Mnemosyne服务已启动。
非英语搜索效果差 默认嵌入模型针对英文优化。请根据上述“配置与调优”部分，更换为多语言或特定语言嵌入模型。
同步失败或连接拒绝 检查服务器端同步服务是否正常运行（mnemosyne sync-serve），防火墙是否开放了指定端口（默认8765）。

通过以上步骤，您应该已经成功将Mnemosyne部署为您的AI智能体的记忆系统。其本地优先、轻量级和高度可集成的特性，使其成为构建具有长期记忆的AI应用的理想基础组件。如需更深入的配置或开发，请务必查阅项目 docs/ 目录下的官方文档。