From 95cde04e6469f09b4158ba273c32e83083b7932f Mon Sep 17 00:00:00 2001 From: Youzini-afk <13153778771cx@gmail.com> Date: Tue, 24 Mar 2026 16:47:06 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README=EF=BC=8C?= =?UTF-8?q?=E9=9D=A2=E5=90=91=E7=94=A8=E6=88=B7=E5=92=8C=E5=BC=80=E5=8F=91?= =?UTF-8?q?=E8=80=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 797 +++++++++++++----------------------------------------- 1 file changed, 187 insertions(+), 610 deletions(-) diff --git a/README.md b/README.md index b52ccce..60cc4b2 100644 --- a/README.md +++ b/README.md @@ -1,696 +1,273 @@ -# ST-BME Memory Graph +# 🧠 ST-BME — SillyTavern 图谱记忆插件 -> 面向 SillyTavern 第三方扩展体系的图谱记忆插件。 -> 它把聊天历史转换成结构化记忆图，在生成前按场景召回并注入，服务于长期 RP、持续剧情、角色状态维护和多轮世界观演化。 - -## 1. 项目定位 - -ST-BME 的核心目标不是“把所有聊天全文塞回上下文”，而是把对话中的长期信息拆成可维护、可更新、可压缩、可检索的记忆图。 - -当前版本坚持 3 个原则： - -1. **不改酒馆本体** - - 作为可发布的第三方扩展运行。 - - 不要求用户给 SillyTavern 打补丁。 - -2. **图谱真相源留在聊天元数据** - - 图谱主体继续跟随当前聊天保存在 `chat_metadata.st_bme_graph`。 - - 不把图谱主数据迁移到独立数据库或服务器文件。 - -3. **向量与图谱解耦** - - 图谱负责结构、时序、压缩、召回分层。 - - 向量只负责语义候选预筛，可以走后端索引，也可以走独立直连兜底。 +> **让 AI 真正记住你们的故事。** +> +> ST-BME 把对话中散落的角色、事件、地点、关系自动提取为记忆图谱，在下一轮生成前精准召回，让长期 RP 的角色不再"失忆"。 --- -## 2. 当前能力概览 +## ✨ 它能做什么 -### 2.1 写入能力 - -- assistant 回复后自动提取未处理楼层 -- LLM 结构化输出 `create / update / delete` -- 支持事件、角色、地点、规则、主线、概要、反思节点 -- 支持时序边、更新边、矛盾边 -- 支持 Mem0 风格近邻对照，减少重复写入 -- 支持 A-MEM 风格记忆进化 -- 支持全局概要生成 -- 支持反思条目生成 -- 支持主动遗忘 -- 支持层级压缩 - -### 2.2 读取能力 - -- 生成前自动召回记忆 -- 向量预筛 -- 图扩散 -- 混合评分 -- 可选 LLM 精确召回 -- 场景重构 -- 分桶注入：状态记忆 / 情景事件 / 反思锚点 / 规则约束 - -### 2.3 运维与安全能力 - -- 新聊天、分支聊天、切换聊天自动隔离 -- 支持图谱导入导出 -- 支持图谱全量重建 -- 支持向量全量重建 -- 支持向量范围重建 -- 支持直连模式全量重嵌 -- 支持历史回退检测与自动恢复 +- 🧩 **自动提取** — 每次 AI 回复后，从上下文中抽取角色状态、事件、地点、规则、主线等结构化记忆 +- 🔍 **智能召回** — 生成前根据当前对话自动检索最相关的记忆，注入 prompt +- 🌐 **图谱可视化** — 内置力导向图谱面板，直观查看记忆节点之间的关系 +- 🎨 **4 套配色主题** — Crimson Synth / Neon Cyan / Amber Console / Violet Haze +- 📱 **手机端适配** — 底部 Tab Bar + 精简布局，手机也能用 +- 🔄 **历史安全** — 删楼、编辑、切 swipe 时自动回滚恢复，不留脏记忆 +- 📦 **不改酒馆本体** — 纯第三方扩展，即装即用 --- -## 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. **运行时状态层** - - 仍然跟随图谱一起保存在 `chat_metadata` - - 保存历史处理指针、楼层 hash、脏区、向量索引映射、batch journal - -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 +```bash +cd SillyTavern/data/default-user/extensions/third-party +git clone https://github.com/pjm0616/ST-Bionic-Memory-Ecology.git st-bme ``` -### 5.2 图状态核心字段 - -| 字段 | 含义 | -| --- | --- | -| `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::` | -| `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` +重启 SillyTavern 即可。 --- -## 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 -用户输入 - -> 向量候选预筛 - -> 图扩散 - -> 混合评分 - -> 可选 LLM 精排 - -> 场景重构 - -> 注入格式化 -``` +- **留空** → 复用当前 SillyTavern 的聊天模型（最简配置） +- **填写** → 你可以指定一个独立的 OpenAI-compatible 模型专门处理记忆 -### 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 +- 搜索和筛选记忆节点 +- 点击节点查看详情 +- 支持按类型过滤 -- 希望尽量走酒馆后端 -- 希望发布后少受浏览器跨域限制 -- 向量 provider 在酒馆现成支持范围内 +### 注入 Tab +- 预览当前注入内容 +- 查看 token 消耗 -支持来源： +### 操作 Tab +- 手动提取 — 立即从当前对话提取 +- 手动压缩 — 合并重复/过时记忆 +- 执行遗忘 — 主动降级低价值记忆 +- 更新概要 — 重新生成前情提要 +- 导出 / 导入图谱 +- 重建图谱 — 从当前聊天重新提取全部记忆 +- 重建向量 — 重建全部向量索引 +- 强制进化 — 让新记忆影响旧记忆 -- `openai` -- `openrouter` -- `cohere` -- `mistral` -- `electronhub` -- `chutes` -- `nanogpt` -- `ollama` -- `llamacpp` -- `vllm` +### 配置 Tab +在面板内可以直接修改记忆 LLM 和 Embedding 配置，无需退出面板。 -实现方式： - -- 使用酒馆 `/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` -- 导入图谱 - -之后： - -- 召回前会自动修复索引 -- 或者你也可以手动点击“重建向量” +### 图谱可视化 +桌面端右侧大区域显示力导向图谱，节点可拖拽、缩放、点击查看详情。支持 4 套配色主题切换。 --- -## 10. 历史回退恢复 +## 🔄 历史安全 -这是本版本与旧实现最大的行为升级之一。 +这是最重要的功能之一。 -### 10.1 旧问题 - -旧实现只能线性推进 `lastProcessedSeq`。 -一旦用户： - -- 删除旧楼层 -- 编辑旧楼层 +当你在 SillyTavern 里做以下操作时： +- 删除某条消息 +- 编辑某条消息 - 切换 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 个区域： - -- 总览 -- 记忆浏览 -- 注入预览 -- 操作 -- 配置 - -### 11.1 新增运行状态 - -总览页会显示： - -- 当前聊天 `chatId` -- 历史状态 -- 向量状态 -- 最近恢复结果 - -### 11.2 手动操作 - -当前支持： - -- 手动提取 -- 手动压缩 -- 执行遗忘 -- 更新概要 -- 导出图谱 -- 导入图谱 -- 重建图谱 -- 强制进化 -- 重建向量 -- 范围重建 -- 直连重嵌 - -说明： - -- “重建图谱”会按当前聊天重放整个提取流程 -- “重建向量”会重建当前聊天全部向量 -- “范围重建”只重建与指定楼层范围相交的节点向量 -- “直连重嵌”仅在 `direct` 模式下有意义 +| 操作 | 说明 | +|------|------| +| 手动提取 | 不等自动触发，立刻提取当前对话 | +| 手动压缩 | 把重复/冗余的事件合并 | +| 执行遗忘 | 降低长期未使用记忆的优先级 | +| 更新概要 | 重新生成全局前情提要 | +| 导出图谱 | 下载当前图谱 JSON（不含向量） | +| 导入图谱 | 导入图谱文件（导入后需重建向量） | +| 重建图谱 | ⚠️ 清空现有图谱，从聊天记录重新提取 | +| 重建向量 | 重建全部节点的向量索引 | +| 范围重建向量 | 只重建指定楼层范围内的向量 | +| 强制进化 | 让新记忆深度影响旧记忆认知 | --- -## 12. 设置说明 +## 🏗️ 开发者参考 -### 12.1 记忆 LLM +### 文件结构 -这套配置用于： - -- 提取 -- 精确召回 -- 压缩 -- 进化 -- 概要 -- 反思 - -实现方式： - -- 留空：复用当前 SillyTavern 聊天模型 -- 填写后：通过酒馆现成后端代理转发到你配置的 OpenAI-compatible 聊天接口 - -### 12.2 Embedding - -当前设置项分成两组： - -#### 后端模式相关 - -| 字段 | 作用 | -| --- | --- | -| `embeddingTransportMode` | `backend` / `direct` | -| `embeddingBackendSource` | 后端向量源 | -| `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 +``` +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/ # 测试脚本 ``` -测试脚本： +### 数据存储 -```powershell -node tests/smart-trigger.mjs -node tests/graph-retrieval.mjs -node tests/injector-format.mjs -node tests/runtime-history.mjs -node tests/vector-config.mjs +- **图谱数据** → `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 精排] → 场景重构 → 分桶注入 ``` -其中新增测试覆盖了： +### 注入格式 -- 历史 hash 检测 -- journal 恢复点定位 -- 向量模式配置归一化 -- backend/direct 基本配置校验 +召回结果分成两层注入： + +- **Core**（常驻）：规则、概要、主线 +- **Recalled**（动态）：根据当前对话召回 + +每层内进一步按用途分桶：当前状态 / 情景事件 / 反思锚点 / 规则约束。 --- -## 17. 适合的使用方式 +## ⚠️ 已知限制 -如果你的目标是： - -- 长期 RP -- 世界观持续累积 -- 多角色状态维护 -- 任务线/主线长期跟踪 -- 对话发生删改时尽量不留下脏记忆 - -那么当前 ST-BME 已经比最早版本更适合作为“长期记忆图谱层”使用。 - -推荐默认用法： - -1. 记忆 LLM：可独立配置，也可复用当前酒馆模型 -2. 向量：优先 `backend` -3. 只有当你明确需要第二套完全独立 Embedding URL/Key/Model 时，再切到 `direct` +1. **记忆质量取决于 LLM** — 模型提取不准，记忆也会不准 +2. **直连模式有跨域风险** — 浏览器的 CORS 限制可能导致请求失败 +3. **后端向量仅支持酒馆已有 provider** — 不在列表里的需要用直连 +4. **恢复优先正确性** — 批次日志缺失时会退化为全量重建，可能较慢 --- -## 18. 总结 +## 📄 License -当前 ST-BME 已经不是“只会抽点节点再注入”的原型版本，而是一套更完整的插件内记忆层： - -- 图谱仍然和聊天强绑定 -- 发布形态仍然是纯第三方扩展 -- 向量层支持后端索引优先 -- 历史变动支持真正恢复，而不只是指针对齐 -- UI 里可以直接看到当前聊天、向量和恢复状态 - -如果你希望它继续往更重型方向发展，下一步最自然的演进会是： - -- 扩展更细的恢复测试 -- 增加范围级重放面板 -- 增加 provider 级能力说明与自动诊断 -- 继续压缩 `batchJournal` 的体积成本 +AGPLv3 — 详见 [LICENSE](./LICENSE)