| name | storage-design |
| description | 存储接口的设计原则、SessionMeta 与 TopologyNode 解耦、上下文槽位、单一 SessionStorage 接口。触发条件：理解或实现 SessionStorage / SessionTree。 |
核心原则
Session 是纯对话单元，不感知树结构。 数据职责切成两条独立的线：
SessionStorage — 单个 Session 的内容数据（消息、上下文槽位等），由 @stello-ai/session 定义SessionTree — 拓扑结构（节点关系、固化配置），由 @stello-ai/core 定义
两者由应用层各自实现并注入；常见做法是共享同一份持久化后端，但接口分离让 Session 层（运行单条对话）和 Orchestrator 层（管理整棵森林）的职责互不耦合。
单一 SessionStorage 接口
所有 Session（含 root）共用同一个接口。Root 没有特权方法——它就是一个 parentId === null 的普通 Session。
职责：
- Session 元数据 CRUD（
getSession / putSession / listSessions）
- L3 对话记录追加/查询/裁剪（
appendRecord / listRecords / trimRecords）
- 三个上下文槽位的读写（
getSystemPrompt/putSystemPrompt / getInsight/putInsight/clearInsight / getMemory/putMemory）
- 事务（
transaction(fn)）
批量收集由 StelloAgent.listSessionDigests() 提供——它在 orchestrator-facing SDK 上聚合 SessionTree.listAll() 与 SessionStorage.getMemory/getInsight，由应用层在 agent 顶层注入 storage: SessionStorage 来启用。
SessionMeta 与 TopologyNode 解耦
树状关系完全由 TopologyNode 维护，SessionMeta 不关心自己在树中的位置。
- SessionMeta（在
SessionStorage）：对话运行时数据（id、label、status、turnCount 等），无 parentId/children/depth
- TopologyNode（在
SessionTree）：纯树结构（id、parentId、children、refs、depth、index、label、sourceSessionId）
两种类型由两条独立接口提供。底层存储实现可以共享一张表/同一份 JSON，但消费侧（Session 层 vs 拓扑 / 前端）拿到的是经过职责裁剪的视图。
两个包的 SessionMeta
@stello-ai/session 和 @stello-ai/core 各有自己的 SessionMeta，字段集合不完全一致；持久化层（PG / FS）通常存超集，由各 adapter 按需投影。
上下文槽位
每个出现在 Session.send() 上下文中的元素都有对应的专用槽位（一对 get/put 方法），不复用通用键值：
| 槽位 | 写入者 | send() 消费 | 生命周期 |
|---|
systemPrompt | fork 合成链固化 / 应用层 | 每次 send 注入 | 持久 |
insight | 应用层（agent.putInsight） | 注入一次即 clear | 一次性 inbox |
memory | 应用层（consolidate 写入 / agent.putMemory） | 不进入 send 上下文 | 持久（供 orchestrator 反思） |
memory 是外部视角的槽位——它是 orchestrator 层（应用层）用来对 Session 做综合反思的输入，但不会注入 Session 自身的 LLM 上下文。Session 的 LLM 看不到自己的 memory。
数据流向
Session.send()
storage.getSystemPrompt → storage.getInsight → storage.listRecords → LLM → storage.appendRecord
↓
storage.clearInsight（若 insight 被消费）
Session.consolidate(fn)
storage.listRecords + storage.getMemory → fn → storage.putMemory
Engine.forkSession(options)
1. sessions.createSession({ parentId, label, sourceSessionId }) ← 拿到 ID
2. sessions.putConfig(childId, serializable) ← 固化 systemPrompt + skills
3. session.fork({ id: childId, context, prompt }) ← 创建 Session 实例
应用层反思层（自行实现，每 N 分钟 / on demand）
agent.listSessionDigests() → 收集所有 Session 的 {id, label, memory, insight}
→ 任意 LLM → 派生 per-target insight
→ agent.putInsight(targetId, content)
SessionTree 接口要点
createSession({ parentId?, label?, sourceSessionId? }) —— 唯一节点创建入口；parentId 缺省即建 root（parentId === null），多 root 合法listRoots() —— 列出所有 root，应用层据此显示森林getTree() —— 返回 SessionTreeNode[] 森林视图addRef(from, to) —— 跨树引用（非父子）getConfig / putConfig —— 持久化 SerializableSessionConfig（只含 systemPrompt / skills）
应用层实现策略
| 后端 | 推荐拆分 |
|---|
| 文件系统（NodeFS） | SessionTreeImpl + InMemoryStorageAdapter（demo 用法） |
| PostgreSQL | 一个 PG schema，两个 wrapper 类（一个实现 SessionStorage，一个实现 SessionTree） |
| 多租户 server | 同上，再加 space_id 维度 |
要点：两个接口的 id 必须语义一致（同一个 Session 的 SessionMeta.id === TopologyNode.id）。应用层在创建/删除 Session 时需保证两条线同步。
