taozuqin/ST-Bionic-Memory-Ecology
1
0
Fork 0
mirror of https://github.com/Youzini-afk/ST-Bionic-Memory-Ecology.git synced 2026-05-15 22:30:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 重写 README，面向用户和开发者

Browse Source
This commit is contained in:
Youzini-afk
2026-03-24 16:47:06 +08:00
parent 50ee8cc8ed
commit 95cde04e64
1 changed files with 187 additions and 610 deletions
Download Patch File Download Diff File Expand all files Collapse all files

797
README.md
View File

@@ -1,696 +1,273 @@
# ST-BME Memory Graph # 🧠 ST-BME — SillyTavern 图谱记忆插件
> 面向 SillyTavern 第三方扩展体系的图谱记忆插件。 > **让 AI 真正记住你们的故事。**
> 它把聊天历史转换成结构化记忆图，在生成前按场景召回并注入，服务于长期 RP、持续剧情、角色状态维护和多轮世界观演化。 >
> ST-BME 把对话中散落的角色、事件、地点、关系自动提取为记忆图谱，在下一轮生成前精准召回，让长期 RP 的角色不再"失忆"。
## 1. 项目定位
ST-BME 的核心目标不是“把所有聊天全文塞回上下文”，而是把对话中的长期信息拆成可维护、可更新、可压缩、可检索的记忆图。
当前版本坚持 3 个原则：
1. **不改酒馆本体**
- 作为可发布的第三方扩展运行。
- 不要求用户给 SillyTavern 打补丁。
2. **图谱真相源留在聊天元数据**
- 图谱主体继续跟随当前聊天保存在 `chat_metadata.st_bme_graph`。
- 不把图谱主数据迁移到独立数据库或服务器文件。
3. **向量与图谱解耦**
- 图谱负责结构、时序、压缩、召回分层。
- 向量只负责语义候选预筛，可以走后端索引，也可以走独立直连兜底。
--- ---
## 2. 当前能力概览 ## ✨ 它能做什么
### 2.1 写入能力 - 🧩 **自动提取** — 每次 AI 回复后，从上下文中抽取角色状态、事件、地点、规则、主线等结构化记忆
- 🔍 **智能召回** — 生成前根据当前对话自动检索最相关的记忆，注入 prompt
- assistant 回复后自动提取未处理楼层 - 🌐 **图谱可视化** — 内置力导向图谱面板，直观查看记忆节点之间的关系
- LLM 结构化输出 `create / update / delete` - 🎨 **4 套配色主题** — Crimson Synth / Neon Cyan / Amber Console / Violet Haze
- 支持事件、角色、地点、规则、主线、概要、反思节点 - 📱 **手机端适配** — 底部 Tab Bar + 精简布局，手机也能用
- 支持时序边、更新边、矛盾边 - 🔄 **历史安全** — 删楼、编辑、切 swipe 时自动回滚恢复，不留脏记忆
- 支持 Mem0 风格近邻对照，减少重复写入 - 📦 **不改酒馆本体** — 纯第三方扩展，即装即用
- 支持 A-MEM 风格记忆进化
- 支持全局概要生成
- 支持反思条目生成
- 支持主动遗忘
- 支持层级压缩
### 2.2 读取能力
- 生成前自动召回记忆
- 向量预筛
- 图扩散
- 混合评分
- 可选 LLM 精确召回
- 场景重构
- 分桶注入：状态记忆 / 情景事件 / 反思锚点 / 规则约束
### 2.3 运维与安全能力
- 新聊天、分支聊天、切换聊天自动隔离
- 支持图谱导入导出
- 支持图谱全量重建
- 支持向量全量重建
- 支持向量范围重建
- 支持直连模式全量重嵌
- 支持历史回退检测与自动恢复
--- ---
## 3. 系统架构 ## 🚀 安装
### 3.1 三层结构 ### 方法一：通过 SillyTavern 扩展安装
ST-BME 当前可以理解成三层： 1. 打开 SillyTavern → 扩展 → 安装扩展
2. 输入仓库地址：
```
https://github.com/pjm0616/ST-Bionic-Memory-Ecology
```
3. 刷新页面
1. **图谱真相层** ### 方法二：手动安装
- 存储在当前聊天 `chat_metadata.st_bme_graph`
- 保存节点、边、层级压缩关系、上次召回结果等
2. **运行时状态层** ```bash
- 仍然跟随图谱一起保存在 `chat_metadata` cd SillyTavern/data/default-user/extensions/third-party
- 保存历史处理指针、楼层 hash、脏区、向量索引映射、batch journal git clone https://github.com/pjm0616/ST-Bionic-Memory-Ecology.git st-bme
3. **向量候选层**
- `backend` 模式：使用酒馆现成 `/api/vector/*`
- `direct` 模式：使用插件自己的 OpenAI-compatible Embedding 直连
### 3.2 为什么不把图谱挪到服务器
因为插件发布要求不能改 SillyTavern 本体，而当前插件最重要的“聊天作用域绑定、聊天分支隔离、导入导出图谱、随着聊天一起迁移”这几件事，天然都和 `chat_metadata` 更契合。
所以当前设计是：
- **图谱本体**：继续在 `chat_metadata`
- **插件设置**：保存到服务器文件 `st-bme-settings.json`
- **向量索引**：按模式选择后端索引或前端直连
---
## 4. 与 SillyTavern 的集成方式
主入口在 [index.js](./index.js)。
插件不是轮询式运行，而是挂在 SillyTavern 的事件周期上：
| ST 事件 | 插件逻辑 | 作用 |
| --- | --- | --- |
| `CHAT_CHANGED` | `onChatChanged()` | 切换聊天时重新加载该聊天图谱与运行时状态 |
| `GENERATION_AFTER_COMMANDS` | `runExtraction()` | assistant 回复后提取新记忆 |
| `GENERATE_BEFORE_COMBINE_PROMPTS` | `runRecall()` | 生成前召回并注入 |
| `MESSAGE_RECEIVED` | `onMessageReceived()` | 新消息到达时保存图状态 |
| `MESSAGE_DELETED` / `MESSAGE_EDITED` / `MESSAGE_SWIPED` / `MESSAGE_UPDATED` | 历史变动检测 | 触发“先止损，再恢复” |
这意味着：
- **写入发生在回复之后**
- **读取发生在下一轮生成之前**
- **删楼层、编辑、切 swipe** 会被当作历史变动，而不是简单忽略
---
## 5. 数据结构
### 5.1 图谱主键
图谱键名固定为：
```text
chat_metadata.st_bme_graph
``` ```
### 5.2 图状态核心字段 重启 SillyTavern 即可。
| 字段 | 含义 |
| --- | --- |
| `version` | 图数据版本，当前为 v4 |
| `lastProcessedSeq` | 兼容字段，表示已处理到的 assistant 楼层 |
| `nodes` | 全部节点 |
| `edges` | 全部关系边 |
| `lastRecallResult` | 最近一次召回节点 ID |
| `historyState` | 历史处理与恢复状态 |
| `vectorIndexState` | 向量索引状态 |
| `batchJournal` | 批次恢复日志 |
### 5.3 historyState
| 字段 | 含义 |
| --- | --- |
| `chatId` | 当前聊天标识 |
| `lastProcessedAssistantFloor` | 已处理到的 assistant 楼层 |
| `processedMessageHashes` | 已处理区间的楼层 hash 快照 |
| `historyDirtyFrom` | 检测到历史变动后的最早脏楼层 |
| `lastMutationReason` | 最近一次脏化原因 |
| `lastRecoveryResult` | 最近一次恢复结果 |
### 5.4 vectorIndexState
| 字段 | 含义 |
| --- | --- |
| `mode` | `backend` 或 `direct` |
| `collectionId` | 当前聊天的向量集合 ID，固定为 `st-bme::<chatId>` |
| `source` | 当前向量源 |
| `modelScope` | 当前向量模型作用域签名 |
| `hashToNodeId` | 向量 hash -> 节点 ID 映射 |
| `nodeToHash` | 节点 ID -> 向量 hash 映射 |
| `dirty` | 当前向量索引是否待重建 |
| `lastSyncAt` | 上次同步时间 |
| `lastStats` | 向量状态统计 |
| `lastWarning` | 最近一次向量告警 |
### 5.5 batchJournal
每次写入批次都会记录恢复信息。它不是审计日志，而是为了在历史回退时执行“受影响后缀回滚 + 重放”。
当前 journal 包含：
- `processedRange`
- `createdNodeIds`
- `createdEdgeIds`
- `updatedNodeSnapshots`
- `archivedNodeSnapshots`
- `invalidatedEdgeSnapshots`
- `vectorHashesInserted`
- `postProcessArtifacts`
- `snapshotBefore`
其中 `postProcessArtifacts` 用于标记该批次是否额外触发了：
- `evolution`
- `synopsis`
- `reflection`
- `sleep`
- `compression`
--- ---
## 6. 节点与关系 ## ⚡ 快速上手
默认 Schema 定义在 [schema.js](./schema.js)。 1. **启用插件** — 右侧面板找到 "ST-BME 图谱记忆" 区块，勾选 "启用记忆图谱"
2. **配置 Embedding** — 选择向量模式（下面会说），有了向量搜索召回效果才好
3. **开始聊天** — 正常跟角色对话，插件会自动在后台提取和召回
4. **打开面板** — 左上角 ≡ 菜单 →「🧠 记忆图谱」查看图谱
### 6.1 节点类型 > **最少配置：** 只勾选"启用"就能跑起来。默认会复用你当前的聊天模型做提取。
| 类型 | 用途 | 常驻注入 | 备注 |
| --- | --- | --- | --- |
| `event` | 事件、动作、剧情推进 | 是 | 支持层级压缩 |
| `character` | 角色状态 | 否 | 同名会优先 update |
| `location` | 地点状态 | 否 | 同名会优先 update |
| `rule` | 世界规则、约束 | 是 | 常驻注入 |
| `thread` | 主线/任务线 | 是 | 支持层级压缩 |
| `synopsis` | 全局前情提要 | 是 | 只保留最新 |
| `reflection` | 反思与长期锚点 | 否 | 支持层级压缩 |
### 6.2 关系类型
默认关系类型包括：
- `related`
- `involved_in`
- `occurred_at`
- `advances`
- `updates`
- `contradicts`
- `evolves`
- `temporal_update`
其中：
- `contradicts` 用于矛盾/冲突
- `updates` 与 `temporal_update` 用于状态更新和时序替代
- `evolves` 用于新信息影响旧记忆的理解
--- ---
## 7. 写入流程 ## 📝 记忆类型
写入主流程分为 6 步。 插件会把对话拆解成以下几种记忆节点：
### 7.1 触发 | 类型 | 说明 | 举例 |
|------|------|------|
| 🧑 角色 | 角色的当前状态、性格、外貌变化 | "小明因为淋雨感冒了" |
| ⚡ 事件 | 发生过的事 | "河边的告白" |
| 📍 地点 | 地点状态 | "废弃实验室，门被锁上了" |
| 📌 规则 | 世界观设定、约束 | "魔法会消耗生命力" |
| 🧵 主线 | 任务线/剧情线 | "寻找失踪的项链" |
| 📜 概要 | 自动生成的前情提要 | — |
| 💭 反思 | 长期规律总结 | "他们经常在夕阳下聊天" |
默认按 assistant 楼层触发： 这些节点之间还会建立关系（参与、发生在、推动、矛盾、更新等），形成一张完整的记忆网络。
- `extractEvery = 1`：每 1 条 assistant 回复提取一次
- 若启用 `enableSmartTrigger`，则可提前触发
### 7.2 上下文打包
插件不是只看一条回复，而是从本批次 assistant 楼层向前回看若干轮，把非系统消息整理成：
```text
#12 [user]: ...
#13 [assistant]: ...
```
### 7.3 结构化提取
提取器要求记忆 LLM 返回严格 JSON：
- `create`
- `update`
- `delete`
如果 LLM 返回非法 JSON，会自动重试。
### 7.4 精确对照
若向量配置可用，会对新建记忆做近邻对照：
- 完全重复：跳过
- 是旧记忆修正：转成 `update`
- 真正新信息：保留 `create`
### 7.5 图谱副作用
提取完成后，可能继续触发：
- 记忆进化
- 全局概要
- 反思条目
- 主动遗忘
- 层级压缩
### 7.6 写入日志与向量同步
批次完成后会：
1. 同步向量状态
2. 记录 `batchJournal`
3. 更新已处理楼层与楼层 hash
4. 保存回 `chat_metadata`
--- ---
## 8. 读取流程 ## 🔧 设置说明
召回逻辑主要在 [retriever.js](./retriever.js)。 ### 记忆 LLM
### 8.1 总体流程 用来做提取、压缩、进化、概要等任务的模型。
```text - **留空** → 复用当前 SillyTavern 的聊天模型（最简配置）
用户输入 - **填写** → 你可以指定一个独立的 OpenAI-compatible 模型专门处理记忆
-> 向量候选预筛
-> 图扩散
-> 混合评分
-> 可选 LLM 精排
-> 场景重构
-> 注入格式化
```
### 8.2 候选预筛 ### Embedding（向量搜索）
这里是本次版本最重要的变化之一： 向量搜索是"智能召回"的关键。支持两种模式：
- `backend` 模式：通过酒馆 `/api/vector/query` #### 后端模式（推荐）
- `direct` 模式：插件自己请求 Embedding API，再做余弦相似度
两种模式都会把结果统一成 `[{ nodeId, score }]`，后续流程不区分。 走 SillyTavern 后端的向量 API，最稳定：
### 8.3 图扩散与混合评分 - 支持 OpenAI / Cohere / Mistral / Ollama / LlamaCpp / vLLM 等
- 在设置面板选择「后端向量源」，填好模型名即可
- 不需要单独填 API Key，复用酒馆已有的
候选节点进入图扩散后，会结合： #### 直连模式
- 图扩散能量 如果你需要完全独立的 Embedding 服务（比如酒馆后端不支持的源）：
- 向量得分
- 节点重要性
- 时间衰减
最后得到综合排序。 - 填入 Embedding API 地址、Key、Model
- 插件直接请求你的 Embedding 服务
- 注意浏览器跨域问题（CORS）
### 8.4 注入格式 > **切换向量模式/模型后，建议点一次"重建向量"。**
注入模块在 [injector.js](./injector.js)。 ### 提取设置
它会把结果分成： | 设置 | 默认 | 说明 |
|------|------|------|
| 每 N 条回复提取 | 1 | 每几条 AI 回复做一次提取 |
| 提取上下文轮数 | 2 | 提取时向前看几轮对话 |
| 启用近邻对照 | 开 | 写入前对比现有记忆，避免重复 |
| 启用记忆进化 | 开 | 新记忆会影响旧记忆理解 |
| 启用自动概要 | 开 | 定期生成前情提要 |
| 启用反思 | 关 | 让 AI 总结长期模式 |
| 启用主动遗忘 | 开 | 太久没用的记忆降低优先级 |
- `Core` 常驻注入 ### 召回设置
- `Recalled` 动态召回注入
并进一步分桶为： | 设置 | 默认 | 说明 |
|------|------|------|
- 当前状态记忆 | 召回上下文轮数 | 3 | 让 AI 根据最近几轮来召回 |
- 情景事件记忆 | 向量候选数 | 15 | 向量搜索返回多少候选 |
- 反思与长期锚点 | 扩散深度 | 2 | 在图上沿关系扩散几层 |
- 规则与约束 | 最终注入数 | 12 | 最终注入多少条记忆 |
- 其他关联记忆 | Token 预算 | 1500 | 注入的最大 token 估算 |
--- ---
## 9. 向量模式 ## 🖥️ 操控面板
当前版本支持两种 Embedding 工作模式。 从左上角 ≡ 菜单点「🧠 记忆图谱」打开面板，或在右侧设置里点「打开操控面板」。
### 9.1 backend 模式 ### 总览 Tab
- 统计数据（活跃节点、边、归档数、碎片率）
- 运行状态（聊天 ID、向量状态、历史状态）
- 最近提取 / 召回的记忆
适用场景： ### 记忆 Tab
- 搜索和筛选记忆节点
- 点击节点查看详情
- 支持按类型过滤
- 希望尽量走酒馆后端 ### 注入 Tab
- 希望发布后少受浏览器跨域限制 - 预览当前注入内容
- 向量 provider 在酒馆现成支持范围内 - 查看 token 消耗
支持来源： ### 操作 Tab
- 手动提取 — 立即从当前对话提取
- 手动压缩 — 合并重复/过时记忆
- 执行遗忘 — 主动降级低价值记忆
- 更新概要 — 重新生成前情提要
- 导出 / 导入图谱
- 重建图谱 — 从当前聊天重新提取全部记忆
- 重建向量 — 重建全部向量索引
- 强制进化 — 让新记忆影响旧记忆
- `openai` ### 配置 Tab
- `openrouter` 在面板内可以直接修改记忆 LLM 和 Embedding 配置，无需退出面板。
- `cohere`
- `mistral`
- `electronhub`
- `chutes`
- `nanogpt`
- `ollama`
- `llamacpp`
- `vllm`
实现方式： ### 图谱可视化
桌面端右侧大区域显示力导向图谱，节点可拖拽、缩放、点击查看详情。支持 4 套配色主题切换。
- 使用酒馆 `/api/vector/insert`
- 使用酒馆 `/api/vector/query`
- 使用酒馆 `/api/vector/delete`
- 使用酒馆 `/api/vector/purge`
说明：
- `openai/openrouter/cohere/...` 这类 provider 依赖宿主已有 provider/secret 体系
- `ollama/llamacpp/vllm` 这类 provider 需要额外填写地址
### 9.2 direct 模式
适用场景：
- 你需要完全独立的第二 Embedding URL/Key/Model
- 目标服务不在酒馆现成 provider 边界内
实现方式：
- 插件直接请求你配置的 OpenAI-compatible `/embeddings`
- 节点 embedding 继续保存在图节点里
### 9.3 模式切换行为
切换以下任一项时，向量状态都会被标记为 `dirty`：
- `mode`
- `source`
- `model`
- `apiUrl`
- `autoSuffix`
- 导入图谱
之后：
- 召回前会自动修复索引
- 或者你也可以手动点击“重建向量”
--- ---
## 10. 历史回退恢复 ## 🔄 历史安全
这是本版本与旧实现最大的行为升级之一。 这是最重要的功能之一。
### 10.1 旧问题 当你在 SillyTavern 里做以下操作时：
- 删除某条消息
旧实现只能线性推进 `lastProcessedSeq`。 - 编辑某条消息
一旦用户：
- 删除旧楼层
- 编辑旧楼层
- 切换 swipe - 切换 swipe
图谱和已处理指针就可能和真实聊天历史不一致。 插件会自动检测到历史发生了变化，然后：
### 10.2 新策略：先止损，再恢复 1. **止损** — 停止当前推进，清空可能失效的注入
2. **回滚** — 找到受影响的批次，删除相关记忆和向量
3. **恢复** — 从变动点重新提取
插件会在历史变动事件发生时： 这样你就不用担心"改了历史但记忆还留着错的内容"的问题。
1. 比对已处理楼层的消息 hash
2. 找出最早受影响楼层
3. 立刻清空旧注入、停止本轮继续推进
4. 记录 `historyDirtyFrom`
5. 在下一次提取或召回前自动恢复
### 10.3 恢复方式
优先策略：
- 从 `batchJournal` 找到受影响前的恢复点
- 回滚受影响后缀
- 删除对应向量 hash
- 从脏楼层重新提取和后处理
兜底策略：
- 如果 journal 缺失或损坏
- 直接按当前聊天全文重建图谱与向量索引
### 10.4 不是 Engram 式的“只对齐指针”
这里必须强调：
ST-BME 当前的恢复不是简单地把“上次提取楼层”对齐到当前楼层然后跳过。
因为 ST-BME 的写入副作用很多：
- 更新节点
- 压缩节点
- 概要
- 反思
- 进化
- 迁移边
所以必须做真正的“回滚 + 重放”，否则图谱会留下脏状态。
--- ---
## 11. 面板与操作 ## 📋 手动操作速查
图谱面板现在主要分 5 个区域： | 操作 | 说明 |
|------|------|
- 总览 | 手动提取 | 不等自动触发，立刻提取当前对话 |
- 记忆浏览 | 手动压缩 | 把重复/冗余的事件合并 |
- 注入预览 | 执行遗忘 | 降低长期未使用记忆的优先级 |
- 操作 | 更新概要 | 重新生成全局前情提要 |
- 配置 | 导出图谱 | 下载当前图谱 JSON（不含向量） |
| 导入图谱 | 导入图谱文件（导入后需重建向量） |
### 11.1 新增运行状态 | 重建图谱 | ⚠️ 清空现有图谱，从聊天记录重新提取 |
| 重建向量 | 重建全部节点的向量索引 |
总览页会显示： | 范围重建向量 | 只重建指定楼层范围内的向量 |
| 强制进化 | 让新记忆深度影响旧记忆认知 |
- 当前聊天 `chatId`
- 历史状态
- 向量状态
- 最近恢复结果
### 11.2 手动操作
当前支持：
- 手动提取
- 手动压缩
- 执行遗忘
- 更新概要
- 导出图谱
- 导入图谱
- 重建图谱
- 强制进化
- 重建向量
- 范围重建
- 直连重嵌
说明：
- “重建图谱”会按当前聊天重放整个提取流程
- “重建向量”会重建当前聊天全部向量
- “范围重建”只重建与指定楼层范围相交的节点向量
- “直连重嵌”仅在 `direct` 模式下有意义
--- ---
## 12. 设置说明 ## 🏗️ 开发者参考
### 12.1 记忆 LLM ### 文件结构
这套配置用于： ```
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 请求封装
- 留空：复用当前 SillyTavern 聊天模型 ├── compressor.js # 层级压缩与遗忘
- 填写后：通过酒馆现成后端代理转发到你配置的 OpenAI-compatible 聊天接口 ├── evolution.js # 记忆进化（A-MEM 风格）
├── diffusion.js # 图扩散算法
### 12.2 Embedding ├── dynamics.js # 动态调节（重要度衰减等）
├── schema.js # 节点类型定义
当前设置项分成两组： ├── themes.js # 4 套主题配色
├── graph-renderer.js # Canvas 力导向图谱渲染器
#### 后端模式相关 ├── panel.js # 操控面板交互逻辑
├── panel.html # 面板 HTML 模板
| 字段 | 作用 | ├── settings.html # 右侧设置面板
| --- | --- | ├── style.css # 全部样式
| `embeddingTransportMode` | `backend` / `direct` | ├── manifest.json # SillyTavern 扩展清单
| `embeddingBackendSource` | 后端向量源 | └── tests/ # 测试脚本
| `embeddingBackendModel` | 后端模型 |
| `embeddingBackendApiUrl` | 仅部分后端源需要 |
| `embeddingAutoSuffix` | 自动补全后缀 |
#### 直连模式相关
| 字段 | 作用 |
| --- | --- |
| `embeddingApiUrl` | 直连 Embedding API 地址 |
| `embeddingApiKey` | 直连 API Key |
| `embeddingModel` | 直连模型 |
---
## 13. 导入导出与兼容
### 13.1 导出
导出时会主动剥离：
- 节点 embedding
- 向量索引映射
- batch journal
这样导出的文件仍然是“轻量图谱文件”，而不是整段运行时缓存快照。
### 13.2 导入
导入后会：
- 保留图谱结构
- 清空节点 embedding
- 清空 batch journal
- 标记向量状态为 `dirty`
也就是说：
- 图谱可以立即查看
- 向量需要后续重建
### 13.3 旧图谱迁移
当前版本会把旧版图谱自动迁移到 v4，并补出：
- `historyState`
- `vectorIndexState`
- `batchJournal`
迁移后默认会提示需要重建向量运行时状态。
---
## 14. 文件结构
这里列出最重要的模块：
| 文件 | 作用 |
| --- | --- |
| [index.js](./index.js) | 主入口，事件绑定、主流程调度、历史恢复、向量同步 |
| [graph.js](./graph.js) | 图数据模型、序列化、版本迁移、导入导出 |
| [extractor.js](./extractor.js) | 结构化提取、冲突对照、概要、反思 |
| [retriever.js](./retriever.js) | 向量候选、图扩散、混合评分、LLM 精排 |
| [runtime-state.js](./runtime-state.js) | 历史 hash、dirty 标记、journal、恢复点定位 |
| [vector-index.js](./vector-index.js) | backend/direct 向量模式与索引同步 |
| [llm.js](./llm.js) | 记忆 LLM 封装，支持酒馆后端代理 |
| [embedding.js](./embedding.js) | 直连 Embedding API 封装 |
| [compressor.js](./compressor.js) | 层级压缩与主动遗忘 |
| [evolution.js](./evolution.js) | 记忆进化 |
| [panel.html](./panel.html) / [panel.js](./panel.js) | 记忆图谱操控面板 |
---
## 15. 已知边界
当前版本已经解决了“不能改酒馆本体”的发布问题，但仍有一些边界需要明确：
1. **backend Embedding 不是任意 URL/Key 全兼容**
- 它只能落在酒馆现成 `/api/vector/*` 已支持的 provider 边界内。
2. **direct 模式仍然受浏览器环境限制**
- 例如 CORS、Mixed Content、远程访问时 `127.0.0.1` 指向错误等。
3. **历史恢复正确性优先于性能**
- 当 journal 不可用时，会退化为当前聊天全量重建。
4. **图谱仍然依赖 LLM 提取质量**
- 结构化输出如果失真，图谱也会跟着失真。
---
## 16. 测试
当前仓库内已有并正在使用的检查包括：
```powershell
node --check index.js
node --check extractor.js
node --check retriever.js
node --check graph.js
node --check runtime-state.js
node --check vector-index.js
node --check panel.js
``` ```
测试脚本： ### 数据存储
```powershell - **图谱数据** → `chat_metadata.st_bme_graph`（跟随聊天保存）
node tests/smart-trigger.mjs - **插件设置** → SillyTavern 的 `extension_settings.st_bme`
node tests/graph-retrieval.mjs - **向量索引** → 后端模式走酒馆 API；直连模式存在节点内
node tests/injector-format.mjs
node tests/runtime-history.mjs ### 事件挂载
node tests/vector-config.mjs
| SillyTavern 事件 | 做什么 |
|---|---|
| `CHAT_CHANGED` | 加载对应聊天的图谱 |
| `GENERATION_AFTER_COMMANDS` | AI 回复后提取记忆 |
| `GENERATE_BEFORE_COMBINE_PROMPTS` | 生成前召回并注入 |
| `MESSAGE_RECEIVED` | 保存图谱状态 |
| 删除 / 编辑 / Swipe | 触发历史变动检测与恢复 |
### 召回流水线
```
用户输入 → 向量预筛 → 图扩散 → 混合评分 → [可选 LLM 精排] → 场景重构 → 分桶注入
``` ```
其中新增测试覆盖了： ### 注入格式
- 历史 hash 检测 召回结果分成两层注入：
- journal 恢复点定位
- 向量模式配置归一化 - **Core**（常驻）：规则、概要、主线
- backend/direct 基本配置校验 - **Recalled**（动态）：根据当前对话召回
每层内进一步按用途分桶：当前状态 / 情景事件 / 反思锚点 / 规则约束。
--- ---
## 17. 适合的使用方式 ## ⚠️ 已知限制
如果你的目标是： 1. **记忆质量取决于 LLM** — 模型提取不准，记忆也会不准
2. **直连模式有跨域风险** — 浏览器的 CORS 限制可能导致请求失败
- 长期 RP 3. **后端向量仅支持酒馆已有 provider** — 不在列表里的需要用直连
- 世界观持续累积 4. **恢复优先正确性** — 批次日志缺失时会退化为全量重建，可能较慢
- 多角色状态维护
- 任务线/主线长期跟踪
- 对话发生删改时尽量不留下脏记忆
那么当前 ST-BME 已经比最早版本更适合作为“长期记忆图谱层”使用。
推荐默认用法：
1. 记忆 LLM：可独立配置，也可复用当前酒馆模型
2. 向量：优先 `backend`
3. 只有当你明确需要第二套完全独立 Embedding URL/Key/Model 时，再切到 `direct`
--- ---
## 18. 总结 ## 📄 License
当前 ST-BME 已经不是“只会抽点节点再注入”的原型版本，而是一套更完整的插件内记忆层： AGPLv3 — 详见 [LICENSE](./LICENSE)
- 图谱仍然和聊天强绑定
- 发布形态仍然是纯第三方扩展
- 向量层支持后端索引优先
- 历史变动支持真正恢复，而不只是指针对齐
- UI 里可以直接看到当前聊天、向量和恢复状态
如果你希望它继续往更重型方向发展，下一步最自然的演进会是：
- 扩展更细的恢复测试
- 增加范围级重放面板
- 增加 provider 级能力说明与自动诊断
- 继续压缩 `batchJournal` 的体积成本