Miyamiz39/mihaji-memory

🐾 Mihaji Memory (米哈唧记忆)

基于 ChromaDB 向量 + BM25 关键词双轨混合检索的 Hermes Agent 原生持久化记忆插件
中日英多语言支持 · RRF 融合重排 · A-Res 加权采样 · 上下文自动缝合 · 毫秒级增量缓存 · 零配置开箱即用

🇨🇳 中文说明 ｜ 🇺🇸 English

🧩 两种实现：按你的平台选

本仓库同时维护 mihaji 的两个实现，机制同源、各自独立演进：

| | 🐍 Hermes 版（本页） | ⚡ DSH 版（dsh-mihaji） |
|---|---|---|
| 平台 | Hermes Agent（Python / ChromaDB + BM25） | DeepSeek Harness profile bundle（Node） |
| 代码目录 | mihaji/ | dsh-mihaji/ |
| 存储 | ChromaDB 向量库 | JSON 单文件（memory.json）+ 关键词/向量混合检索 |
| 默认嵌入模型 | fp32 PyTorch（SentenceTransformer） | INT8 q8 ONNX 量化（transformers.js，文件 ~113MB、进程内 ~450MB） |
| 安装 / 文档 | 按本页下方说明 | dsh-mihaji/README.md |

- 用 DSH 的选 dsh-mihaji：默认已用 q8 量化版，内存比 fp32 省一半以上，精度实测与 fp32 一致性 ≥0.992，旧 fp32 向量无需重嵌。
- 用 Hermes 的选本页版本：默认 fp32 多语言模型（PyTorch 栈，不直接复用 ONNX q8；需要低内存可自行走 optimum/onnxruntime 路线）。
- DSH 移植的架构与决策记录见 docs/dsh-port-design.md。

🌟 核心特性

- 🧠 双轨混合检索 (Hybrid Search + RRF)：
结合 ChromaDB 多语言稠密向量（语义联想）与 Jieba BM25 稀疏关键词（精准专有名词匹配），通过 RRF (Reciprocal Rank Fusion) 无监督融合排序，召回质量兼顾语义与精确命中。
- ⚡ 两段式自动注入 (Two-Pass Prefetch & A-Res Sampling)：
每轮对话前，底层自动执行两段式检索：Top-3 精准命中 + Top-2 记忆强度加权采样（A-Res 算法，w² 平方加权），既保证关键事实不遗忘，又避免每轮看到机械重复的上下文。
- 🧵 上下文前后自动缝合 (Context Chunk Stitching)：
多分块长记忆在检索命中时，自动回溯并无缝拼接相邻的 chunk_idx ± 1 片段，杜绝断句断意。
- 🚀 BM25 磁盘缓存与增量更新 (Zero-Lag Indexing)：
分词语料与倒排索引自动持久化为 bm25_cache.json；新记忆存入时仅对新块做增量分词追加，彻底消除每轮对话全量扫描带来的 1~2 秒主线程卡顿。
- 🧹 主动管理与离线睡眠巩固 (CRUD & Maintenance)：
- Agent 交互工具：remember（主动存储）、search（精准查询）、delete（语义/ID遗忘纠错）、count（条目统计）。
- 离线巩固脚本 maintenance.py：超短噪音清洗、跨桶 Jaccard 相似度去重、JSON 全量备份。
- 🛡️ 极简与克制 (Opinionated Zero-Config)：
固化科学的数学级差与最优超参数，开箱即用，无需用户纠结调参。

🏗️ 架构与数据流

flowchart TB
subgraph AgentLoop ["🤖 Hermes Agent 运行循环"]
direction TB
UserMsg["👤 用户消息 (User Message)"]

subgraph Retrieval ["🔍 检索与提示词注入阶段"]
Prefetch["⚡ prefetch(query)"]
Hybrid["🧠 Hybrid Search (Vector + BM25)"]
RRF["⚖️ RRF 融合排序"]
Stitch["🧵 上下文缝合 (chunk ± 1)"]
PromptBlock["📋 自动注入系统提示词 (System Prompt)"]
end

Assistant["✨ LLM 思考与回复"]

subgraph Memorization ["💾 记忆存储阶段"]
SyncTurn["📥 sync_turn() 钩子"]
Chunker["✂️ 300字切块 (50重叠)"]
DB[("🗄️ ChromaDB 向量库")]
BM25Cache["⚡ BM25 增量追加 & 磁盘缓存"]
end

