Mnemosyne 记忆系统

“Native, zero-cloud memory for AI agents. SQLite-backed. Sub-millisecond. Fully private.” 仓库：https://github.com/AxDSan/mnemosyne 文档：https://mnemosyne-website.vercel.app/ PyPI：mnemosyne-memory

Mnemosyne 是 Hermes Agent 的默认记忆系统，提供本地、零依赖、私有持久化记忆。核心架构为 BEAM（Bilevel Episodic-Associative Memory），基于 SQLite 实现三层记忆结构。

架构

BEAM 三层结构

层级	表名	用途	自动注入 Prompt？
Working Memory	`working_memory`	当前会话的热数据，最新上下文	✅ 是
Episodic Memory	`episodic_memory`	长期存储，sleep() 后从 working 压缩而来	❌ 检索时查询
Scratchpad	`scratchpad`	Agent 临时推理工作区	❌

混合检索

召回时使用 四维混合评分：

50% 向量语义相似度（sqlite-vec 余弦距离）
30% FTS5 全文检索（BM25）
20% 重要度（importance 字段）
时间衰减（可选，通过 temporal_weight 控制）

安装与配置

依赖包

包名	用途	安装方式	补丁 ID
`mnemosyne-memory`	Mnemosyne 核心	`uv pip install`	`pip-mnemosyne`
`fastembed`	本地 ONNX 嵌入模型	`uv pip install`	`pip-fastembed`
`sqlite-vec`	SQLite 向量扩展	`uv pip install`	`pip-sqlite-vec`

所有包已注册到 Patch System，容器重建后 patch_system.py replay 自动恢复。

环境变量

变量	值	说明
`MNEMOSYNE_DATA_DIR`	`/opt/data/home/.hermes/mnemosyne/data`	数据库路径（指向持久卷）
`MNEMOSYNE_EMBEDDING_MODEL`	`BAAI/bge-small-zh-v1.5`	嵌入模型（中文优化，512 维）

注册位置：

/opt/data/scripts/bootstrap-hermes.sh（启动脚本）
/opt/data/.env（容器环境）

嵌入模型

当前使用 BAAI/bge-small-zh-v1.5，特点：

中文优化，支持中英混合输入
512 维向量（vs 英文版 384 维）
本地 ONNX 推理，~34MB 模型缓存于 ~/.hermes/cache/fastembed/
首次使用自动下载，后续离线运行

可选替代模型（fastembed 支持）：

jinaai/jina-embeddings-v2-base-zh — 768 维，8192 token 上下文，中英混合优化更强（~256MB）
qdrant/multilingual-e5-large-onnx — 1024 维，多语言~100 种（较大）
BAAI/bge-small-en-v1.5 — 384 维，纯英文（原默认，不适用于中文）

代码补丁：embeddings.py 的 _get_embedding_dim() 已添加 "BAAI/bge-small-zh-v1.5": 512 映射；beam.py 的 EMBEDDING_DIM 已改为从 embeddings 模块动态读取，不再硬编码 384。

向量量化类型

通过 MNEMOSYNE_VEC_TYPE 环境变量控制（默认 int8）：

int8 — 8-bit 量化，平衡精度与存储（默认）
bit — 1-bit 二进制量化，极致压缩
float32 — 全精度，存储较大

存储位置

文件	路径	持久化？
数据库	`/opt/data/home/.hermes/mnemosyne/data/mnemosyne.db`	✅ 是
模型缓存	`/opt/data/home/.hermes/cache/fastembed/`	✅ 是
导出备份	`/opt/data/home/.hermes/mnemosyne/data/mnemosyne_export.json`	✅ 是
工具 CLI	`mnemosyne` 命令（venv 内）	—

⚠️ 关键陷阱：HOME 不一致：Hermes 网关进程 HOME=/root，终端工具 HOME=/opt/data/home，这会导致两个独立的 mnemosyne.db。设置 MNEMOSYNE_DATA_DIR=/opt/data/home/.hermes/mnemosyne/data 避免此坑。

数据库 Schema

核心表

表名	说明
`working_memory`	当前/近期会话工作记忆
`episodic_memory`	长期情景记忆（含 tier 分级：1-3，自动降级）
`memories`	遗留版记忆表（向后兼容）
`memory_embeddings`	遗留版向量存储（JSON 格式）
`facts`	知识图谱事实（subject-predicate-object）
`triples`	三元组
`annotations`	实体/事实标注
`gists`	记忆要点摘要
`graph_edges`	图谱边
`consolidation_log`	压缩日志
`consolidated_facts`	已压缩事实
`conflicts`	冲突记录
`scratchpad`	推理暂存区

向量表（sqlite-vec 虚拟表）

表名	用途
`vec_episodes`	情景记忆向量索引（`int8[512]`）
`vec_facts`	知识图谱事实向量索引（`int8[512]`）

FTS5 全文搜索表

表名	索引内容
`fts_working`	工作记忆全文索引
`fts_episodes`	情景记忆全文索引
`fts_facts`	事实全文索引

记忆生命周期

