# ST-BME

> 面向 [SillyTavern](https://github.com/SillyTavern/SillyTavern) 的双向记忆图谱扩展，用于在长对话、角色扮演与持续故事创作中提供结构化写入、图谱检索与可控注入能力。

## 项目简介

ST-BME（ST-Bionic-Memory-Ecology）是一个运行在 SillyTavern 第三方扩展体系中的记忆模块。它围绕“写入”和“读取”两条路径工作：

- 写入侧将聊天内容提取为结构化节点与关系，持久化到当前聊天元数据中。
- 读取侧在生成前根据用户输入检索相关记忆，并以格式化内容注入上下文。

项目的目标不是替代模型本身的上下文理解，而是在长周期互动中为模型补充一层可累积、可筛选、可演化的外部记忆表示。

当前实现以知识图谱为核心，结合向量相似度、图扩散、LLM 精确筛选，以及若干受外部研究项目启发的增强机制。

## 核心特性

### 已实现

- **图谱化记忆存储**：使用节点与边表示事件、角色、地点、规则、主线、概要等结构化信息。
- **聊天级持久化**：图状态写入当前聊天 `chat_metadata`，可随聊天保存与恢复。
- **自动记忆提取**：按设定频率从最近对话中抽取结构化操作并更新图谱。
- **三阶段召回编排**：支持向量预筛、图扩散排序、混合评分与可选 LLM 精确召回。
- **情景重构召回**：会围绕命中的事件、角色、地点自动补齐相邻场景节点，使注入结果更接近连续剧情记忆。
- **层级压缩**：对事件与主线等类型执行分层摘要，控制图谱膨胀。
- **全局概要节点**：周期性生成 `synopsis` 类型节点，作为长期叙事锚点。
- **记忆进化**：新节点写入后，基于近邻分析回溯更新已有记忆并建立新连接。
- **时序更新追踪增强**：节点更新时会补充 `updates` / `temporal_update` 语义链路，并生成可追踪的状态更新事件。
- **反思条目生成**：支持按提取周期生成 `reflection` 节点，用于沉淀高层叙事结论、关系趋势与后续建议。
- **时序边字段**：关系边携带 `validAt` / `invalidAt` / `expiredAt` 等时间语义字段。
- **导入导出与手动操作入口**：设置面板已提供查看图谱、查看注入、重建、压缩、导入、导出等入口。

### 实验性

以下能力在代码和设置项中已出现，但成熟度与验证覆盖仍有限，应视为实验性：

- **Mem0 风格精确对照**：新记忆可与近邻旧记忆对照后再决定新增、更新或跳过。
- **认知边界过滤**：可按可见性约束过滤检索结果，适用于“角色不知道的信息不应注入”的场景。
- **交叉检索**：实体命中后沿图边扩展相关事件节点，补充情境上下文。
- **分桶式注入编排**：召回结果会按“当前状态 / 情景事件 / 反思锚点 / 规则约束”分组组织，降低碎片化注入。
- **主动遗忘**：按保留价值归档低价值节点，缓解长期运行后的图谱膨胀。
- **概率触发回忆**：未被主流程命中的高重要性节点有概率被额外召回。

### 规划中

以下方向在现有代码中仅有预留开关、设计痕迹或路线图描述，尚不应视为完整能力：

- **完整端到端测试与稳定性验证**
- **图谱可视化面板**
- **自定义 Schema 编辑体验增强**
- **多聊天图谱合并与迁移工具**
- **导出为 World Info 等外部格式的更完整支持**

## 适用场景

ST-BME 当前更适合以下场景：

- 长篇角色扮演（RP）与多人剧情对话
- 需要持续追踪角色状态、地点状态、事件推进的故事生成
- 世界观设定较多、规则需要持续注入的互动创作
- 需要在单个聊天内形成“前情提要 + 当前状态 + 局部召回”结构的长期陪伴式对话

对短聊天、一次性问答、无结构叙事需求的场景，ST-BME 的收益通常不会明显高于普通上下文管理。

## 架构概览

### 写入路径

1. 从聊天中收集尚未处理的对话片段。
2. 调用提取器生成结构化操作（创建 / 更新 / 删除）。
3. 按配置执行近邻对照，降低重复创建概率。
4. 将新节点写入图谱，并补充关系边。
5. 为缺失向量的节点生成 embedding。
6. 可选执行记忆进化、全局概要更新、主动遗忘与层级压缩。
7. 将图状态保存回聊天元数据。

### 读取路径

1. 读取当前活跃图节点。
2. 可选先做认知边界过滤。
3. 执行向量预筛与实体锚点识别。
4. 基于时序邻接图做扩散排序。
5. 按混合评分汇总候选节点。
6. 在小图或大图场景下，可进一步调用 LLM 做精确召回。
7. 将结果格式化后注入到生成上下文中。

### 模块对应关系

- [`index.js`](ST-BME/index.js)：扩展入口、设置管理、流程调度、持久化挂钩
- [`extractor.js`](ST-BME/extractor.js)：记忆提取、精确对照、概要生成
- [`retriever.js`](ST-BME/retriever.js)：召回主流程、混合评分、可选精确召回
- [`graph.js`](ST-BME/graph.js)：图数据模型、节点边操作、时序字段
- [`compressor.js`](ST-BME/compressor.js)：层级压缩与主动遗忘
- [`evolution.js`](ST-BME/evolution.js)：新记忆触发的近邻进化
- [`diffusion.js`](ST-BME/diffusion.js)：图扩散排序
- [`schema.js`](ST-BME/schema.js)：默认节点类型定义与关系类型约束
- [`injector.js`](ST-BME/injector.js)：召回结果格式化与注入内容构建
- [`embedding.js`](ST-BME/embedding.js)：OpenAI 兼容 embedding 接口封装
- [`llm.js`](ST-BME/llm.js)：LLM JSON 调用封装

## 目录结构

```text
ST-BME/
├── manifest.json       # 扩展清单
├── index.js            # 扩展入口与流程编排
├── settings.html       # 设置面板
├── style.css           # UI 样式
├── graph.js            # 图数据模型
├── schema.js           # 节点类型与关系定义
├── extractor.js        # 写入路径
├── retriever.js        # 读取路径
├── evolution.js        # 记忆进化
├── compressor.js       # 压缩与主动遗忘
├── diffusion.js        # 图扩散算法
├── dynamics.js         # 动态评分与访问强化
├── embedding.js        # Embedding API 封装
├── llm.js              # LLM 调用封装
├── injector.js         # 注入格式化
├── LICENSE             # 许可证
└── README.md
```

## 安装方式

### 1. 准备环境

先确保本地已经可正常运行 SillyTavern。

### 2. 放置扩展目录

将 [`ST-BME`](ST-BME) 目录放入 SillyTavern 第三方扩展目录，例如：

```text
SillyTavern/public/scripts/extensions/third-party/ST-BME/
```

### 3. 重新加载 SillyTavern

重启或刷新 SillyTavern 后，在扩展面板中应能看到 ST-BME 对应条目。扩展清单定义见 [`manifest.json`](ST-BME/manifest.json)。

### 4. 配置 Embedding 接口

若要启用向量检索、近邻对照与部分增强能力，需要填写可用的 OpenAI 兼容 embedding 接口：

- API 地址
- API Key
- 模型名

默认模型名为 `text-embedding-3-small`。

## 配置说明

设置面板位于 [`settings.html`](ST-BME/settings.html)，当前主要配置可分为以下几类。

### 基础开关

| 配置项            | 默认值 | 说明                                  |
| ----------------- | ------ | ------------------------------------- |
| 启用记忆图谱      | 关闭   | 总开关，关闭时不执行提取与召回        |
| 每 N 条回复提取   | 1      | 控制提取频率                          |
| 启用记忆召回注入  | 开启   | 是否在生成前注入检索结果              |
| 启用 LLM 精确召回 | 开启   | 小图 / 大图场景下可进一步筛选候选记忆 |
| 注入深度          | 4      | 控制注入位置                          |

### 混合评分权重

默认权重来自 [`index.js`](ST-BME/index.js)：

| 参数       | 默认值 |
| ---------- | ------ |
| 图扩散权重 | 0.6    |
| 向量权重   | 0.3    |
| 重要性权重 | 0.1    |

### 增强能力开关

| 能力         | 默认状态 | 当前判断                   |
| ------------ | -------- | -------------------------- |
| 记忆进化     | 开启     | 已实现                     |
| 精确对照     | 开启     | 实验性                     |
| 全局概要     | 开启     | 已实现                     |
| 认知边界     | 关闭     | 实验性                     |
| 交叉检索     | 关闭     | 实验性                     |
| 惊奇度分割   | 关闭     | 规划中 / 预留开关          |
| 主动遗忘     | 关闭     | 实验性                     |
| 概率触发回忆 | 关闭     | 实验性                     |
| 反思条目     | 关闭     | 已实现（建议先小规模验证） |

## 数据模型

### 图状态

图状态由以下核心部分组成：

- `version`
- `lastProcessedSeq`
- `nodes`
- `edges`
- `lastRecallResult`

其中节点和边统一由 [`graph.js`](ST-BME/graph.js) 管理，并序列化到聊天元数据中。

### 节点类型

默认 Schema 定义在 [`schema.js`](ST-BME/schema.js)。当前内置节点类型包括：

| 类型         | 用途                 | 当前状态                             |
| ------------ | -------------------- | ------------------------------------ |
| `event`      | 事件、动作、剧情推进 | 已实现                               |
| `character`  | 角色状态快照         | 已实现                               |
| `location`   | 地点与环境状态       | 已实现                               |
| `rule`       | 世界规则、约束与设定 | 已实现                               |
| `thread`     | 主线与阶段性进度     | 已实现                               |
| `synopsis`   | 全局前情提要         | 已实现                               |
| `reflection` | 反思与元认知记录     | 已实现周期生成，建议结合实际剧情验证 |

### 关系类型

当前内置关系类型包括：

- `related`
- `involved_in`
- `occurred_at`
- `advances`
- `updates`
- `contradicts`
- `evolves`
- `temporal_update`

### 时序语义

边对象已实现以下时间字段：

- `validAt`：关系生效时间
- `invalidAt`：关系失效时间
- `expiredAt`：系统标记过期时间

这为后续更严格的“过去事实 / 当前事实”区分提供了基础，但实际策略仍在持续打磨中。

## 使用流程

### 最小使用步骤

1. 在扩展面板中启用 ST-BME。
2. 配置 Embedding API。
3. 开启“记忆召回注入”。
4. 开始正常聊天，让系统按设定频率自动提取记忆。
5. 使用“查看图谱”或“查看注入”观察当前状态。

### 推荐使用方式

- 初次使用时保持默认 Schema，不要一开始就大幅改结构。
- 长剧情场景下保留“全局概要”与“记忆进化”。
- 图规模较小时可保留 LLM 精确召回，图规模增大后再按成本调整。
- 若叙事强依赖角色认知差异，可逐步测试“认知边界”。
- 对 API 成本敏感时，提高“每 N 条回复提取”的数值。

## 当前状态

### 已实现

- 扩展基础骨架与设置面板
- 聊天级图谱持久化
- 默认 Schema 与关系类型
- 提取、召回、注入三段式主流程
- 向量检索接入
- 图扩散排序
- 层级压缩
- 记忆进化
- 全局概要节点
- 边的时序字段与失效处理基础逻辑
- 导入导出入口

### 实验性

- 精确对照对重复 / 更新场景的稳定收益
- 认知边界过滤在复杂多角色剧情中的效果
- 交叉检索对召回质量的增益
- 主动遗忘的阈值与副作用控制
- 概率触发回忆的叙事收益与噪声控制
- 情景重构召回在大图、复杂多线叙事中的排序稳定性

### 规划中

- 惊奇度驱动的提取触发机制
- 反思节点自动生成闭环
- 更完整的可视化与调试工具
- 智能触发提取与惊奇度分割的进一步增强
- 更系统的 benchmark、回归测试与使用文档

## 路线图

- [ ] 补充端到端测试与典型场景回归样例
- [x] 完善惊奇度分割与智能触发提取（轻量 MVP）
- [ ] 完成反思条目生成与注入策略
- [ ] 提供图谱可视化界面
- [ ] 增强 Schema 配置与编辑体验
- [ ] 增加多聊天图谱合并能力
- [ ] 完善导出为外部记忆格式的支持

## 设计来源与参考

本项目当前实现和设计思路参考了仓库内收录的若干研究型项目与实现，但 ST-BME 自身为面向 SillyTavern 扩展场景的工程整合。

| 参考项目                     | 主要启发方向              |
| ---------------------------- | ------------------------- |
| [`A-MEM`](A-MEM/README.md)   | 记忆进化、近邻回溯更新    |
| [`EM-LLM`](EM-LLM/README.md) | 事件边界 / 惊奇度分割思路 |
| `Graphiti`                   | 时序关系与图结构管理      |
| `Mem0`                       | 新旧记忆对照与更新决策    |
| `RoleRAG`                    | 认知边界过滤              |
| `AriGraph`                   | 沿图边扩展的交叉检索      |
| `MemoRAG`                    | 全局概要作为长期锚点      |
| `SleepGate`                  | 主动遗忘与保留价值评估    |
| `Reflexion`                  | 反思条目方向              |

## 许可证

本项目采用 AFPL License 发布，详见 [`LICENSE`](ST-BME/LICENSE)。