UserMsg -->|"对话开始前"| Prefetch
Prefetch --> Hybrid --> RRF --> Stitch --> PromptBlock
PromptBlock --> Assistant
Assistant -->|"对话结束后"| SyncTurn
SyncTurn --> Chunker --> DB & BM25Cache
end

🛠️ 工具操作指南 (mihaji_memory)

插件会自动为 Hermes Agent 注册 mihaji_memory 工具，LLM 可在需要时主动调用：

| 动作 (Action) | 说明 | 关键参数 | 示例场景 |
|:---|:---|:---|:---|
| search | 混合检索过往记忆 | query, limit (默认5) | "搜一下用户之前提到的芒果糯米饭做法" |
| remember | 主动记录高价值长期记忆 | text, strength (1-100), memory_type, tags | "记住用户换到了上海工作，偏好泰餐" |
| delete | 主动删除错误/过时的记忆 | query, doc_id 或 group_id | "删除关于之前旧地址的记忆" |
| count | 查看当前记忆库总条目数 | 无 | 统计当前记忆容量 |

💡 记忆类型 (memory_type) 支持：preference（偏好）、knowledge（知识）、event（事件）、task（任务）、general（通用）。

📦 安装与快速开始

1. 克隆仓库

git clone https://github.com/Miyamiz39/mihaji-memory.git
cd mihaji-memory

2. 软链接至 Hermes 插件目录

Linux / macOS:
ln -s $(pwd)/mihaji ~/.hermes/plugins/mihaji

Windows (PowerShell 以管理员或开发者模式运行):
New-Item -ItemType SymbolicLink -Path "$env:LOCALAPPDATA\hermes\plugins\mihaji" -Target "$((Get-Location).Path)\mihaji"

3. 安装依赖

建议在 Hermes 的 Python 虚拟环境中安装：

使用 uv (推荐)
uv pip install -r requirements.txt --python ~/.hermes/hermes-agent/venv/bin/python3

或使用 pip (请确保处于 Hermes 的 venv 中)
pip install -r requirements.txt

PyTorch 提示：sentence-transformers 依赖 PyTorch。如仅使用 CPU，可安装轻量 CPU 版：
pip install torch --index-url https://download.pytorch.org/whl/cpu

4. 激活插件

在 ~/.hermes/config.yaml 中配置：

memory:
provider: mihaji

可选配置（留空则自动使用默认值）：
plugins:
mihaji:
db_path: "" # 留空默认使用 profile 下的 mihaji_memory 目录
model_name: "paraphrase-multilingual-MiniLM-L12-v2"

[!NOTE]
关于嵌入模型（Embedding Model）：
本插件为多语言跨会话记忆量身设计，固化选用 paraphrase-multilingual-MiniLM-L12-v2（原生支持中、日、英等 50+ 种语言）。
模型推理直接由应用层托管，纯本地离线运行（首次自动通过高速镜像拉取），并配备后台静默预热机制，开箱即用，无需额外配置。
本版为 fp32 PyTorch 加载；同一模型的 INT8 q8（ONNX）量化默认版见 DSH 实现（dsh-mihaji/），两版产出向量可互认。

重启 Hermes 即可生效：
hermes memory status

🧹 记忆睡眠巩固 (maintenance.py)

项目附带了离线记忆巩固脚本，建议通过 Cron 定期在夜间执行：

预览清理效果 (不修改数据库)
python mihaji/maintenance.py --dry-run

执行实际清理并自动备份
python mihaji/maintenance.py --backup-dir ~/memory-backups --min-length 20 --dedup-threshold 0.95

功能说明：
- 过滤 < 20 字符的无效碎语噪音；
- 基于字符二元 Jaccard 相似度跨桶合并近似重复记忆；
- 导出 JSON 结构化备份文件；
- 触发 BM25 索引自动重平衡。

🗂️ 仓库目录结构

mihaji-memory/
├── README.md               # 中文文档
├── README.en.md            # English Documentation
├── requirements.txt        # 运行时依赖清单
├── LICENSE                 # MIT License
├── AGENTS.md               # 架构 handoff 说明与已知问题排查
└── mihaji/                 # 插件核心代码 (对应 Hermes 插件目录)
├── __init__.py         # MemoryProvider 入口与 Tool Schema
├── store.py            # ChromaDB 存储封装、分块与上下文缝合
├── hybrid_search.py    # BM25 增量索引、RRF 融合与 A-Res 加权采样
├── maintenance.py      # 记忆维护与去重巩固脚本
└── plugin.yaml         # Hermes 插件元数据声明

🐾 致谢与协议
由 Miyamiz39 与 Hina 用 ❤️ 打造（北京，2026）。
本项目遵循 MIT 开源协议。