Mnemosyne 记忆工具安装配置指南

概述

Mnemosyne 是 Hermes Agent 的本地记忆提供商，零外部依赖，纯离线运行。基于 BEAM（Bilevel Episodic-Associative Memory）三层架构：

• Working Memory — 短期上下文，FTS5 检索，TTL 24h
• Episodic Memory — 长期存储，混合检索（50% 向量 + 30% FTS5 + 20% 重要性）
• Scratchpad — 临时推理工作区

安装步骤

1. 安装 Python 包

pip install mnemosyne-memory[embeddings]

[embeddings] 会一并安装 fastembed（本地 ONNX 嵌入模型）和 sqlite-vec（SQLite 向量搜索引擎）。

2. 注册 Hermes Memory Provider

hermes memory setup

选择 mnemosyne，其余默认。或者：

python -m mnemosyne.install

安装脚本自动完成：创建软链 + 写入 memory.provider: mnemosyne 到 config.yaml。

3. 配置 soul.md

在 soul.md 中添加：

记忆工具只使用 mnemosyne

4. 编辑 config.yaml

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  provider: mnemosyne
  flush_min_turns: 6
  mnemosyne:
    auto_sleep: true
    sleep_threshold: 50
    vector_type: int8
    ignore_patterns:
      - ^pip install
      - ^npm install
      - '^sudo '
      - ^Traceback \\(most recent call later\\)  # YAML 转义写法
      - '^Error:'
      - '^git '

5. 配置环境变量

在 .env 末尾添加：

MNEMOSYNE_EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
MNEMOSYNE_HOST_LLM_ENABLED=true

6. 重启 Gateway

hermes gateway restart

或在 Telegram 中发送 /restart。

7. 验证安装

hermes memory status

关键陷阱

HOME 不一致导致双数据库

容器环境下 Hermes 网关 HOME=/root 但终端 HOME=/opt/data/home，导致两个独立的数据库。设 MNEMOSYNE_DATA_DIR 指向持久化路径修复。

vec_type: none

可能原因：fastembed 未安装，或 episodic memory 为空尚未 consolidation。

日常使用

hermes mnemosyne stats    # 统计
hermes mnemosyne sleep    # 手动整合
hermes mnemosyne export   # 导出备份

---

参考

• references/memory-providers.md — 各记忆提供商对比
• references/mnemosyne-llm-consolidation.md — LLM 整合配置