flowchart LR
    A[用户输入] --> B[mnemosyne_remember]
    B --> C[working_memory]
    C --> D{mnemosyne_sleep<br>consolidation}
    D --> E[episodic_memory<br>压缩摘要]
    D --> F[working_memory<br>标记 consolidated_at]
    E --> G[tier 1<br>全保留]
    G --> H[tier 2<br>30天后 50%权重]
    H --> I[tier 3<br>180天后 25%权重+压缩]

可用工具

工具	用途
`mnemosyne_recall`	混合搜索记忆（vec + FTS + importance + temporal）
`mnemosyne_remember`	存储记忆（支持 `scope=global/session`、importance、entity extraction）
`mnemosyne_stats`	查看记忆系统统计
`mnemosyne_sleep`	执行 consolidation（working → episodic）
`mnemosyne_invalidate`	标记记忆已过期
`mnemosyne_triple_add/query`	知识图谱三元组操作

配置参考

config.yaml 中的 memory 配置：

memory:
  provider: mnemosyne

Mnemosyne 支持的环境变量调优（beam.py 中定义）：

变量	默认值	说明
`MNEMOSYNE_WM_MAX_ITEMS`	10000	工作记忆上限
`MNEMOSYNE_WM_TTL_HOURS`	24	工作记忆 TTL
`MNEMOSYNE_EP_LIMIT`	50000	情景记忆检索上限
`MNEMOSYNE_SLEEP_BATCH`	5000	每次 sleep 处理量
`MNEMOSYNE_RECENCY_HALFLIFE`	168	时效半衰期（小时）
`MNEMOSYNE_TIER2_DAYS`	30	降级到 tier 2 天数
`MNEMOSYNE_TIER3_DAYS`	180	降级到 tier 3 天数
`MNEMOSYNE_VEC_TYPE`	int8	向量量化类型

调试与维护

查看统计

mnemosyne stats

诊断环境

mnemosyne diagnose --fix

备份与恢复

mnemosyne backup
mnemosyne restore <backup.db.gz>
mnemosyne verify [--quick]

导出/导入

mnemosyne export [file.json]
mnemosyne import <file.json>

重建向量索引（更换嵌入模型后）

# 需在 Hermes 进程内使用 _get_connection()
from mnemosyne.core.beam import _get_connection, _vec_insert
from mnemosyne.core import embeddings as e
 
conn = _get_connection()
cur = conn.cursor()
 
# DROP + RECREATE vec 表
cur.execute("DROP TABLE IF EXISTS vec_episodes")
cur.execute("DROP TABLE IF EXISTS vec_facts")
conn.execute(f"CREATE VIRTUAL TABLE vec_episodes USING vec0(embedding int8[{e.EMBEDDING_DIM}])")
conn.execute(f"CREATE VIRTUAL TABLE vec_facts USING vec0(embedding int8[{e.EMBEDDING_DIM}])")
 
# 重新 embedding
cur.execute("SELECT rowid, content FROM episodic_memory")
for r in cur.fetchall():
    vec = e.embed([r["content"]])[0]
    _vec_insert(conn, r["rowid"], vec.tolist())
conn.commit()

⚠️ DROP TABLE 必须通过 agent 的 _get_connection() 执行（即 Hermes 进程内），用外部连接操作 vec0 虚拟表会失败（sqlite-vec v0.1.9 已知限制）。

注意事项

HOME 不一致问题：MNEMOSYNE_DATA_DIR 必须指向持久卷，否则 Hermes 网关进程和终端工具分别使用不同的数据库
向量重建限制：vec0 虚拟表的 DROP TABLE 需通过创建该表的同一连接执行（agent 内 _get_connection()），外部连接操作会报 SQL logic error
FTS 表与 vec 表解耦：即使向量索引不可用，FTS5 全文检索仍然正常工作
所有记忆写入会同步到 memories 遗留表：双写保证向后兼容
Patch System 已注册：pip-mnemosyne、pip-fastembed、pip-sqlite-vec、symlink-mnemosyne-plugin、config-mnemosyne-provider、run-mnemosyne-install 共 6 个补丁，容器重建后自动恢复
Mnemosyne 优先级问题：当 Hermes 的 memory 工具（原生）和 Mnemosyne 同时可用时，Hermes 默认优先使用原生 memory 工具。解决方案：在 soul.md 中写入硬性要求，强制 agent 优先使用 Mnemosyne 的 mnemosyne_remember/mnemosyne_recall 等工具。

好奇心花园🪴

探索

最近的笔记

Mnemosyne 记忆工具安装配置指南

note-template

getMoon.js

Mnemosyne 记忆系统

Mnemosyne 记忆系统

架构

BEAM 三层结构

混合检索

安装与配置

依赖包

环境变量

嵌入模型

向量量化类型

存储位置

数据库 Schema

核心表

向量表（sqlite-vec 虚拟表）

FTS5 全文搜索表

记忆生命周期

可用工具

配置参考

调试与维护

查看统计

诊断环境

备份与恢复

导出/导入

重建向量索引（更换嵌入模型后）

注意事项

关系图谱

目录

反向链接