ST-Bionic-Memory-Ecology/docs/README.md

ST-BME 开发者文档

这里是 ST-Bionic-Memory-Ecology（ST-BME）的开发者/架构文档。面向想理解内部原理、算法、或参与维护的人。

普通用户的安装、面板、配置、排障说明在仓库根目录的 README.md，本目录不重复。

文档地图

architecture/ — 架构与控制平面

跨文件的结构、数据路径、不变量。这些内容变化慢，是理解"为什么这样组织"的入口。

• overview.md — 子系统地图 + 写入/读取/安全三条数据路径
• control-plane.md — 身份解析、持久化状态机、必须维持的不变量
• storage-and-formats.md — 存储分层、快照契约、向前兼容纪律
• server-integration.md — 三档 Authority 集成、自动降级/升级、能力探测

algorithms/ — 算法原理

核心算法"怎么算的"：参数、公式、阈值。基于真实代码编写，并标注关键文件位置。

• retrieval.md — 三层混合检索：向量预筛 + 图扩散 + LLM 精排 + 多意图/DPP/残差
• extraction.md — LLM 提取管线：消息 → 结构化 → 图谱写入 → 时序边
• diffusion-and-dynamics.md — 图扩散（PEDSA）+ 混合评分 + 访问强化/衰减
• consolidation-and-compression.md — 记忆整合/去重 + 压缩遗忘 + 分层总结
• vector-and-embedding.md — 向量空间身份 + 批量 embedding + 维度门禁

features/ — 功能解析

每个面向用户的功能"做什么、怎么用、边界在哪"。

• memory-model.md — 节点类型、关系类型、主客观分层、故事时间线
• recall-cards.md — 持久召回卡片
• history-safety.md — 历史变动恢复、渲染限制保护、Restore Lock
• hide-and-render.md — 隐藏旧楼层与渲染限制
• ena-planner.md — ENA Planner
• native-acceleration.md — Native/WASM 灰度加速

contributing/ — 参与维护

怎么开发、怎么测、必须遵守的约定。

• development.md — 构建、测试、检查命令；分支工作流
• testing.md — 测试分类、ratchet 防线、依赖注入守卫
• conventions.md — 注入式控制器模式、必须保持的不变量

维护原则（重要）

文档最大的敌人是腐烂。本目录遵守三条防腐铁律：

1. 离代码越近，腐烂越慢。 单个函数的 API 细节留在模块头注释里（改代码自然会改它），不抄进这里。本目录只写"跨文件的算法原理、不变量、功能行为"。
2. 不写一改就过期的内容。 避免"某函数第几行做什么"这种描述；算法文档引用文件位置时，描述的是"哪个算法在哪个文件"，而非逐行。
3. 改了行为就更新对应文档。 算法参数、不变量、功能边界发生变化时，更新这里；纯重构（不改行为）通常不需要动文档。