mirror of
https://github.com/Youzini-afk/ST-Bionic-Memory-Ecology.git
synced 2026-05-15 22:30:38 +08:00
274 lines
9.4 KiB
Markdown
274 lines
9.4 KiB
Markdown
# 🧠 ST-BME — SillyTavern 图谱记忆插件
|
||
|
||
> **让 AI 真正记住你们的故事。**
|
||
>
|
||
> ST-BME 把对话中散落的角色、事件、地点、关系自动提取为记忆图谱，在下一轮生成前精准召回，让长期 RP 的角色不再"失忆"。
|
||
|
||
---
|
||
|
||
## ✨ 它能做什么
|
||
|
||
- 🧩 **自动提取** — 每次 AI 回复后，从上下文中抽取角色状态、事件、地点、规则、主线等结构化记忆
|
||
- 🔍 **智能召回** — 生成前根据当前对话自动检索最相关的记忆，注入 prompt
|
||
- 🌐 **图谱可视化** — 内置力导向图谱面板，直观查看记忆节点之间的关系
|
||
- 🎨 **4 套配色主题** — Crimson Synth / Neon Cyan / Amber Console / Violet Haze
|
||
- 📱 **手机端适配** — 底部 Tab Bar + 精简布局，手机也能用
|
||
- 🔄 **历史安全** — 删楼、编辑、切 swipe 时自动回滚恢复，不留脏记忆
|
||
- 📦 **不改酒馆本体** — 纯第三方扩展，即装即用
|
||
|
||
---
|
||
|
||
## 🚀 安装
|
||
|
||
### 方法一：通过 SillyTavern 扩展安装
|
||
|
||
1. 打开 SillyTavern → 扩展 → 安装扩展
|
||
2. 输入仓库地址：
|
||
```
|
||
https://github.com/pjm0616/ST-Bionic-Memory-Ecology
|
||
```
|
||
3. 刷新页面
|
||
|
||
### 方法二：手动安装
|
||
|
||
```bash
|
||
cd SillyTavern/data/default-user/extensions/third-party
|
||
git clone https://github.com/pjm0616/ST-Bionic-Memory-Ecology.git st-bme
|
||
```
|
||
|
||
重启 SillyTavern 即可。
|
||
|
||
---
|
||
|
||
## ⚡ 快速上手
|
||
|
||
1. **启用插件** — 右侧面板找到 "ST-BME 图谱记忆" 区块，勾选 "启用记忆图谱"
|
||
2. **配置 Embedding** — 选择向量模式（下面会说），有了向量搜索召回效果才好
|
||
3. **开始聊天** — 正常跟角色对话，插件会自动在后台提取和召回
|
||
4. **打开面板** — 左上角 ≡ 菜单 →「🧠 记忆图谱」查看图谱
|
||
|
||
> **最少配置：** 只勾选"启用"就能跑起来。默认会复用你当前的聊天模型做提取。
|
||
|
||
---
|
||
|
||
## 📝 记忆类型
|
||
|
||
插件会把对话拆解成以下几种记忆节点：
|
||
|
||
| 类型 | 说明 | 举例 |
|
||
|------|------|------|
|
||
| 🧑 角色 | 角色的当前状态、性格、外貌变化 | "小明因为淋雨感冒了" |
|
||
| ⚡ 事件 | 发生过的事 | "河边的告白" |
|
||
| 📍 地点 | 地点状态 | "废弃实验室，门被锁上了" |
|
||
| 📌 规则 | 世界观设定、约束 | "魔法会消耗生命力" |
|
||
| 🧵 主线 | 任务线/剧情线 | "寻找失踪的项链" |
|
||
| 📜 概要 | 自动生成的前情提要 | — |
|
||
| 💭 反思 | 长期规律总结 | "他们经常在夕阳下聊天" |
|
||
|
||
这些节点之间还会建立关系（参与、发生在、推动、矛盾、更新等），形成一张完整的记忆网络。
|
||
|
||
---
|
||
|
||
## 🔧 设置说明
|
||
|
||
### 记忆 LLM
|
||
|
||
用来做提取、压缩、进化、概要等任务的模型。
|
||
|
||
- **留空** → 复用当前 SillyTavern 的聊天模型（最简配置）
|
||
- **填写** → 你可以指定一个独立的 OpenAI-compatible 模型专门处理记忆
|
||
|
||
### Embedding（向量搜索）
|
||
|
||
向量搜索是"智能召回"的关键。支持两种模式：
|
||
|
||
#### 后端模式（推荐）
|
||
|
||
走 SillyTavern 后端的向量 API，最稳定：
|
||
|
||
- 支持 OpenAI / Cohere / Mistral / Ollama / LlamaCpp / vLLM 等
|
||
- 在设置面板选择「后端向量源」，填好模型名即可
|
||
- 不需要单独填 API Key，复用酒馆已有的
|
||
|
||
#### 直连模式
|
||
|
||
如果你需要完全独立的 Embedding 服务（比如酒馆后端不支持的源）：
|
||
|
||
- 填入 Embedding API 地址、Key、Model
|
||
- 插件直接请求你的 Embedding 服务
|
||
- 注意浏览器跨域问题（CORS）
|
||
|
||
> **切换向量模式/模型后，建议点一次"重建向量"。**
|
||
|
||
### 提取设置
|
||
|
||
| 设置 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| 每 N 条回复提取 | 1 | 每几条 AI 回复做一次提取 |
|
||
| 提取上下文轮数 | 2 | 提取时向前看几轮对话 |
|
||
| 启用近邻对照 | 开 | 写入前对比现有记忆，避免重复 |
|
||
| 启用记忆进化 | 开 | 新记忆会影响旧记忆理解 |
|
||
| 启用自动概要 | 开 | 定期生成前情提要 |
|
||
| 启用反思 | 关 | 让 AI 总结长期模式 |
|
||
| 启用主动遗忘 | 开 | 太久没用的记忆降低优先级 |
|
||
|
||
### 召回设置
|
||
|
||
| 设置 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| 召回上下文轮数 | 3 | 让 AI 根据最近几轮来召回 |
|
||
| 向量候选数 | 15 | 向量搜索返回多少候选 |
|
||
| 扩散深度 | 2 | 在图上沿关系扩散几层 |
|
||
| 最终注入数 | 12 | 最终注入多少条记忆 |
|
||
| Token 预算 | 1500 | 注入的最大 token 估算 |
|
||
|
||
---
|
||
|
||
## 🖥️ 操控面板
|
||
|
||
从左上角 ≡ 菜单点「🧠 记忆图谱」打开面板，或在右侧设置里点「打开操控面板」。
|
||
|
||
### 总览 Tab
|
||
- 统计数据（活跃节点、边、归档数、碎片率）
|
||
- 运行状态（聊天 ID、向量状态、历史状态）
|
||
- 最近提取 / 召回的记忆
|
||
|
||
### 记忆 Tab
|
||
- 搜索和筛选记忆节点
|
||
- 点击节点查看详情
|
||
- 支持按类型过滤
|
||
|
||
### 注入 Tab
|
||
- 预览当前注入内容
|
||
- 查看 token 消耗
|
||
|
||
### 操作 Tab
|
||
- 手动提取 — 立即从当前对话提取
|
||
- 手动压缩 — 合并重复/过时记忆
|
||
- 执行遗忘 — 主动降级低价值记忆
|
||
- 更新概要 — 重新生成前情提要
|
||
- 导出 / 导入图谱
|
||
- 重建图谱 — 从当前聊天重新提取全部记忆
|
||
- 重建向量 — 重建全部向量索引
|
||
- 强制进化 — 让新记忆影响旧记忆
|
||
|
||
### 配置 Tab
|
||
在面板内可以直接修改记忆 LLM 和 Embedding 配置，无需退出面板。
|
||
|
||
### 图谱可视化
|
||
桌面端右侧大区域显示力导向图谱，节点可拖拽、缩放、点击查看详情。支持 4 套配色主题切换。
|
||
|
||
---
|
||
|
||
## 🔄 历史安全
|
||
|
||
这是最重要的功能之一。
|
||
|
||
当你在 SillyTavern 里做以下操作时：
|
||
- 删除某条消息
|
||
- 编辑某条消息
|
||
- 切换 swipe
|
||
|
||
插件会自动检测到历史发生了变化，然后：
|
||
|
||
1. **止损** — 停止当前推进，清空可能失效的注入
|
||
2. **回滚** — 找到受影响的批次，删除相关记忆和向量
|
||
3. **恢复** — 从变动点重新提取
|
||
|
||
这样你就不用担心"改了历史但记忆还留着错的内容"的问题。
|
||
|
||
---
|
||
|
||
## 📋 手动操作速查
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| 手动提取 | 不等自动触发，立刻提取当前对话 |
|
||
| 手动压缩 | 把重复/冗余的事件合并 |
|
||
| 执行遗忘 | 降低长期未使用记忆的优先级 |
|
||
| 更新概要 | 重新生成全局前情提要 |
|
||
| 导出图谱 | 下载当前图谱 JSON（不含向量） |
|
||
| 导入图谱 | 导入图谱文件（导入后需重建向量） |
|
||
| 重建图谱 | ⚠️ 清空现有图谱，从聊天记录重新提取 |
|
||
| 重建向量 | 重建全部节点的向量索引 |
|
||
| 范围重建向量 | 只重建指定楼层范围内的向量 |
|
||
| 强制进化 | 让新记忆深度影响旧记忆认知 |
|
||
|
||
---
|
||
|
||
## 🏗️ 开发者参考
|
||
|
||
### 文件结构
|
||
|
||
```
|
||
ST-BME/
|
||
├── index.js # 主入口：事件绑定、流程调度、历史恢复
|
||
├── graph.js # 图数据模型、序列化、版本迁移
|
||
├── extractor.js # 记忆提取、概要、反思
|
||
├── retriever.js # 向量候选、图扩散、混合评分、召回
|
||
├── injector.js # 召回结果格式化注入
|
||
├── runtime-state.js # 运行时状态：楼层 hash、dirty 标记、恢复日志
|
||
├── vector-index.js # 向量索引管理（backend / direct 双模式）
|
||
├── embedding.js # 直连 Embedding API 封装
|
||
├── llm.js # 记忆 LLM 请求封装
|
||
├── compressor.js # 层级压缩与遗忘
|
||
├── evolution.js # 记忆进化（A-MEM 风格）
|
||
├── diffusion.js # 图扩散算法
|
||
├── dynamics.js # 动态调节（重要度衰减等）
|
||
├── schema.js # 节点类型定义
|
||
├── themes.js # 4 套主题配色
|
||
├── graph-renderer.js # Canvas 力导向图谱渲染器
|
||
├── panel.js # 操控面板交互逻辑
|
||
├── panel.html # 面板 HTML 模板
|
||
├── settings.html # 右侧设置面板
|
||
├── style.css # 全部样式
|
||
├── manifest.json # SillyTavern 扩展清单
|
||
└── tests/ # 测试脚本
|
||
```
|
||
|
||
### 数据存储
|
||
|
||
- **图谱数据** → `chat_metadata.st_bme_graph`（跟随聊天保存）
|
||
- **插件设置** → SillyTavern 的 `extension_settings.st_bme`
|
||
- **向量索引** → 后端模式走酒馆 API；直连模式存在节点内
|
||
|
||
### 事件挂载
|
||
|
||
| SillyTavern 事件 | 做什么 |
|
||
|---|---|
|
||
| `CHAT_CHANGED` | 加载对应聊天的图谱 |
|
||
| `GENERATION_AFTER_COMMANDS` | AI 回复后提取记忆 |
|
||
| `GENERATE_BEFORE_COMBINE_PROMPTS` | 生成前召回并注入 |
|
||
| `MESSAGE_RECEIVED` | 保存图谱状态 |
|
||
| 删除 / 编辑 / Swipe | 触发历史变动检测与恢复 |
|
||
|
||
### 召回流水线
|
||
|
||
```
|
||
用户输入 → 向量预筛 → 图扩散 → 混合评分 → [可选 LLM 精排] → 场景重构 → 分桶注入
|
||
```
|
||
|
||
### 注入格式
|
||
|
||
召回结果分成两层注入：
|
||
|
||
- **Core**（常驻）：规则、概要、主线
|
||
- **Recalled**（动态）：根据当前对话召回
|
||
|
||
每层内进一步按用途分桶：当前状态 / 情景事件 / 反思锚点 / 规则约束。
|
||
|
||
---
|
||
|
||
## ⚠️ 已知限制
|
||
|
||
1. **记忆质量取决于 LLM** — 模型提取不准，记忆也会不准
|
||
2. **直连模式有跨域风险** — 浏览器的 CORS 限制可能导致请求失败
|
||
3. **后端向量仅支持酒馆已有 provider** — 不在列表里的需要用直连
|
||
4. **恢复优先正确性** — 批次日志缺失时会退化为全量重建，可能较慢
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
AGPLv3 — 详见 [LICENSE](./LICENSE)
|